API Endpoints
ClayHR

Create or Update user

post
https://acmecompany.bizmerlin.net/rm/api/user/completeUserDetails

Creates a user, or updates the user if a match is found. The same call can also save addresses, education, employment history, contacts, compensation, custom field values and reporting managers.

Matching
The first identifier sent is used, in this order: userId → empId → email → guid. If a user matches, it is updated otherwise a new user is created.

Required fields

  • Create: firstName and email.
  • Update: one identifier and firstName.

Notes

  • On update, only the fields you send are changed.
  • Send a unique extAppUID on each list item so repeat calls update it instead of adding a duplicate.
  • Dates use yyyy-MM-dd. countryCode is a 2-letter ISO code.
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
integer

Identifier (priority 1). ID of an existing user to update.

string

Identifier (priority 2). Employee ID. On create it may be replaced by an auto-generated ID if employee ID generation is enabled. On update it is applied only for Admin API users.

string
required

Identifier (priority 3). Work email of the user. Required when creating.

string

Identifier (priority 4). The unique system generated ID of an existing user. Used for matching only.

string

Salutation, e.g. Mr., Ms., Dr.

string
required

First name of the user. Also used as the short name (first 15 characters) when shortName is not sent.

string

Middle name of the user

string

Last name of the user. Strongly recommended when creating.

string

Second last name of the user

string

Family suffix, e.g. Jr.

string

Short display name. Defaults to firstName (max 15 characters).

string

Phone number of the user

string

Cell phone number of the user

string

Job title of the user

date

Start date (yyyy-MM-dd)

date

End date (yyyy-MM-dd)

date

Date of birth (yyyy-MM-dd)

string

Gender of the user. Applied on update only.

string
enum

A = Active, F = Future, I = Inactive. Applied on update only, and only for Admin API users. New users are always created as Active.

Allowed:
integer

ID of an existing location. Takes priority over locationName.

string

Name of an existing location (used when locationId is not sent).

integer

ID of an existing department / org unit.

integer

ID of an existing user profile. On create, the company's default profile (if configured) is used instead.

reportsToEmail
array of strings

Emails of existing users this user reports to. Unknown emails are ignored.

reportsToEmail
customFieldValues
object

Custom field values, keyed by the custom field code configured for Users. Values are saved as text exactly as sent. Use this for text fields, dropdown fields are not supported. Unknown codes are ignored.

addressList
array of objects

Addresses of the user.

addressList
educationList
array of objects

Education details of the user.

educationList
employmentList
array of objects

Previous employment details of the user.

employmentList
contactList
array of objects

Dependents and emergency contacts of the user.

contactList
financialList
array of objects

Compensation / financial records of the user.

financialList
Headers
int32
required

The ID of the user to authenticate.

string
required

The API key of the user to authenticate.

Responses

Updated 5 days ago

Language
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 5 days ago