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

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

# Create a phone for a person

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

Operation ID: `createPersonPhoneV2`

Creates a new phone and associates it with the specified person. The first phone added is automatically marked preferred. Sending preferred: true on a subsequent phone unprefers all existing phones for that person. A person may have at most 5 phones.

## Path parameters

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

## Header parameters

- `Idempotency-Key` (string, uuid, optional) - Client-generated UUID used to deduplicate retried requests. When provided, the server caches the first successful response for this key and returns it for any subsequent request with the same key from the same client, without re-processing.

## Request body (required)

Content types: `application/json`

## Responses

- `201` - Phone created successfully.
- `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:
    post:
      summary: Create a phone for a person
      description: >
        Creates a new phone and associates it with the specified person. The
        first phone added is automatically marked preferred. Sending preferred:
        true on a subsequent phone unprefers all existing phones for that
        person. A person may have at most 5 phones.
      operationId: createPersonPhoneV2
      tags:
        - Phones
      security:
        - oauth2:
            - identity.profiles.write
      parameters:
        - $ref: "#/components/parameters/PersonIdParam"
        - $ref: "#/components/parameters/IdempotencyKeyParam"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePhoneRequest"
      responses:
        "201":
          description: Phone created successfully.
          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:
                $ref: "#/components/schemas/PhoneV2"
        "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.write
components:
  parameters:
    PersonIdParam:
      name: personId
      in: path
      description: ID of the person
      required: true
      schema:
        type: string
        format: uuid
    IdempotencyKeyParam:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        format: uuid
      description: >
        Client-generated UUID used to deduplicate retried requests. When
        provided, the server caches the first successful response for this key
        and returns it for any subsequent request with the same key from the
        same client, without re-processing.
  schemas:
    CreatePhoneRequest:
      title: CreatePhoneRequest
      type: object
      required:
        - type
        - number
        - preferred
      properties:
        type:
          $ref: "#/components/schemas/PhoneType"
        number:
          type: string
          description: Phone number (exactly 10 digits)
          pattern: ^[0-9]{10}$
          example: "3035551234"
        extension:
          type: string
          description: Optional phone extension (max 6 characters)
          maxLength: 6
          example: "1234"
        preferred:
          type: boolean
          description: Whether this is the preferred phone number
          example: true
    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
    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
  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
  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)
```