# Create a User Identity * [Request Parameters](#request-parameters) * [Response](#response) Creates a new [user identity](https://docs.seam.co/latest/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity). {% tabs %} {% tab title="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:** ```javascript await seam.userIdentities.create({ user_identity_key: "61c6c8ec-21ac-4d1d-be02-688889c66d8c", email_address: "jane@example.com", phone_number: "+15551234567", full_name: "Jane Doe", acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"], }); ``` **Output:** ```javascript { "created_at": "2025-06-16T16:54:17.946546Z", "display_name": "Jane Doe", "email_address": "jane@example.com", "errors": [], "full_name": "Jane Doe", "phone_number": "+15551234567", "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", "user_identity_key": "jane_doe", "warnings": [], "workspace_id": "b7e0a4e0-1044-4319-9a0b-42b642b68c7f" } ``` {% endtab %} {% tab title="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 curl --include --request POST "https://connect.getseam.com/user_identities/create" \ --header "Authorization: Bearer $SEAM_API_KEY" \ --json @- < "2025-06-16T16:54:17.946546Z", "display_name" => "Jane Doe", "email_address" => "jane@example.com", "errors" => [], "full_name" => "Jane Doe", "phone_number" => "+15551234567", "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", "user_identity_key" => "jane_doe", "warnings" => [], "workspace_id" => "b7e0a4e0-1044-4319-9a0b-42b642b68c7f", } ``` {% endtab %} {% tab title="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:** ```php $seam->user_identities->create( user_identity_key: "61c6c8ec-21ac-4d1d-be02-688889c66d8c", email_address: "jane@example.com", phone_number: "+15551234567", full_name: "Jane Doe", acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"], ); ``` **Output:** ```php [ "created_at" => "2025-06-16T16:54:17.946546Z", "display_name" => "Jane Doe", "email_address" => "jane@example.com", "errors" => [], "full_name" => "Jane Doe", "phone_number" => "+15551234567", "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", "user_identity_key" => "jane_doe", "warnings" => [], "workspace_id" => "b7e0a4e0-1044-4319-9a0b-42b642b68c7f", ]; ``` {% endtab %} {% tab title="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_cli seam user-identities create --user_identity_key "61c6c8ec-21ac-4d1d-be02-688889c66d8c" --email_address "jane@example.com" --phone_number "+15551234567" --full_name "Jane Doe" --acs_system_ids ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"] ``` **Output:** ```seam_cli { "created_at": "2025-06-16T16:54:17.946546Z", "display_name": "Jane Doe", "email_address": "jane@example.com", "errors": [], "full_name": "Jane Doe", "phone_number": "+15551234567", "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", "user_identity_key": "jane_doe", "warnings": [], "workspace_id": "b7e0a4e0-1044-4319-9a0b-42b642b68c7f" } ``` {% endtab %} {% endtabs %}
Authentication Methods * API key * Personal access token\ Must also include the `seam-workspace` header in the request. To learn more, see [Authentication](https://docs.seam.co/latest/api/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, +15555550100). *** **`user_identity_key`** *String* Unique key for the new user identity. *** ## Response {% hint style="success" %} Returns: [**user\_identity**](/latest/api/user_identities.md) {% endhint %} {% tabs %} {% tab title="JSON" %} ```json { "created_at": "2025-06-16T16:54:17.946546Z", "display_name": "Jane Doe", "email_address": "jane@example.com", "errors": [], "full_name": "Jane Doe", "phone_number": "+1555551002", "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" } ``` {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.seam.co/latest/api/user_identities/create.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.