User provisioning

Creates a user when you may not have an email. Same idea as onboarding: profile, roles, and a service provider or location. Send one user, or up to 10.

POST /fieldservicegateway/usermanagement/v3/user-provisioning

Request

The body is one user object or an array of user objects.

Field	Type	Required	Description
firstName	string	yes	1–100 characters
lastName	string	yes	1–100 characters
middleName	string	no	Up to 100 characters
externalReferenceNumber	string	yes	Id from the calling system. Required even when email is omitted
roles	string[]	yes	At least one role, each in Application:RoleName form
serviceProviderNumber	string	one of these is required	Service provider to assign
serviceProviderLocationNumbers	string[]	one of these is required	Location numbers to assign
contact	object	no	Email and phone. Omit when there is no contact
contact.email[].type	string	yes, when email is sent	PERSONAL, WORK, or DEFAULT
contact.email[].address	string	yes, when email is sent	Email address
contact.email[].primary	boolean	yes, when email is sent	Whether this email is primary
contact.phone[].type	string	yes, when phone is sent	HOME, MOBILE, or WORK
contact.phone[].number	string	yes, when phone is sent	Phone number
contact.phone[].countryCode	string	yes, when phone is sent	Country calling code
contact.phone[].primary	boolean	yes, when phone is sent	Whether this phone is primary
addresses	array	no	Home address only (type is HOME)
profilePictureUrl	string	no	Profile image URL
employeeId	string	no	Employee id
sbUsername	string	no	ServiceBench username
userAttributes	array	no	Extra attributes. Each item needs name (1–50 characters) and value

password is not accepted.

Example

{
  "firstName": "Ada",
  "lastName": "Lovelace",
  "externalReferenceNumber": "EXT-1001",
  "roles": ["Honeycomb:Technician"],
  "serviceProviderNumber": "10001"
}

cURL

curl --request POST 'https://[BASE_URL]/fieldservicegateway/usermanagement/v3/user-provisioning' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: {{x-api-key}}' \
  --header 'Authorization: {{Authorization}}' \
  --header 'Asurion-correlationid: correlation-id' \
  --header 'Asurion-enduser: end-user' \
  --header 'Asurion-sourcesystem: source-system' \
  --header 'Asurion-serviceprovider: company-id' \
  --header 'Asurion-client: default' \
  --data '{
    "firstName": "Ada",
    "lastName": "Lovelace",
    "externalReferenceNumber": "EXT-1001",
    "roles": ["Honeycomb:Technician"],
    "serviceProviderNumber": "10001"
  }'

Response

The body is always { "results": [] }.

Field	Type	Description
index	number	Position in the request, starting at 0
email	string	Primary email, or empty when none was sent
success	boolean	Whether that user was provisioned
userNumber	number	Present when a user record exists
isNewUser	boolean	true when the user was created on this call
error	string	Present when success is false
code	string	Present on some item failures

201 Created

Every user succeeded.

{
  "results": [
    {
      "index": 0,
      "email": "",
      "success": true,
      "userNumber": 1001,
      "isNewUser": true
    }
  ]
}

207 Multi-Status

At least one user failed. Successful and failed items are returned together.

{
  "results": [
    {
      "index": 0,
      "email": "",
      "success": false,
      "error": "externalReferenceNumber is required"
    }
  ]
}

Errors

400 Bad Request

The body is not a user object or an array of 1–10 users.

{
  "error": "request body is invalid"
}

An empty array, or an array larger than 10, returns 400 with { "results": [] }.

500 Internal Server Error

{
  "success": false,
  "error": "Internal server error",
  "code": "INTERNAL_ERROR",
  "correlationId": "correlation-id",
  "timestamp": "2026-10-16T00:00:00.000Z"
}