> ## Documentation Index
> Fetch the complete documentation index at: https://www.seam.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List User Identities

> Returns a list of all [user identities](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity).



## OpenAPI

````yaml /openapi.json get /user_identities/list
openapi: 3.0.0
info:
  description: >-
    Programmable API to control locks, thermostats, noise sensors, cameras,
    access control systems, and other IoT devices.


    Prefer the official Seam SDKs over hand-written HTTP calls: they handle

    authentication, request serialization, pagination, and error handling for

    you. The official SDKs are listed in this document under

    `info.x-seam-sdks`.


    If you call the HTTP API directly, your query parameters must be

    serialized compatibly with the Seam API. There is no universal convention

    for serializing arrays, booleans, or nested objects in a query string, so

    use @seamapi/url-search-params-serializer, the language specific serializer
    module provided by each Seam SDK, or follow its specification:

    https://github.com/seamapi/url-search-params-serializer
  title: Seam Connect
  version: 1.0.0
  x-seam-query-serializer:
    description: >-
      Reference implementation and specification for query parameter
      serialization compatible with the Seam API.
    url: https://github.com/seamapi/url-search-params-serializer
  x-seam-sdks:
    - language: javascript
      url: https://github.com/seamapi/javascript
    - language: python
      url: https://github.com/seamapi/python
    - language: ruby
      url: https://github.com/seamapi/ruby
    - language: php
      url: https://github.com/seamapi/php
    - language: csharp
      url: https://github.com/seamapi/csharp
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:
    get:
      tags:
        - /user_identities
      summary: List User Identities
      description: >-
        Returns a list of all [user
        identities](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity).
      operationId: userIdentitiesListGet
      parameters:
        - in: query
          name: user_identity_ids
          schema:
            description: >-
              Array of user identity IDs by which to filter the list of user
              identities.
            items:
              format: uuid
              type: string
            type: array
        - in: query
          name: search
          schema:
            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`.
            minLength: 1
            type: string
        - in: query
          name: credential_manager_acs_system_id
          schema:
            description: >-
              `acs_system_id` of the credential manager by which you want to
              filter the list of user identities.
            format: uuid
            type: string
        - in: query
          name: limit
          schema:
            default: 500
            description: Maximum number of records to return per page.
            exclusiveMinimum: true
            minimum: 0
            type: integer
        - in: query
          name: created_before
          schema:
            description: >-
              Timestamp by which to limit returned user identities. Returns user
              identities created before this timestamp.
            format: date-time
            type: string
        - in: query
          name: page_cursor
          schema:
            description: >-
              Identifies the specific page of results to return, obtained from
              the previous page's `next_page_cursor`.
            nullable: true
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  pagination:
                    $ref: '#/components/schemas/pagination'
                  user_identities:
                    items:
                      $ref: '#/components/schemas/user_identity'
                    type: array
                required:
                  - user_identities
                  - pagination
                type: object
          description: OK
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
      security:
        - api_key: []
        - client_session: []
        - pat_with_workspace: []
        - console_session_with_workspace: []
        - support_read_only_token: []
      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](/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).
      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:
          description: Display name for the user identity.
          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
                x-resource-type: user_identity
          type: array
        full_name:
          description: Full name of the user associated with the user identity.
          minLength: 1
          nullable: true
          type: string
        merged_user_identity_ids:
          description: >-
            IDs that other user identities used to have before they were merged
            into this user identity. Looking up any of them returns this user
            identity.
          items:
            format: uuid
            type: string
          type: array
        merged_user_identity_keys:
          description: >-
            Keys that other user identities used to have before they were merged
            into this user identity. Looking up any of them returns this user
            identity.
          items:
            type: string
          type: array
        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 that contains the user identity.
          format: uuid
          type: string
      required:
        - user_identity_id
        - user_identity_key
        - email_address
        - phone_number
        - display_name
        - full_name
        - merged_user_identity_ids
        - merged_user_identity_keys
        - 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
    support_read_only_token:
      bearerFormat: Support Read-Only Token
      scheme: bearer
      type: http

````