---
title: "Create a User Identity"
method: POST
path: "/user_identities/create"
tags: ["/user_identities"]
---

# Create a User Identity

`POST /user_identities/create`

Creates a new [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity).

## Request body

- object
  - `acs_system_ids` string[] — 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, email, nullable — Unique email address for the new user identity.
  - `full_name` string, nullable — Full name of the user associated with the new user identity.
  - `phone_number` string, nullable — Unique phone number for the new user identity in E.164 format (for example, +15555550100).
  - `user_identity_key` string, nullable — Unique key for the new user identity.

## Response `200`

OK

- object
  - `user_identity` UserIdentity, required — Represents a [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) associated with an application user account. See the [user_identity object](/api/user_identities/object).
    - `acs_user_ids` string[], required — Array of access system user IDs associated with the user identity.
    - `created_at` string, date-time, required — Date and time at which the user identity was created.
    - `display_name` string, required — Display name for the user identity.
    - `email_address` string, email, nullable, required — Unique email address for the user identity.
    - `errors` object[], required — Array of errors associated with the user identity. Each error object within the array contains fields like "error_code" and "message." "error_code" is a string that uniquely identifies the type of error, enabling quick recognition and categorization of the issue. "message" provides a more detailed description of the error, offering insights into the issue and potentially how to rectify it.
      - `acs_system_id` string, uuid, required — ID of the access system that the user identity is associated with.
      - `acs_user_id` string, uuid, required — ID of the access system user that has an issue.
      - `created_at` string, date-time, required — Date and time at which Seam created the error.
      - `error_code` 'issue_with_acs_user', required — Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
      - `message` string, required — Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
    - `full_name` string, nullable, required — Full name of the user associated with the user identity.
    - `phone_number` string, nullable, required — Unique phone number for the user identity in [E.164 format](https://www.itu.int/rec/T-REC-E.164/en) (for example, +15555550100).
    - `user_identity_id` string, uuid, required — ID of the user identity.
    - `user_identity_key` string, nullable, required — Unique key for the user identity.
    - `warnings` union[], required — Array of warnings associated with the user identity. Each warning object within the array contains two fields: "warning_code" and "message." "warning_code" is a string that uniquely identifies the type of warning, enabling quick recognition and categorization of the issue. "message" provides a more detailed description of the warning, offering insights into the issue and potentially how to rectify it.
      - union — Warnings associated with the user identity.
        - object — Indicates that the user identity is currently being deleted.
          - `created_at` string, date-time, required — Date and time at which Seam created the warning.
          - `message` string, required — Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
          - `warning_code` 'being_deleted', required — Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
        - object — Indicates that the ACS user's profile does not match the user identity's profile
          - `created_at` string, date-time, required — Date and time at which Seam created the warning.
          - `message` string, required — Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
          - `warning_code` 'acs_user_profile_does_not_match_user_identity', required — Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
    - `workspace_id` string, uuid, required — ID of the workspace that contains the user identity.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized

---

[API](https://skmtc.net/seam/apis/seam-connect.md) · [All operations](https://skmtc.net/seam/apis/seam-connect/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/seam/seam-connect/versions/00c35395ce12/schema)