How do I set up the WinTeam integration?

Last updated: October 16, 2026

Connect Onboarded to WinTeam so a new hire's onboarding data is sent into WinTeam. You'll add your credentials, choose which fields to collect, add WinTeam to a form, and review each submission from the integration.

Before you start

Admin access to your account's Integrations settings, and permission to build forms.
Your WinTeam Tenant ID.
Your WinTeam APIM key (the API subscription key for your WinTeam account).
The list of WinTeam fields you want to send, and the values WinTeam accepts for any dropdown-style field.

Install the integration

Open the marketplace. From your account, open the Integration Marketplace and choose WinTeam.
Install. Install the app. WinTeam now appears in your integrations.

Connect your WinTeam credentials

Open the settings. Open the WinTeam integration and go to the Settings tab. Step 1 is Credentials.
Enter your credentials. Fill in your Tenant ID and API key. The key is stored encrypted and is never shown again.
Save. Select Save & Continue.

To change your Tenant ID later, leave the API key blank and select Save. Your existing key is kept.

Map your fields

Step 2, Fields Mapping, unlocks once an APIM key has been saved. This is where you decide which WinTeam fields Onboarded collects and how each answer is sent. The first time, select Initialize Field Mapping.

Field mapping has two tabs: Code Lists and Field Configs. Build your code lists first, so they're available when you add the fields that use them.

You can add and edit fields and code lists only on a draft version. Forms use the published version, so nothing you change here affects live forms until you publish.

Add a code list

A code list is a fixed set of choices for a dropdown field, for example marital status or employment type. Each choice pairs a code that WinTeam understands with a label that people see.

Open the Code Lists tab and select Add Code List.
Fill in the list details:
Field
What to enter
Name
A friendly name that you'll pick from later, such as Marital Status.
Key
A short identifier for the list, such as marital_status. Use lowercase letters and underscores.
Select Add Item for each choice, enter its Code and Label, and select the check mark to keep it. Use the pencil icon to edit an item.
Item field
What to enter
Code
The exact value WinTeam expects, such as S.
Label
The text people see in the dropdown, such as Single.
Select Save.

Field	What to enter
`Name`	A friendly name that you'll pick from later, such as `Marital Status`.
`Key`	A short identifier for the list, such as `marital_status`. Use lowercase letters and underscores.

Item field	What to enter
`Code`	The exact value WinTeam expects, such as `S`.
`Label`	The text people see in the dropdown, such as `Single`.

When someone picks a choice, they see its label and Onboarded sends its code to WinTeam.

Add a field

Each field config describes one value that is sent to WinTeam.

Open the Field Configs tab and select Add Field Config.

Fill in the dialog. Field Key, Label, Type and Assignee are required.

Field	What to enter
`Field Key`	The name of the field in WinTeam, exactly as WinTeam's API expects it, such as `firstName`. For a value that sits inside a group, separate the parts with a dot, such as `employee.address.street`.
`Label`	The name people see on the form, such as `First Name`.
`Type`	The kind of answer: `string` (text), `number`, `date` (date picker), `boolean` (true or false), `option` (pick from a code list), or `selector`.
`Code List`	Only used when `Type` is `option`. Choose the code list you built above. It stays unavailable for other types.
`Assignee`	Who fills the field in: `Employee` on the employee page, or `Employer` on the employer page.
`Field Mapping`	Optional. Where Onboarded should pre-fill the answer from, such as `personal.employee_id`. When Onboarded already has the value, the field arrives filled in and the person completing the form can't change it. Leave it blank to have the person enter the answer.

Optionally add value mappings (see the next section), then select Add Field Config.

Social Security numbers are cleaned up automatically. Any dashes or spaces are removed before the value is sent to WinTeam.

Translate values with value mappings

Use value mappings when the answer people give doesn't match the value WinTeam expects, for example the form says Single but WinTeam wants S. Each rule swaps one input value for one output value just before the record is sent.

In the field config dialog, find Value Mappings and select Add Rule.
Enter the input value, which is the answer as Onboarded has it, and the output value, which is what WinTeam should receive. Select the check mark to keep the rule.
Repeat for each value you need to translate. Select the X on a rule to remove it.

Input value	Output value
`Single`	`S`
`Married`	`M`

These values are only an example. Use the values your WinTeam account accepts.

An input value has to match the answer exactly, including capitalization and spaces. If an answer doesn't match any rule, it is sent to WinTeam unchanged.

For a dropdown field, you usually don't need value mappings. Put the WinTeam value in the code list item's Code, and Onboarded sends it for you. Use value mappings for text, date and true or false answers that need translating.

Publish your mapping

When your code lists and fields are ready, select Publish Version.
To change a published mapping later, select New Version to create a draft copy, make your edits, then select Publish Version again.

Add WinTeam to a form

Open the Form Builder and create or edit a form.
Add the employee step. On the employee page, add an integration field and choose WinTeam. It shows the fields you assigned to Employee.
Add the employer step. On the employer page, add an integration field and choose WinTeam. It shows the fields you assigned to Employer.
Link the form. Open the Forms tab in the WinTeam integration, choose the WinTeam form and the policy it falls under, and set it up.

How a new hire reaches WinTeam

The employee completes their WinTeam page first, then your team completes the employer page. Once both are submitted, Onboarded creates the employee in WinTeam.

Open the Records tab to follow each submission. A submission moves from pending to employee_submitted, then employer_submitted, and finishes as success. If WinTeam rejects it, the status is failed and the WinTeam error message is shown.

Verify

The integration is wired up correctly when a test task shows the WinTeam fields on both the employee and employer pages, and the submission reaches success in the Records tab.

If a submission is failed, read the message on the record. A message naming a field usually means a Field Key that WinTeam doesn't recognize or a value WinTeam doesn't accept, so check that field's key, code list and value mappings. If WinTeam can't be reached or authentication fails, check your Tenant ID and API key in Settings.