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

> Returns a list of all [phones](https://docs.seam.co/capability-guides/mobile-access/managing-phones-for-a-user-identity). To filter the list of returned phones by a specific owner user identity or credential, include the `owner_user_identity_id` or `acs_credential_id`, respectively, in the request body.



## OpenAPI

````yaml /openapi.json post /phones/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:
  /phones/list:
    post:
      tags:
        - /phones
      summary: List Phones
      description: >-
        Returns a list of all
        [phones](https://docs.seam.co/capability-guides/mobile-access/managing-phones-for-a-user-identity).
        To filter the list of returned phones by a specific owner user identity
        or credential, include the `owner_user_identity_id` or
        `acs_credential_id`, respectively, in the request body.
      operationId: phonesListPost
      requestBody:
        content:
          application/json:
            schema:
              properties:
                acs_credential_id:
                  description: >-
                    ID of the
                    [credential](https://docs.seam.co/low-level-apis/access-systems/managing-credentials)
                    by which you want to filter the list of returned phones.
                  format: uuid
                  type: string
                owner_user_identity_id:
                  description: >-
                    ID of the user identity that represents the owner by which
                    you want to filter the list of returned phones.
                  format: uuid
                  type: string
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  ok:
                    type: boolean
                  phones:
                    items:
                      $ref: '#/components/schemas/phone'
                    type: array
                required:
                  - phones
                  - 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.phones.list({
              owner_user_identity_id: "6bc848b0-0e7f-4d4c-8ea1-004ccda0b0a4",
            });

            /*
            [
              {
                "created_at": "2025-06-14T16:54:17.946540Z",
                "custom_metadata": {
                  "id": "internalId1"
                },
                "device_id": "e452f665-a635-4c65-922b-9feab0e0f84f",
                "device_type": "ios_phone",
                "display_name": "My Phone",
                "errors": [],
                "nickname": "My Phone",
                "properties": {
                  "assa_abloy_credential_service_metadata": {
                    "endpoints": [
                      {
                        "endpoint_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
                        "is_active": true
                      }
                    ],
                    "has_active_endpoint": true
                  }
                },
                "warnings": [],
                "workspace_id": "da8639a4-28a2-4884-a4f9-b7691f4cf336"
              }
            ]
            */
        - lang: bash
          label: cURL
          source: >-
            curl --include --request POST
            "https://connect.getseam.com/phones/list" \
              --header "Authorization: Bearer $SEAM_API_KEY" \
              --json @- <<EOF
            {
              "owner_user_identity_id": "6bc848b0-0e7f-4d4c-8ea1-004ccda0b0a4"
            }

            EOF


            # Response:

            # {

            #   "phones": [

            #     {

            #       "created_at": "2025-06-14T16:54:17.946540Z",

            #       "custom_metadata": {

            #         "id": "internalId1"

            #       },

            #       "device_id": "e452f665-a635-4c65-922b-9feab0e0f84f",

            #       "device_type": "ios_phone",

            #       "display_name": "My Phone",

            #       "errors": [],

            #       "nickname": "My Phone",

            #       "properties": {

            #         "assa_abloy_credential_service_metadata": {

            #           "endpoints": [

            #             {

            #               "endpoint_id":
            "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",

            #               "is_active": true

            #             }

            #           ],

            #           "has_active_endpoint": true

            #         }

            #       },

            #       "warnings": [],

            #       "workspace_id": "da8639a4-28a2-4884-a4f9-b7691f4cf336"

            #     }

            #   ]

            # }
        - lang: python
          label: Seam SDK
          source: >-
            seam.phones.list(owner_user_identity_id="6bc848b0-0e7f-4d4c-8ea1-004ccda0b0a4")


            # [
                Phone(
                    created_at="2025-06-14T16:54:17.946540Z",
                    custom_metadata={"id": "internalId1"},
                    device_id="e452f665-a635-4c65-922b-9feab0e0f84f",
                    device_type="ios_phone",
                    display_name="My Phone",
                    errors=[],
                    nickname="My Phone",
                    properties={
                        "assa_abloy_credential_service_metadata": {
                            "endpoints": [
                                {
                                    "endpoint_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
                                    "is_active": true,
                                }
                            ],
                            "has_active_endpoint": true,
                        }
                    },
                    warnings=[],
                    workspace_id="da8639a4-28a2-4884-a4f9-b7691f4cf336",
                )
            ]
        - lang: ruby
          label: Seam SDK
          source: >-
            seam.phones.list(owner_user_identity_id:
            "6bc848b0-0e7f-4d4c-8ea1-004ccda0b0a4")


            # => [
              {
                "created_at" => "2025-06-14T16:54:17.946540Z",
                "custom_metadata" => {
                  id: "internalId1",
                },
                "device_id" => "e452f665-a635-4c65-922b-9feab0e0f84f",
                "device_type" => "ios_phone",
                "display_name" => "My Phone",
                "errors" => [],
                "nickname" => "My Phone",
                "properties" => {
                  assa_abloy_credential_service_metadata: {
                    endpoints: [{ endpoint_id: "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", is_active: true }],
                    has_active_endpoint: true,
                  },
                },
                "warnings" => [],
                "workspace_id" => "da8639a4-28a2-4884-a4f9-b7691f4cf336",
              },
            ]
        - lang: php
          label: Seam SDK
          source: |-
            $seam->phones->list(
                owner_user_identity_id: "6bc848b0-0e7f-4d4c-8ea1-004ccda0b0a4",
            );

            // [
                [
                    "created_at" => "2025-06-14T16:54:17.946540Z",
                    "custom_metadata" => ["id" => "internalId1"],
                    "device_id" => "e452f665-a635-4c65-922b-9feab0e0f84f",
                    "device_type" => "ios_phone",
                    "display_name" => "My Phone",
                    "errors" => [],
                    "nickname" => "My Phone",
                    "properties" => [
                        "assa_abloy_credential_service_metadata" => [
                            "endpoints" => [
                                [
                                    "endpoint_id" => "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
                                    "is_active" => true,
                                ],
                            ],
                            "has_active_endpoint" => true,
                        ],
                    ],
                    "warnings" => [],
                    "workspace_id" => "da8639a4-28a2-4884-a4f9-b7691f4cf336",
                ],
            ];
        - lang: bash
          label: Seam CLI
          source: >-
            seam phones list --owner_user_identity_id
            "6bc848b0-0e7f-4d4c-8ea1-004ccda0b0a4"


            # [

            #   {

            #     "created_at": "2025-06-14T16:54:17.946540Z",

            #     "custom_metadata": {

            #       "id": "internalId1"

            #     },

            #     "device_id": "e452f665-a635-4c65-922b-9feab0e0f84f",

            #     "device_type": "ios_phone",

            #     "display_name": "My Phone",

            #     "errors": [],

            #     "nickname": "My Phone",

            #     "properties": {

            #       "assa_abloy_credential_service_metadata": {

            #         "endpoints": [

            #           {

            #             "endpoint_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",

            #             "is_active": true

            #           }

            #         ],

            #         "has_active_endpoint": true

            #       }

            #     },

            #     "warnings": [],

            #     "workspace_id": "da8639a4-28a2-4884-a4f9-b7691f4cf336"

            #   }

            # ]
components:
  schemas:
    phone:
      description: Represents an app user's mobile phone.
      properties:
        created_at:
          description: |-
            Date and time at which the phone was created.
              
          format: date-time
          type: string
        custom_metadata:
          additionalProperties:
            oneOf:
              - type: string
              - type: boolean
          description: >-
            Optional [custom
            metadata](https://docs.seam.co/core-concepts/devices/adding-custom-metadata-to-a-device)
            for the phone.
              
          type: object
        device_id:
          description: |-
            ID of the phone.
                      
          format: uuid
          type: string
        device_type:
          description: |-
            Device type for phones.
                      
          enum:
            - ios_phone
            - android_phone
          type: string
        display_name:
          description: >-
            Display name of the phone. Defaults to `nickname` (if it is set) or
            `properties.appearance.name`, otherwise. Enables administrators and
            users to identify the phone easily, especially when there are
            numerous phones.
              
          type: string
        errors:
          description: Errors associated with the phone.
          items:
            properties:
              error_code:
                type: string
              message:
                type: string
            required:
              - error_code
              - message
            type: object
          type: array
        nickname:
          description: |-
            Optional nickname to describe the phone, settable through Seam.
              
          type: string
        properties:
          description: |2-

                      Properties of the phone.
                      
          properties:
            assa_abloy_credential_service_metadata:
              description: ASSA ABLOY Credential Service metadata for the phone.
              properties:
                endpoints:
                  description: Endpoints associated with the phone.
                  items:
                    properties:
                      endpoint_id:
                        description: ID of the associated endpoint.
                        type: string
                      is_active:
                        description: Indicated whether the endpoint is active.
                        type: boolean
                    required:
                      - endpoint_id
                      - is_active
                    type: object
                  type: array
                has_active_endpoint:
                  description: >-
                    Indicates whether the credential service has active
                    endpoints associated with the phone.
                  type: boolean
              required:
                - has_active_endpoint
                - endpoints
              type: object
            salto_space_credential_service_metadata:
              description: Salto Space credential service metadata for the phone.
              properties:
                has_active_phone:
                  description: >-
                    Indicates whether the credential service has an active
                    associated phone.
                  type: boolean
              required:
                - has_active_phone
              type: object
          type: object
        warnings:
          description: Warnings associated with the phone.
          items:
            properties:
              message:
                type: string
              warning_code:
                type: string
            required:
              - warning_code
              - message
            type: object
          type: array
        workspace_id:
          description: >-
            ID of the [workspace](https://docs.seam.co/core-concepts/workspaces)
            that contains the phone.
              
          format: uuid
          type: string
      required:
        - device_id
        - display_name
        - workspace_id
        - created_at
        - custom_metadata
        - errors
        - warnings
        - device_type
        - properties
      type: object
      x-property-groups:
        phones:
          name: Phones
      x-route-path: /phones
  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

````