Employees (Partial Update)
Description
Updates an existing Employee or creates a new one. If an identifier (UUID or External ID) is provided and it matches an existing Employee, an update is performed on the provided fields. If no matching Employee is found, a new one is created. Note: to clear field set value to string SET_AS_NULL
See the Aerial Spec for more details.
File Naming Convention
TGEN_employees_partialupdate_2026-08_<optionalSuffix>.csv
importType:partialupdateapiVersion:2026-08
Columns
Nested object fields are flattened into columns using dot notation (parent.child). Array fields are flattened using zero-based index notation, one element per column (field[0], field[1], and so on).
Note: A whole array cannot be passed in a single column: a literal value such as ['value-1','value-2'] will be rejected. To import multiple array elements, add one indexed column per element. Rows in the table below with type array describe the field as a whole and are not valid CSV column headers.
| Column Header | Description | Key Information | Type | Required |
|---|---|---|---|---|
externalId | Integrator provided unique identifier for the employee. | Max Length: 255 | string | No |
uuid | Unique Tulip identifier of the employee. Required for patching. | Max Length: 36 | string | No |
samlNameId | If using SSO for authentication against a third party system, set the login username in this field if different than the value set in externalId. | string | No | |
disabled | Boolean dictating if employee is disabled (true or false) | boolean | No | |
store | Unique Tulip identifier of the store the employee is associated with | Max Length: 36 | string | No |
displayName | Name that will be displayed for the employee | string | No | |
firstName | First name of the employee | Max Length: 255 | string | No |
lastName | Last name of the employee | Max Length: 255 | string | No |
emailAddress | Email address of the employee | Max Length: 255 | string | No |
image | Image associated with the employee | string | No | |
mobileNumber | Mobile number for the employee in E.164 standard | string | No | |
jobTitle | Job title of the employee | Max Length: 255 | string | No |
liveConnectAvailability | Boolean dictating whether live connect is available or not for the employee (true or false) | boolean | No | |
attributes | Attribute Values associated with this employee. Supports SET_AS_NULL. | Not a CSV column header. Pass each array element in its own indexed column (attributes[0], attributes[1], and so on). | mixed | No |
attributes[0] | Attribute Value, External ID, UUID or SET_AS_NULL | mixed | No | |
attributes[0].value | Value of the attribute, this will be any type casted to string but supports all basic types | mixed | Yes | |
attributes[0].name | External ID of the attribute | Max Length: 255 | string | Yes |
attributes[0].languageExternalId | External ID of the language, defaults to english | Max Length: 255 | string | Yes |
attributes[0].attributeId | Tulip ID of the Attribute | Min: 0 | integer | No |
attributes[0].description | Tulip Attribute description | Max Length: 255 | string | Yes |
attributes[0].type | Tulip Attribute Type | Allowed: string, boolean, integer, float | string | Yes |
orgAccess | The complete set of org-chart nodes (Division, Region, District, or Store) this employee has access to. Each entry grants access to the whole node including everything beneath it; the array replaces the employee’s existing assignment set. Supports SET_AS_NULL. | Not a CSV column header. Pass each array element in its own indexed column (orgAccess[0], orgAccess[1], and so on). | mixed | No |
orgAccess[0] | Org-chart node the employee has access to | mixed | No | |
orgAccess[0].type | The kind of node access is granted at | Allowed: Division, Region, District, Store | string | Yes |
orgAccess[0].uuid | Unique Tulip identifier of the node. One of uuid, externalId, or id is required. | string | No | |
orgAccess[0].externalId | External identifier of the node (store organization resource external ID, or store code for stores). One of uuid, externalId, or id is required. | Max Length: 255 | string | No |
orgAccess[0].id | Internal Tulip identifier of the node. One of uuid, externalId, or id is required. | integer | No | |
signature | Object containing the signature of the employee. Supports SET_AS_NULL. | mixed | No | |
signature.content | The signature of the employee | string | Yes | |
profile | Object containing the profile of the employee. Supports SET_AS_NULL. | mixed | No | |
profile.phoneNumber | The profile phone number of the employee in E.164 format | string | No | |
offlineNotificationConfig | Object containing the offline notification config of the employee. Supports SET_AS_NULL. | mixed | No | |
offlineNotificationConfig.forwardingNumber | Forwarding number for the employee in E.164 standard | string | No | |
offlineNotificationConfig.forwardingEnabled | Boolean dictating if employee has forwarding enabled (true or false) | boolean | No | |
offlineNotificationConfig.forwardAllEnabled | Boolean dictating if all messages should be forwarded to the employee (true or false) | boolean | No | |
offlineNotificationConfig.forwardLoggedOutEnabled | Boolean dictating if messages should be forwarded when employee is logged out (true or false) | boolean | No | |
authUser | Object containing the user of the employee | mixed | No | |
authUser.username | The username of the employee | string | Yes | |
authUser.password | For standard integrations, this field is used exclusively to set a temporary password during user creation; the password field is ignored when updating existing users. Unless configured otherwise, temporary passwords must be at least 12 characters long and must include one letter, one number, and one special character. Legacy configurations support ongoing (and non-temporary) password updates. | string | No | |
authUser.disabled | Boolean dictating if user is disabled (true or false) | boolean | No | |
authUser.roles | Array of role external ID’s | Not a CSV column header. Pass each array element in its own indexed column (authUser.roles[0], authUser.roles[1], and so on). | array | No |
authUser.roles[0] | Array element | string | No |
Sample CSV
See the following employees CSV sample file.
Note: The sample CSV may contain sample ID fields which reference other resources that do not match the data in your environment. You may omit any non-required fields from the sample CSV, reference the table above for required fields.