---
title: "List phones for a person"
url: "https://developer-staging.agentsync.io/apis/identity/versions/1ed33a2c-924a-434c-9643-fbc531dea1b8/operations/listPersonPhonesV2"
---

> Full API specification: https://developer-staging.agentsync.io/apis/identity/versions/1ed33a2c-924a-434c-9643-fbc531dea1b8.md

# List phones for a person

`GET` `/v2/persons/{personId}/phones`

Operation ID: `listPersonPhonesV2`

Returns phones belonging to the specified person and visible to the authenticated customer, paginated by continuation token.

## Path parameters

- `personId` (string, uuid, required) - ID of the person

## Query parameters

- `page_token` (string, optional) - Opaque continuation token returned by the previous response's `page.nextToken`. Omit on the first request. Format is server-controlled and may change without an API version bump.
- `page_size` (integer, int32, optional) - Requested number of items in the response. Defaults to 25 when omitted; values outside `[1, 250]` are rejected with `400` (not clamped). The actual size returned is reflected in `page.size` and may be smaller (last page or empty result).

## Responses

- `200` - A page of phones belonging to the person.
- `400` - One or more request fields failed validation
- `401` - No valid bearer token was presented
- `403` - The token does not carry the required scope
- `404` - The requested resource does not exist or is not visible to the caller
- `429` - Rate limit exceeded. The caller has exceeded the maximum number of requests allowed per rate-limit window for the authenticated credential. NOTE: The response body for this status deviates from the standard V2 error shape ({message, details, code}). The body contains only a top-level "message" string. Clients should treat the Retry-After header as the authoritative retry signal and must not parse the message string.
- `500` - An unexpected server error occurred

## OpenAPI definition

```yaml
openapi: 3.0.1
info:
  title: Identity API
  version: v1.275.8
servers:
  - url: https://api.sandbox.agentsync.io/id
    description: Sandbox server
  - url: https://api.agentsync.io/id
    description: Production server
paths:
  /v2/persons/{personId}/phones:
    get:
      summary: List phones for a person
      description: >
        Returns phones belonging to the specified person and visible to the
        authenticated customer, paginated by continuation token.
      operationId: listPersonPhonesV2
      tags:
        - Phones
      security:
        - oauth2:
            - identity.profiles.read
      parameters:
        - $ref: "#/components/parameters/PersonIdParam"
        - $ref: "#/components/parameters/PageToken"
        - $ref: "#/components/parameters/PageSize"
      responses:
        "200":
          description: A page of phones belonging to the person.
          headers:
            ratelimit-limit:
              $ref: "#/components/headers/ratelimit-limit"
            ratelimit-remaining:
              $ref: "#/components/headers/ratelimit-remaining"
            ratelimit-reset:
              $ref: "#/components/headers/ratelimit-reset"
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                  - page
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/PhoneV2"
                  page:
                    $ref: "#/components/schemas/Page"
        "400":
          $ref: "#/components/responses/V2BadRequest"
        "401":
          $ref: "#/components/responses/V2Unauthorized"
        "403":
          $ref: "#/components/responses/V2Forbidden"
        "404":
          $ref: "#/components/responses/V2NotFound"
        "429":
          $ref: "#/components/responses/V2TooManyRequests"
        "500":
          $ref: "#/components/responses/V2InternalServerError"
security:
  - oauth2:
      - identity.profiles.read
components:
  parameters:
    PersonIdParam:
      name: personId
      in: path
      description: ID of the person
      required: true
      schema:
        type: string
        format: uuid
    PageToken:
      name: page_token
      in: query
      required: false
      description: >
        Opaque continuation token returned by the previous response's
        `page.nextToken`. Omit on the first request. Format is server-controlled
        and may change without an API version bump.
      schema:
        type: string
    PageSize:
      name: page_size
      in: query
      required: false
      description: >
        Requested number of items in the response. Defaults to 25 when omitted;
        values outside `[1, 250]` are rejected with `400` (not clamped). The
        actual size returned is reflected in `page.size` and may be smaller
        (last page or empty result).
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 250
        default: 25
  headers:
    ratelimit-limit:
      description: >
        Maximum number of requests allowed per rate-limit window for the
        authenticated credential. The value returned in this header is
        authoritative; do not cache it.
      schema:
        type: integer
    ratelimit-remaining:
      description: Number of requests remaining in the current rate-limit window.
      schema:
        type: integer
    ratelimit-reset:
      description: >
        Unix timestamp (seconds) after which at least one additional request
        slot becomes available. In a sliding window this is a hint, not a hard
        reset point — retrying exactly at this instant may still return 429
        under sustained load.
      schema:
        type: integer
    Retry-After:
      description: >
        Minimum seconds to wait before retrying. Use this value directly as your
        retry delay; it already accounts for any server-side backoff.
      schema:
        type: integer
  schemas:
    PhoneV2:
      title: PhoneV2
      type: object
      description: |
        A phone record returned by V2 phone endpoints.
      required:
        - id
        - type
        - number
        - preferred
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: Phone identifier.
          readOnly: true
          example: 550e8400-e29b-41d4-a716-446655440000
        type:
          $ref: "#/components/schemas/PhoneType"
        number:
          type: string
          description: 10-digit phone number.
          example: "3035551234"
        extension:
          type: string
          nullable: true
          description: Optional phone extension.
          example: "1234"
        preferred:
          type: boolean
          description: Whether this is the preferred phone number.
          example: true
        createdAt:
          type: string
          format: date-time
          description: RFC3339 UTC timestamp when the phone was created.
          readOnly: true
          example: 2024-01-15T10:30:00Z
        updatedAt:
          type: string
          format: date-time
          nullable: true
          description: RFC3339 UTC timestamp when the phone was last updated.
          readOnly: true
          example: 2024-01-15T14:45:00Z
    Page:
      type: object
      description: Page metadata for a token-based list response.
      required:
        - size
        - nextToken
      properties:
        size:
          type: integer
          format: int32
          minimum: 0
          description: >
            Number of items actually returned in this response — equal to
            `items.length`. On an empty result this is `0`. This is NOT a copy
            of the request's `page_size` hint; clients holding the hint already
            know what they asked for.
          example: 25
        nextToken:
          type: string
          nullable: true
          description: >
            Opaque token to request the next page. `null` when this is the last
            page. Pass back as the `page_token` query parameter to resume.
          example: eyJ2IjoxLCJrIjp7InVwZGF0ZWRBdCI6IjIwMjYtMDUtMTlUMTI6MDA6MDBaIiwiaWQiOiIwMUhYWVoifX0
    PhoneType:
      title: PhoneType
      type: string
      description: The type of phone
      enum:
        - CELL
        - BUSINESS
        - RESIDENT
        - FAX
      example: CELL
    V2Error:
      type: object
      required:
        - message
        - details
        - code
      properties:
        message:
          type: string
          description: Human-readable error summary. Do not parse — use "code" for
            branching.
          example: Validation failed
        details:
          type: array
          description: Per-field validation errors. Empty for all non-400 responses.
          items:
            $ref: "#/components/schemas/V2FieldError"
        code:
          type: string
          description: Stable machine-readable error code.
          enum:
            - validation_failed
            - unauthorized
            - unauthorized_scope
            - resource_not_found
            - conflict
            - unprocessable
            - unsupported_media_type
            - rate_limited
            - internal
          example: validation_failed
    V2FieldError:
      type: object
      required:
        - param
        - message
      properties:
        param:
          type: string
          description: The request field that failed validation
          example: email
        message:
          type: string
          description: Human-readable description of the failure
          example: must not be blank
  responses:
    V2BadRequest:
      description: One or more request fields failed validation
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/V2Error"
          example:
            message: Validation failed
            code: validation_failed
            details:
              - param: email
                message: must not be blank
    V2Unauthorized:
      description: No valid bearer token was presented
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/V2Error"
          example:
            message: Authentication required
            code: unauthorized
            details: []
    V2Forbidden:
      description: The token does not carry the required scope
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/V2Error"
          example:
            message: Insufficient scope
            code: unauthorized_scope
            details: []
    V2NotFound:
      description: The requested resource does not exist or is not visible to the caller
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/V2Error"
          example:
            message: Resource not found
            code: resource_not_found
            details: []
    V2TooManyRequests:
      description: >
        Rate limit exceeded. The caller has exceeded the maximum number of
        requests allowed per rate-limit window for the authenticated credential.

        NOTE: The response body for this status deviates from the standard V2
        error shape ({message, details, code}). The body contains only a
        top-level "message" string. Clients should treat the Retry-After header
        as the authoritative retry signal and must not parse the message string.
      headers:
        ratelimit-limit:
          $ref: "#/components/headers/ratelimit-limit"
        ratelimit-remaining:
          $ref: "#/components/headers/ratelimit-remaining"
        ratelimit-reset:
          $ref: "#/components/headers/ratelimit-reset"
        Retry-After:
          $ref: "#/components/headers/Retry-After"
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
          example:
            message: API rate limit exceeded
    V2InternalServerError:
      description: An unexpected server error occurred
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/V2Error"
          example:
            message: An unexpected error occurred
            code: internal
            details: []
  securitySchemes:
    oauth2:
      type: oauth2
      description: >
        OAuth2 client credentials. The `tokenUrl` below is the SANDBOX token
        endpoint; for production use `https://auth.agentsync.io/oauth2/token`.
        OpenAPI 3.0 permits only one token URL per flow, so both cannot be
        expressed here — see the Authentication section for the full environment
        table.
      flows:
        clientCredentials:
          tokenUrl: https://auth.sandbox.agentsync.io/oauth2/token
          scopes:
            identity.profiles.read: Read access to producer profile resources (V2 customer-facing)
            identity.profiles.write: Write access to producer profile resources (V2 customer-facing)
```