Create a User Identity

• Request Parameters

• Response

Creates a new user identity.

JavaScript

Creates a new user identity. By specifying the desired acs_system_id, this operation also creates an access system user for the specified access system if this user does not already exist.

Code:

await seam.userIdentities.create({
  user_identity_key: "61c6c8ec-21ac-4d1d-be02-688889c66d8c",
  email_address: "[email protected]",
  phone_number: "[phone]",
  full_name: "Jane Doe",
  acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"],
});

Output:

{
  "created_at": "2025-06-16T16:54:17.946546Z",
  "display_name": "Jane Doe",
  "email_address": "[email protected]",
  "errors": [],
  "full_name": "Jane Doe",
  "phone_number": "[phone]",
  "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
  "user_identity_key": "jane_doe",
  "warnings": [],
  "workspace_id": "b7e0a4e0-1044-4319-9a0b-42b642b68c7f"
}

cURL

Creates a new user identity. By specifying the desired acs_system_id, this operation also creates an access system user for the specified access system if this user does not already exist.

Code:

curl --include --request POST "https://connect.getseam.com/user_identities/create" \
  --header "Authorization: Bearer $SEAM_API_KEY" \
  --json @- <<EOF
{
  "user_identity_key": "61c6c8ec-21ac-4d1d-be02-688889c66d8c",
  "email_address": "[email protected]",
  "phone_number": "[phone]",
  "full_name": "Jane Doe",
  "acs_system_ids": [
    "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  ]
}
EOF

Output:

{
  "user_identity": {
    "created_at": "2025-06-16T16:54:17.946546Z",
    "display_name": "Jane Doe",
    "email_address": "[email protected]",
    "errors": [],
    "full_name": "Jane Doe",
    "phone_number": "[phone]",
    "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "user_identity_key": "jane_doe",
    "warnings": [],
    "workspace_id": "b7e0a4e0-1044-4319-9a0b-42b642b68c7f"
  }
}

Python

Creates a new user identity. By specifying the desired acs_system_id, this operation also creates an access system user for the specified access system if this user does not already exist.

Code:

seam.user_identities.create(
    user_identity_key="61c6c8ec-21ac-4d1d-be02-688889c66d8c",
    email_address="[email protected]",
    phone_number="[phone]",
    full_name="Jane Doe",
    acs_system_ids=["c359cba2-8ef2-47fc-bee0-1c7c2a886339"],
)

Output:

UserIdentity(
    created_at="2025-06-16T16:54:17.946546Z",
    display_name="Jane Doe",
    email_address="[email protected]",
    errors=[],
    full_name="Jane Doe",
    phone_number="[phone]",
    user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b",
    user_identity_key="jane_doe",
    warnings=[],
    workspace_id="b7e0a4e0-1044-4319-9a0b-42b642b68c7f",
)

Ruby

Creates a new user identity. By specifying the desired acs_system_id, this operation also creates an access system user for the specified access system if this user does not already exist.

Code:

seam.user_identities.create(
  user_identity_key: "61c6c8ec-21ac-4d1d-be02-688889c66d8c",
  email_address: "[email protected]",
  phone_number: "[phone]",
  full_name: "Jane Doe",
  acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"],
)

Output:

{
  "created_at" => "2025-06-16T16:54:17.946546Z",
  "display_name" => "Jane Doe",
  "email_address" => "[email protected]",
  "errors" => [],
  "full_name" => "Jane Doe",
  "phone_number" => "[phone]",
  "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
  "user_identity_key" => "jane_doe",
  "warnings" => [],
  "workspace_id" => "b7e0a4e0-1044-4319-9a0b-42b642b68c7f",
}

PHP

Creates a new user identity. By specifying the desired acs_system_id, this operation also creates an access system user for the specified access system if this user does not already exist.

Code:

$seam->user_identities->create(
    user_identity_key: "61c6c8ec-21ac-4d1d-be02-688889c66d8c",
    email_address: "[email protected]",
    phone_number: "[phone]",
    full_name: "Jane Doe",
    acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"]
);

Output:

[
    "created_at" => "2025-06-16T16:54:17.946546Z",
    "display_name" => "Jane Doe",
    "email_address" => "[email protected]",
    "errors" => [],
    "full_name" => "Jane Doe",
    "phone_number" => "[phone]",
    "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "user_identity_key" => "jane_doe",
    "warnings" => [],
    "workspace_id" => "b7e0a4e0-1044-4319-9a0b-42b642b68c7f",
];

Seam CLI

Creates a new user identity. By specifying the desired acs_system_id, this operation also creates an access system user for the specified access system if this user does not already exist.

Code:

seam user-identities create --user_identity_key "61c6c8ec-21ac-4d1d-be02-688889c66d8c" --email_address "[email protected]" --phone_number "[phone]" --full_name "Jane Doe" --acs_system_ids ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"]

Output:

{
  "created_at": "2025-06-16T16:54:17.946546Z",
  "display_name": "Jane Doe",
  "email_address": "[email protected]",
  "errors": [],
  "full_name": "Jane Doe",
  "phone_number": "[phone]",
  "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
  "user_identity_key": "jane_doe",
  "warnings": [],
  "workspace_id": "b7e0a4e0-1044-4319-9a0b-42b642b68c7f"
}

Authentication Methods

• API key

• Personal access token Must also include the seam-workspace header in the request.

To learn more, see Authentication.

Request Parameters

acs_system_ids Array of UUIDs

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.

---

email_address String

Unique email address for the new user identity.

---

full_name String

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

---

phone_number String

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

---

user_identity_key String

Unique key for the new user identity.

---

Response

user_identity

JSON

{
  "created_at": "2025-06-16T16:54:17.946546Z",
  "display_name": "Jane Doe",
  "email_address": "[email protected]",
  "errors": [],
  "full_name": "Jane Doe",
  "phone_number": "[phone]",
  "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
  "user_identity_key": "jane_doe",
  "acs_user_ids": ["0fc82df4-391b-4d00-a234-86378f1c3952"],
  "warnings": [],
  "workspace_id": "b7e0a4e0-1044-4319-9a0b-42b642b68c7f"
}