Create a User Identity

Create a new user identity

Creates a new user identity.

/user_identities/create

post

Creates a new user identity.

Authorizations

api_keypat_with_workspaceconsole_session_with_workspace

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

user_identity_keystring · min: 1 · nullableOptional

Unique key for the new user identity.

email_addressstring · email · nullableOptional

Unique email address for the new user identity.

phone_numberstring · nullableOptional

Unique phone number for the new user identity in E.164 format (for example, [phone]).

full_namestring · min: 1 · nullableOptional

Full name of the user associated with the new user identity.

acs_system_idsstring · uuid[]Optional

List of access system IDs to associate with the new user identity through access system users. If there's no user with the same email address or phone number in the specified access systems, a new access system user is created. If there is an existing user with the same email or phone number in the specified access systems, the user is linked to the user identity.

Responses

200

OK

application/json

400

Bad Request

401

Unauthorized

post

/user_identities/create

HTTPcURLJavaScriptPython

POST /user_identities/create HTTP/1.1
Host: connect.getseam.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 160

{
  "user_identity_key": "text",
  "email_address": "[email protected]",
  "phone_number": "text",
  "full_name": "text",
  "acs_system_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

{
  "user_identity": {
    "user_identity_id": "123e4567-e89b-12d3-a456-426614174000",
    "user_identity_key": "text",
    "email_address": "[email protected]",
    "phone_number": "text",
    "display_name": "text",
    "full_name": "text",
    "created_at": "2026-01-30T18:24:24.104Z",
    "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
    "errors": [
      {
        "created_at": "2026-01-30T18:24:24.104Z",
        "message": "text",
        "error_code": "issue_with_acs_user",
        "acs_user_id": "123e4567-e89b-12d3-a456-426614174000",
        "acs_system_id": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "warnings": [
      {
        "created_at": "2026-01-30T18:24:24.104Z",
        "message": "text",
        "warning_code": "being_deleted"
      }
    ],
    "acs_user_ids": [
      "123e4567-e89b-12d3-a456-426614174000"
    ]
  },
  "ok": true
}

Request

Specify the characteristics of the new user identity by including the corresponding parameters in the request body. Note that if you specify one or more of the user_identity_key, email_address, or phone_number, each of these values must be unique within your workspace.

Request Body Parameters

Parameter	Type	Description
user_identity_key	String Optional	Unique key for the user identity
email_address	String Optional	Unique email address for the user identity
phone_number	String Optional	Unique phone number for the user identity in E.164 format (for example, [phone])
full_name	String Optional	Full name of the user associated with the user identity

Sample Request

cURL (bash)

curl -X 'POST' \
  'https://connect.getseam.com/user_identities/create' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ${API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_identity_key": "jean_doe",
  "email_address": "[email protected]",
  "phone_number": "[phone]",
  "full_name": "Jean Doe"
}'

Go

Response

Returns a user_identity containing the following properties:

Property	Description
user_identity_id	ID of the user identity
user_identity_key	Unique key for the user identity
email_address	Unique email address for the user identity
display_name	Display name for the user identity
full_name	Full name of the user associated with the user identity
created_at	Date and time at which the user identity was created
workspace_id	ID of the workspace that contains the user identity

This response also includes a Boolean ok status indicator.

Sample Response

JSON

{
  "user_identity": {
    "user_identity_id": "48500a8e-5e7e-4bde-b7e5-0be97cae5d7a",
    "user_identity_key": "jean_doe",
    "email_address": "[email protected]",
    "phone_number": "[phone]",
    "display_name": "Jean Doe",
    "full_name": "Jean Doe",
    "created_at": "2024-01-11T05:37:50.264Z",
    "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be"
  },
  "ok": true
}