Create New User

What this endpoint does

Creates one user in the community selected by the Community API key. Use it for broker onboarding, federated/OAuth provisioning, local-password accounts, referral attribution, and initializing broker identifiers or other custom fields. Do not send communityId in the body.

INFO

Workflow

Create user -> read user

Quick start

{
  "firstname": "Ada",
  "lastname": "Lovelace",
  "username": "ada_lovelace_123",
  "displayname": "Ada Lovelace",
  "email": "ada@example.com",
  "accessLevel": 1,
  "joinServer": true,
  "sendEmail": false,
  "emailPassword": false,
  "externalId": "<brokerCustomerId>"
}

Authentication and permission

Send a server-side Community API key as Bearer <apiKey>. The key resolves the community and needs createUser. Never place an API key, broker credential, or login token in customFields.

Required fields are firstname, lastname, username, and accessLevel. A username cannot contain @. Email and username are normalized for duplicate checks.

Complete examples

Federated user: omit password and confirmPassword, use joinServer: true, and normally set sendEmail and emailPassword to false. Store the stable broker identity in externalId when the community has an active identifier field.

Custom-field identifier fallback: if externalId is not configured, send customFields: [{"fieldIdorName":"customerid","value":"<brokerCustomerId>"}]. fieldIdOrName is an accepted compatibility alias, but prefer fieldIdorName on this endpoint.

Referral: add "referral":"<referrerReferralValue>". The value is passed to the community's referral mapping. Referral processing is a follow-up effect, so a referral failure does not reverse an already-created user.

Local password: send matching password and confirmPassword, each 8-20 characters with a number and special character, and enable the configured account-email flow when the user must receive credentials. Passwords are write-only. This API never returns them.

Custom-field values preserve meaningful falsy data. JSON false, numerical 0, and an empty string for a valid multi-line field are not discarded.

Success and readback

{
  "status": "success",
  "code": "USER_CREATED",
  "message": "User created successfully",
  "data": {
    "userId": "3247779",
    "username": "ada_lovelace_123",
    "email": "ada@example.com",
    "communityMemberId": "<communityMemberObjectId>",
    "identifierKey": "customerid",
    "externalId": "<brokerCustomerId>",
    "created": true
  }
}

Treat data.userId as an opaque string. Save it, then confirm the result with POST /v1/users/info. The controller sends success only after its mandatory user and membership writes finish. Analytics, referral tracking, and email are follow-up effects and do not change an already-committed success into a failure.

CHECK

Readback

Run the follow-up read named above. Compare the returned identifiers and final stored values.

Errors and recovery

400 DUPLICATE_EMAIL or DUPLICATE_USERNAME: no new user was created. Lookup and reconcile the existing identity.

400 PASSWORD_MISMATCH or PASSWORD_MATCHES_USERNAME: fix the local-password request.

400 EXTERNAL_IDENTIFIER_REQUIRED, EXTERNAL_IDENTIFIER_NOT_CONFIGURED, or EXTERNAL_IDENTIFIER_CONFLICT: use the community's configured identifier contract.

400 INVALID_CUSTOM_FIELDS: inspect errorFields; do not remove valid false, 0, or empty multi-line values.

401 AUTHENTICATION_REQUIRED / 403 API_KEY_PERMISSION_DENIED: fix the key or permission.

409 DUPLICATE_EXTERNAL_ID: lookup the existing broker identity instead of creating another user.

500 USER_CREATION_RECONCILIATION_REQUIRED: the outcome is ambiguous. Stop automatic creation and reconcile using data.userId and the external identifier.

500 USER_CREATE_FAILED: an unexpected failure occurred; do not assume a timeout means nothing was saved.

Retry safety

WARNING

Retry rule

This endpoint does not currently accept an Idempotency-Key. After a timeout, do not blindly create again. First call POST /v1/users/info using the external identifier, email, or returned platform ID. Retry creation only after readback proves that no user was created.

Gotchas

Avoid this mistake

Next steps

Read the user

Read back with POST /v1/users/info. Use POST /v1/users/update for profile, role, or intentional identifier changes. Create field definitions before writing new custom-field values, then use the canonical user-first history endpoint for value updates.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

application/json

User created successfully. Use data.userId for follow-up reads and communityMemberId as the created community membership record.

Bodyapplication/json

curl --location 'https://api.returning.ai/v1/users' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "firstname": "Ada", "lastname": "Lovelace", "username": "ada_lovelace_123", "displayname": "Ada Lovelace", "email": "ada@example.com", "accessLevel": 1, "joinServer": true, "sendEmail": false, "emailPassword": false, "externalId": "broker-user-123" }'

{ "status": "success", "code": "USER_CREATED", "message": "User created successfully", "data": { "userId": "3247779", "username": "ada_lovelace_123", "email": "ada@example.com", "communityMemberId": "66f000000000000000000001", "identifierKey": "customerid", "externalId": "<brokerCustomerId-or-cognitoSub>", "created": true } }

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps

Request

Responses

Create New User

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Request

Responses

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps