> ## 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.

# List User Identities

> Returns a list of all [user identities](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/list
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/list:
    post:
      tags:
        - /user_identities
      summary: List User Identities
      description: >-
        Returns a list of all [user
        identities](https://docs.seam.co/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity).
      operationId: userIdentitiesListPost
      requestBody:
        content:
          application/json:
            schema:
              properties:
                created_before:
                  description: >-
                    Timestamp by which to limit returned user identities.
                    Returns user identities created before this timestamp.
                  format: date-time
                  type: string
                credential_manager_acs_system_id:
                  description: >-
                    `acs_system_id` of the credential manager by which you want
                    to filter the list of user identities.
                  format: uuid
                  type: string
                limit:
                  default: 500
                  description: Maximum number of records to return per page.
                  exclusiveMinimum: true
                  minimum: 0
                  type: integer
                page_cursor:
                  description: >-
                    Identifies the specific page of results to return, obtained
                    from the previous page's `next_page_cursor`.
                  nullable: true
                  type: string
                search:
                  description: >-
                    String for which to search. Filters returned user identities
                    to include all records that satisfy a partial match using
                    `full_name`, `phone_number`, `email_address` or
                    `user_identity_id`.
                  type: string
                user_identity_ids:
                  description: >-
                    Array of user identity IDs by which to filter the list of
                    user identities.
                  items:
                    format: uuid
                    type: string
                  type: array
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  ok:
                    type: boolean
                  pagination:
                    $ref: '#/components/schemas/pagination'
                  user_identities:
                    items:
                      $ref: '#/components/schemas/user_identity'
                    type: array
                required:
                  - user_identities
                  - pagination
                  - ok
                type: object
          description: OK
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
      security:
        - api_key: []
        - client_session: []
        - pat_with_workspace: []
        - console_session_with_workspace: []
      x-codeSamples:
        - lang: javascript
          label: Seam SDK
          source: |-
            await seam.userIdentities.list();

            /*
            [
              {
                "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",
                "warnings": [],
                "workspace_id": "b7e0a4e0-1044-4319-9a0b-42b642b68c7f"
              }
            ]
            */
        - lang: bash
          label: cURL
          source: >-
            curl --include --request POST
            "https://connect.getseam.com/user_identities/list" \
              --header "Authorization: Bearer $SEAM_API_KEY"

            # Response:

            # {

            #   "user_identities": [

            #     {

            #       "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",

            #       "warnings": [],

            #       "workspace_id": "b7e0a4e0-1044-4319-9a0b-42b642b68c7f"

            #     }

            #   ]

            # }
        - lang: python
          label: Seam SDK
          source: |-
            seam.user_identities.list()

            # [
                UserIdentity(
                    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",
                    warnings=[],
                    workspace_id="b7e0a4e0-1044-4319-9a0b-42b642b68c7f",
                )
            ]
        - lang: ruby
          label: Seam SDK
          source: |-
            seam.user_identities.list()

            # => [
              {
                "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",
                "warnings" => [],
                "workspace_id" => "b7e0a4e0-1044-4319-9a0b-42b642b68c7f",
              },
            ]
        - lang: php
          label: Seam SDK
          source: |-
            $seam->user_identities->list();

            // [
                [
                    "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",
                    "warnings" => [],
                    "workspace_id" => "b7e0a4e0-1044-4319-9a0b-42b642b68c7f",
                ],
            ];
        - lang: bash
          label: Seam CLI
          source: |-
            seam user-identities list

            # [
            #   {
            #     "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",
            #     "warnings": [],
            #     "workspace_id": "b7e0a4e0-1044-4319-9a0b-42b642b68c7f"
            #   }
            # ]
components:
  schemas:
    pagination:
      description: Information about the current page of results.
      properties:
        has_next_page:
          description: Indicates whether there is another page of results after this one.
          type: boolean
        next_page_cursor:
          description: >-
            Opaque value that can be used to select the next page of results via
            the `page_cursor` parameter.
          nullable: true
          type: string
        next_page_url:
          description: URL to get the next page of results.
          format: uri
          nullable: true
          type: string
      required:
        - next_page_cursor
        - has_next_page
        - next_page_url
      type: object
    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
    client_session:
      bearerFormat: Client Session Token
      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

````