Create New User

Creates a user in the community resolved from the Community API key. Use this for broker-driven onboarding, OAuth/federated provisioning, or pre-provisioning users before they open the Returning.AI widget.

The API key determines the community. Do not pass communityId in the request body.

For OAuth/federated users, omit password and confirmPassword, set joinServer: true, and set sendEmail: false / emailPassword: false.

Endpoint metadata:

Required permission: createUser

Authentication:

Send a Community API key in the Authorization header using Bearer <apiKey>.

The API key resolves the community. Do not send communityId in the body.

The key must include the createUser permission.

OAuth/federated provisioning:

Do not send password or confirmPassword.

Use joinServer: true when the user should immediately become a full community member.

Use sendEmail: false and emailPassword: false because the broker or identity provider owns sign-in.

Store the broker's stable user identifier in a configured custom field, commonly customerid.

Example - OAuth/federated user:

{
  "firstname": "Ada",
  "lastname": "Lovelace",
  "username": "ada_lovelace_123",
  "displayname": "Ada Lovelace",
  "email": "ada@example.com",
  "accessLevel": 1,
  "joinServer": true,
  "sendEmail": false,
  "emailPassword": false,
  "customFields": [
    {
      "fieldIdorName": "customerid",
      "value": "<brokerCustomerId-or-cognitoSub>"
    }
  ]
}

For OAuth/federated users, do not send password or confirmPassword.

Put the broker's stable user identifier in the configured custom field. In many broker integrations this field is named customerid; the exact field name is community-specific.

Use the same identifier later when resolving or authenticating the user through the broker/widget integration.

Example - referral linkage during provisioning:

{
  "firstname": "Grace",
  "lastname": "Hopper",
  "username": "grace_hopper_123",
  "displayname": "Grace Hopper",
  "email": "grace@example.com",
  "accessLevel": 1,
  "joinServer": true,
  "sendEmail": false,
  "emailPassword": false,
  "customFields": [
    {
      "fieldIdorName": "customerid",
      "value": "<newUserBrokerCustomerId>"
    }
  ],
  "referral": "<referrerReferralValue>"
}

referral should contain the value used by the community's custom referral-link mapping. For example, if the referral link maps referral_id to customerid, pass the referrer's customerid value.

If the referral mapping is not configured, if no matching referrer is found, or if multiple users match the referral value, user creation can still succeed but referral tracking may be skipped.

Example - local password user:

{
  "firstname": "John",
  "lastname": "Doe",
  "username": "john_doe_123",
  "displayname": "John Doe",
  "email": "john@example.com",
  "password": "StrongPass1!",
  "confirmPassword": "StrongPass1!",
  "accessLevel": 1,
  "joinServer": true,
  "sendEmail": true,
  "emailPassword": true,
  "emailTemplate": "0"
}

Use the password example only for users who should sign in with a Returning.AI local password. Brokers using OAuth or a federated identity provider should use the no-password example above.

Optional externalId shortcut:

Some communities can use top-level externalId as a shortcut for the active user identifier field. This only works when the community has an active user identifier field configured. If the community does not have that configuration, use customFields instead.

{
  "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-or-cognitoSub>"
}

If externalId is sent for a community without an active identifier field, the API returns:

{
  "status": "fail",
  "code": "EXTERNAL_IDENTIFIER_NOT_CONFIGURED",
  "message": "externalId requires an active user identifier field",
  "data": {
    "externalId": "<brokerCustomerId-or-cognitoSub>",
    "created": false
  }
}

Success response fields:

Use data.userId as the created Returning.AI user ID for follow-up reads.

communityMemberId is the community membership record created for this user.

identifierKey and externalId are included when the create request resolved an active external identifier.

Recommended provisioning flow:

Check whether the user already exists with POST /v1/users/filter.

If no user exists, call POST /v1/users.

Use data.userId from the create response to confirm the user with POST /v1/users/info.

After readback succeeds, mint or issue any broker/widget session token that depends on this user identifier.

Check before create:

{
  "filter": {
    "customerid": {
      "eq": "<brokerCustomerId-or-cognitoSub>"
    }
  },
  "fields": ["username", "email", "customerid", "join_date"]
}

Confirm readback:

{
  "idOrEmail": "123456",
  "customFields": ["customerid"]
}

Expected readback:

{
  "status": "success",
  "data": {
    "userId": "123456",
    "username": "ada_lovelace_123",
    "roles": ["@all"],
    "customFields": {
      "customerid": "<brokerCustomerId-or-cognitoSub>"
    }
  }
}

If the user is needed immediately after creation, keep a short retry around the readback step, for example 250ms, 500ms, then 1000ms.

Related endpoints:

POST /v1/users/filter - check whether a user already exists by custom field before creating.

POST /v1/users/info - confirm the created user and custom fields before issuing a widget/embed token.

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, "customFields": [ { "fieldIdorName": "customerid", "value": "<brokerCustomerId-or-cognitoSub>" } ] }'

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

Request

Responses