Bulk upsert users

post

https://example.com/v4/suite/users/bulk

Accepts a batch of user upsert records and processes them asynchronously.
Existing users are matched by import key or username:
records without a matching user are created, records with a matching user are updated.
Partial success is allowed: individual records may fail validation without failing the
whole batch - a rejected record is recorded against the job rather than stopping the rest.
The response contains only a job reference. The job's overall status and rolled-up counts
are retrieved via GET /v4/suite/users/jobs({jobId}), and per-record outcomes via
GET /v4/suite/users/jobs({jobId})/users.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

A batch of user upsert records to be processed asynchronously. Each item follows the
same schema as the single-user POST /v4/suite/users request.

Create or replace user payload. If both startDate and leaveDate are provided, startDate must be earlier than leaveDate.

username

string

required

length between 1 and 100

^\S+$

givenName

string

required

length between 1 and 50

familyName

string

required

length between 1 and 50

preferredName

string

dateOfBirth

date

Date of birth in YYYY-MM-DD format

emailAddress

string

length ≤ 256

ccEmailAddress

string

length ≤ 256

mobileNumber

string

culture

string

enum

department

string

division

string

companyName

string

managerType

string

preferredTrainingLocation

string

location

string

region

string

roles

object

costCenter

string

payGrade

string

payrollNumber

string

contractType

string

employeeCategory

string

isEnabled

boolean

required

startDate

date

Start date of employment in YYYY-MM-DD format

leaveDate

date

End date of employment in YYYY-MM-DD format

isAbsent

boolean

isFireWarden

boolean

isFirstAider

boolean

importKey

string

required

length ≤ 256

brandId

uuid | null

The ID of the brand to assign to the user. Omit or set to null to use the system default.

primaryJobProfileId

uuid | null

The ID of the primary job profile to assign to the user. Omit or set to null to leave the user with no primary job profile.

primaryGroupId

uuid | null

The ID of the group to set as the user's primary group. Omit or set to null to leave unset. Groups are also how manager hierarchy is modelled: each group has a managerId, and a user's manager is the manager of their primary group. This is the usual way to set a user's manager - resolve the group's ID by name first with GET /v4/suite/groups?$filter=title eq 'YOUR-GROUP'.

additionalJobProfileIds

array of uuids | null

The IDs of the user's job profiles other than the primary. Replaces the collection entirely - any job profile not listed is unassigned. Omit it, or send null or an empty array, to leave the user with no additional job profiles: PUT replaces the whole resource, so an omitted collection is a removal rather than "leave unchanged". No ID may refer to the user's primary job profile, and no ID may appear more than once. To reference a job profile by code, resolve it to an ID first with GET /v4/suite/job-profiles?$filter=code eq 'YOUR-CODE'.

additionalJobProfileIds

userInformationFields

object

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Language

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

application/problem+json

202Bulk upsert job accepted for asynchronous processing

400Bad Request

401Unauthorized - Authentication required

403Forbidden - Insufficient permissions

500Internal Server Error