Create User

POST/users

Caller

Key	Supported users
Company-scoped	Hirer company and project users
Agency-scoped	Agency Admin and Agency Staff users

Summary

Creates a new user account. The account starts active and unverified. Existing emails are rejected; this endpoint does not attach an existing user to another company or agency.

Set notifyUser: true to send the account invitation, using SSO instructions where applicable. It defaults to false. If invitation delivery fails after account creation, the endpoint returns 500; check the user in the portal before retrying.

Request Fields

Membership fields accept ObjectIds or references returned by the corresponding read endpoints.

Field	Type	Required	Description
firstName	string	Yes	First name
lastName	string	Yes	Last name
email	string	Yes	Valid, unique email; hirer SSO domain and exception rules apply
phone	string	No	Phone number
countryCode	string	No	Telephone dialling code
jobTitle	string	No	Job title
role	string	Yes	companyAdmin, companyFinance, projectAdmin, projectFinance, projectApprover, projectRequestor, ldAdmin, or ldUser
tags	object[]	No	Project-user tags: each item contains a tag ObjectId and an optional company ObjectId. Get tag IDs from Get Company Tags with resourceType=user; mandatory-tag rules apply
approvalStages	object[]	No	One item with a company ObjectId and integer stage (1–4); the stage must be configured for that company and the role must be projectApprover
companyRoleId	string	No	Company role ObjectId from Get Company Custom Roles; requires companyRoleCompanyId; assignment permissions and base-role compatibility apply
companyRoleCompanyId	string	When supplying companyRoleId	ObjectId of an assigned company within the key scope
company	string or string[]	For company roles	One or more companies within the key scope
project	string[]	For project roles	All projects must belong to one scoped company
labourDesk	string	For agency roles	One agency within the key scope
notifyUser	boolean	No	Send an invitation; defaults to false

Supply the membership field appropriate to the role. Project requests may also supply the matching company.

Request Examples

Replace example IDs with records available to your key and use a unique email address for each new account.

Company finance user

Assign the user to a company and send an invitation. Use company for companyAdmin and companyFinance roles.

{
  "firstName": "Jamie",
  "lastName": "Morgan",
  "email": "jamie@example.com",
  "role": "companyFinance",
  "company": "507f1f77bcf86cd799439011",
  "phone": "7700900123",
  "countryCode": "+44",
  "jobTitle": "Finance Manager",
  "notifyUser": true
}

Project requestor

A minimal project-user request. All selected projects must belong to the same company. Omitting notifyUser creates the account without sending an invitation.

{
  "firstName": "Alex",
  "lastName": "Taylor",
  "email": "alex@example.com",
  "role": "projectRequestor",
  "project": ["507f1f77bcf86cd799439016"]
}

Project user with tags

Retrieve user tag IDs from Get Company Tags using resourceType=user. Each tag must belong to the selected projects’ company. The company inside each tag item is optional for creation because the projects identify the company.

{
  "firstName": "Sam",
  "lastName": "Patel",
  "email": "sam@example.com",
  "role": "projectRequestor",
  "project": ["507f1f77bcf86cd799439016"],
  "tags": [
    {
      "tag": "507f1f77bcf86cd799439019",
      "company": "507f1f77bcf86cd799439011"
    }
  ],
  "notifyUser": true
}

Project approver with an approval stage

Assign an approver to stage 2. The stage must be configured for the selected projects’ company. approvalStages accepts one item and applies only to projectApprover users.

{
  "firstName": "Jordan",
  "lastName": "Reed",
  "email": "jordan@example.com",
  "role": "projectApprover",
  "project": ["507f1f77bcf86cd799439016"],
  "approvalStages": [
    {
      "company": "507f1f77bcf86cd799439011",
      "stage": 2
    }
  ],
  "notifyUser": true
}

Project user with a custom role

Retrieve the custom role from Get Company Custom Roles. Set role to its returned base role and companyRoleId to its returned id. This example assumes a custom role with base role projectRequestor; companyRoleCompanyId must be the selected projects’ company ObjectId.

{
  "firstName": "Casey",
  "lastName": "Green",
  "email": "casey@example.com",
  "role": "projectRequestor",
  "project": ["507f1f77bcf86cd799439016"],
  "companyRoleId": "507f1f77bcf86cd799439050",
  "companyRoleCompanyId": "507f1f77bcf86cd799439011",
  "notifyUser": true
}

Custom-role approver with tags and an approval stage

Combine a custom role, user tags and an approval stage in one request. This example assumes the custom role has base role projectApprover and stage 2 is configured. The custom role, tags and approval stage must all belong to the selected projects’ company.

{
  "firstName": "Riley",
  "lastName": "Clarke",
  "email": "riley@example.com",
  "role": "projectApprover",
  "project": ["507f1f77bcf86cd799439016"],
  "tags": [
    {
      "tag": "507f1f77bcf86cd799439019",
      "company": "507f1f77bcf86cd799439011"
    }
  ],
  "approvalStages": [
    {
      "company": "507f1f77bcf86cd799439011",
      "stage": 2
    }
  ],
  "companyRoleId": "507f1f77bcf86cd799439051",
  "companyRoleCompanyId": "507f1f77bcf86cd799439011",
  "notifyUser": true
}

Agency staff user

Use an agency-scoped key and labourDesk for ldUser or ldAdmin users. Company custom roles, project-user tags and approval stages do not apply to agency users.

{
  "firstName": "Taylor",
  "lastName": "Jones",
  "email": "taylor@agency.example",
  "role": "ldUser",
  "labourDesk": "507f1f77bcf86cd799439017",
  "phone": "7700900456",
  "countryCode": "+44",
  "jobTitle": "Recruitment Consultant",
  "notifyUser": true
}

Response

Returns HTTP 200 with a public profile. Passwords, reset tokens, MFA credentials, preferences and private account settings are excluded.

Field	Type	Description
success	boolean	true
data	object	Show child attributes id (string): user ObjectId reference (string): user reference firstName (string): first name lastName (string): last name email (string): email phone (string, optional): phone number countryCode (string, optional): dialling code jobTitle (string, optional): job title role (string): base role active (boolean): active status verified (boolean): verification status
meta	object	Empty object

Errors

HTTP status	Cause
400	Invalid or unsupported fields, duplicate email, SSO-domain rejection, or workflow restriction
401	Missing or invalid API key
403	Missing write:users, inactive or unverified owner, or insufficient management permissions
404	User or membership not found within the key scope
429	Rate limit exceeded
500	User write or invitation delivery failed