> ## Documentation Index > Fetch the complete documentation index at: https://docs.seam.co/llms.txt > Use this file to discover all available pages before exploring further. # Create a User Identity > Creates a new [user identity](https://docs.seam.co/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity). ## OpenAPI ````yaml /openapi.json post /user_identities/create openapi: 3.0.0 info: title: Seam Connect version: 1.0.0 servers: - url: https://connect.getseam.com security: [] tags: - description: access_codes name: /access_codes - description: acs name: /acs - description: action_attempts name: /action_attempts - description: client_sessions name: /client_sessions - description: connected_accounts name: /connected_accounts - description: connect_webviews name: /connect_webviews - description: devices name: /devices - description: events name: /events - description: health name: /health - description: locks name: /locks - description: networks name: /networks - description: noise_sensors name: /noise_sensors - description: phones name: /phones - description: thermostats name: /thermostats - description: user_identities name: /user_identities - description: webhooks name: /webhooks - description: workspaces name: /workspaces paths: /user_identities/create: post: tags: - /user_identities summary: Create a User Identity description: >- Creates a new [user identity](https://docs.seam.co/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity). operationId: userIdentitiesCreatePost requestBody: content: application/json: schema: properties: acs_system_ids: description: >- 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. items: format: uuid type: string type: array email_address: description: Unique email address for the new user identity. format: email nullable: true type: string full_name: description: Full name of the user associated with the new user identity. minLength: 1 nullable: true type: string phone_number: description: >- Unique phone number for the new user identity in E.164 format (for example, +15555550100). nullable: true type: string user_identity_key: description: Unique key for the new user identity. minLength: 1 nullable: true type: string type: object responses: '200': content: application/json: schema: properties: ok: type: boolean user_identity: $ref: '#/components/schemas/user_identity' required: - user_identity - ok type: object description: OK '400': description: Bad Request '401': description: Unauthorized security: - api_key: [] - pat_with_workspace: [] - console_session_with_workspace: [] x-codeSamples: - lang: javascript label: Seam SDK source: |- 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"], }); /* { "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" } */ - lang: bash label: cURL source: >- curl --include --request POST "https://connect.getseam.com/user_identities/create" \ --header "Authorization: Bearer $SEAM_API_KEY" \ --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" => "+15551234567", "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", "user_identity_key" => "jane_doe", "warnings" => [], "workspace_id" => "b7e0a4e0-1044-4319-9a0b-42b642b68c7f", } - lang: php label: Seam SDK source: |- $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"], ); // [ "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", ]; - lang: bash label: Seam CLI source: >- 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"] # { # "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" # } components: schemas: user_identity: description: >- Represents a [user identity](https://docs.seam.co/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) associated with an application user account. properties: acs_user_ids: description: Array of access system user IDs associated with the user identity. items: format: uuid type: string type: array created_at: description: Date and time at which the user identity was created. format: date-time type: string display_name: minLength: 1 type: string email_address: description: Unique email address for the user identity. format: email nullable: true type: string errors: description: >- 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. items: description: Errors associated with the user identity. discriminator: propertyName: error_code oneOf: - description: >- Indicates that there is an issue with an access system user associated with this user identity. properties: acs_system_id: description: >- ID of the access system that the user identity is associated with. format: uuid type: string acs_user_id: description: ID of the access system user that has an issue. format: uuid type: string created_at: description: Date and time at which Seam created the error. format: date-time type: string error_code: description: >- Unique identifier of the type of error. Enables quick recognition and categorization of the issue. enum: - issue_with_acs_user type: string message: description: >- Detailed description of the error. Provides insights into the issue and potentially how to rectify it. type: string required: - created_at - message - error_code - acs_user_id - acs_system_id type: object type: array full_name: minLength: 1 nullable: true type: string phone_number: description: >- Unique phone number for the user identity in [E.164 format](https://www.itu.int/rec/T-REC-E.164/en) (for example, +15555550100). nullable: true type: string user_identity_id: description: ID of the user identity. format: uuid type: string user_identity_key: description: Unique key for the user identity. minLength: 1 nullable: true type: string warnings: description: >- 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. items: description: Warnings associated with the user identity. discriminator: propertyName: warning_code oneOf: - description: Indicates that the user identity is currently being deleted. properties: created_at: description: Date and time at which Seam created the warning. format: date-time type: string message: description: >- Detailed description of the warning. Provides insights into the issue and potentially how to rectify it. type: string warning_code: description: >- Unique identifier of the type of warning. Enables quick recognition and categorization of the issue. enum: - being_deleted type: string required: - created_at - message - warning_code type: object - description: >- Indicates that the ACS user's profile does not match the user identity's profile properties: created_at: description: Date and time at which Seam created the warning. format: date-time type: string message: description: >- Detailed description of the warning. Provides insights into the issue and potentially how to rectify it. type: string warning_code: description: >- Unique identifier of the type of warning. Enables quick recognition and categorization of the issue. enum: - acs_user_profile_does_not_match_user_identity type: string required: - created_at - message - warning_code type: object type: array workspace_id: description: >- ID of the [workspace](https://docs.seam.co/core-concepts/workspaces) that contains the user identity. format: uuid type: string required: - user_identity_id - user_identity_key - email_address - phone_number - display_name - full_name - created_at - workspace_id - errors - warnings - acs_user_ids type: object x-route-path: /user_identities securitySchemes: api_key: bearerFormat: API Key scheme: bearer type: http pat_with_workspace: bearerFormat: API Token scheme: bearer type: http console_session_with_workspace: bearerFormat: Console Session Token scheme: bearer type: http ````