Onboarding

Creates or updates a user in one call: profile, role assignment, service-provider or location assignment, and technician setup when a technician role is included.

POST /fieldservicegateway/usermanagement/v3/onboarding

Send one user object, or an array of up to 10 users.

Asurion-serviceprovider values New and system are normalized before the call continues. Other headers are standard.

Request

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

User object

Field	Type	Required	Description
firstName	string	yes	1–100 characters
lastName	string	yes	1–100 characters
middleName	string	no	Up to 100 characters
contact	object	yes	Must include email
contact.email	array	yes	At least one email
contact.email[].type	string	yes	PERSONAL, WORK, or DEFAULT
contact.email[].address	string	yes	Email address
contact.email[].primary	boolean	yes	Whether this email is primary
contact.phone	array	no	Phone numbers
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
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
addresses	array	no	Home address only (type is HOME)
addresses[].addressLine1	string	yes, when an address is sent	Street line 1
addresses[].addressLine2	string	no	Street line 2
addresses[].city	string	yes, when an address is sent	City
addresses[].state	string	yes, when an address is sent	State
addresses[].postalCode	string	yes, when an address is sent	Postal code
addresses[].country	string	yes, when an address is sent	Country
profilePictureUrl	string	no	Profile image URL
employeeId	string	no	Employee id
externalReferenceNumber	string	no	External reference
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",
  "contact": {
    "email": [
      {
        "type": "WORK",
        "address": "user@example.com",
        "primary": true
      }
    ],
    "phone": [
      {
        "type": "MOBILE",
        "number": "5550100",
        "countryCode": "1",
        "primary": true
      }
    ]
  },
  "roles": ["Honeycomb:Technician"],
  "serviceProviderNumber": "10001",
  "serviceProviderLocationNumbers": ["20001"]
}

cURL

curl --request POST 'https://[BASE_URL]/fieldservicegateway/usermanagement/v3/onboarding' \
  --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",
    "contact": {
      "email": [
        {
          "type": "WORK",
          "address": "user@example.com",
          "primary": true
        }
      ],
      "phone": [
        {
          "type": "MOBILE",
          "number": "5550100",
          "countryCode": "1",
          "primary": true
        }
      ]
    },
    "roles": ["Honeycomb:Technician"],
    "serviceProviderNumber": "10001",
    "serviceProviderLocationNumbers": ["20001"]
  }'

A batch request is a JSON array of the same object. Maximum size is 10.

Response

The body is always:

{
  "results": []
}

Each item:

Field	Type	Description
index	number	Position in the request, starting at 0
email	string	Primary email used for that user
success	boolean	Whether that user completed onboarding
userNumber	number	Present when a user record exists
isNewUser	boolean	true when the user row was created on this call
error	string	Present when success is false

201 Created

Every user succeeded.

{
  "results": [
    {
      "index": 0,
      "email": "user@example.com",
      "success": true,
      "userNumber": 1001,
      "isNewUser": true
    }
  ]
}

207 Multi-Status

At least one user failed. Successful and failed items are returned together. The same status is used when every item fails.

{
  "results": [
    {
      "index": 0,
      "email": "user@example.com",
      "success": false,
      "userNumber": 1001,
      "error": "User exists and is deactivated"
    }
  ]
}

Item-level failures include:

error	When
Email is required	No primary email was found
Service provider not found	serviceProviderNumber does not exist
Service provider location(s) not found: ...	A location number does not exist
roleName must be in format "Application:RoleName"	A role string is not Application:RoleName
Role '<role>' does not exist	The role is not defined
User exists and is deactivated	The email or employee id matches an inactive user
User with this email already exists with a different employee ID	The email belongs to another employee id
Employee ID is already associated with a different user	The employee id belongs to a different active user

An existing active user with the same email and employee id is updated and returned as success.

Errors

Schema and unexpected failures use this body:

Field	Type	Description
success	boolean	false
error	string	Error message
code	string	Stable error code
details.fields	array	Field errors, when the failure is a validation error
details.fields[].field	string	Field name
details.fields[].message	string	What is wrong
details.fields[].code	string	Field error code
correlationId	string	Request correlation id
timestamp	string	ISO-8601 time

400 Bad Request

The body is not a user object or an array of 1–10 users, or a required field is missing or the wrong type.

{
  "success": false,
  "error": "One or more onboarding reference validations failed",
  "code": "VALIDATION_ERROR",
  "details": {
    "fields": [
      {
        "field": "roles",
        "message": "Invalid role format: technician",
        "code": "INVALID_FORMAT"
      }
    ]
  },
  "correlationId": "correlation-id",
  "timestamp": "2026-10-15T00:00:00.000Z"
}

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-15T00:00:00.000Z"
}