> ## Documentation Index > Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update Phone Number > Update a phone number's label, agent assignment, or provider ## OpenAPI ````yaml 2026-03-01/api.yml PATCH /agents/phone-numbers/{id} openapi: 3.0.1 info: title: Cartesia API version: 0.0.1 servers: - url: https://api.cartesia.ai description: Production security: [] paths: /agents/phone-numbers/{id}: patch: tags: - Phone Numbers summary: Update Phone Number description: Update a phone number's label, agent assignment, or provider operationId: phone_numbers_update parameters: - $ref: '#/components/parameters/CartesiaVersionHeader' - name: id in: path description: The phone number ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdatePhoneNumberBody' responses: '200': description: Phone number updated. content: application/json: schema: $ref: '#/components/schemas/PhoneNumberResponse' '400': description: >- Update failed. Possible reasons: phone number not found in the target provider account, or webhook configuration failed. '404': description: Phone number, agent, or provider not found. security: - APIKeyAuth: [] components: parameters: CartesiaVersionHeader: name: Cartesia-Version in: header description: API version header. required: true schema: type: string format: date example: '2026-03-01' default: '2026-03-01' enum: - '2026-03-01' schemas: UpdatePhoneNumberBody: title: UpdatePhoneNumberBody type: object description: >- Fields to update on a phone number. All fields are optional. Set `agent_id` to `null` to unassign the current agent. properties: label: type: string description: A new human-readable name. agent_id: type: string nullable: true description: >- Assign an agent to answer inbound calls to this number, or `null` to unassign. provider: description: >- Change the provider. Pass `{ "id": "..." }` for an existing provider, or pass Twilio account fields for lookup convenience. For Twilio, the phone number must exist in the target provider account. For SIP trunk providers, Cartesia handles reassignment between SIP providers. Switching between provider types is not supported; delete and re-import the number instead. oneOf: - type: object title: By ID properties: id: type: string required: - id - type: object title: By Twilio Account properties: type: type: string enum: - twilio account_sid: type: string region: $ref: '#/components/schemas/TelephonyRegion' required: - type - account_sid PhoneNumberResponse: title: PhoneNumberResponse description: A phone number with its provider and agent assignment details. allOf: - $ref: '#/components/schemas/PhoneNumberBaseResponse' - type: object properties: provider: $ref: '#/components/schemas/ProviderResponse' required: - provider TelephonyRegion: title: TelephonyRegion type: string enum: - us1 - ie1 - au1 description: >- The Twilio region the phone number and API key are configured for. `us1` (US), `ie1` (Ireland), `au1` (Australia). Default is `us1`. default: us1 PhoneNumberBaseResponse: title: PhoneNumberBaseResponse type: object description: Common phone number fields. properties: id: type: string description: Unique identifier for the phone number. label: type: string nullable: true description: A human-readable name for the phone number. number: type: string description: The phone number in E.164 format (e.g. +14155551234). agent: nullable: true description: >- The agent that answers inbound calls to this number, or `null` if unassigned type: object properties: id: type: string name: type: string required: - id - name created_at: type: string format: date-time description: UTC timestamp when the phone number was created. updated_at: type: string format: date-time description: UTC timestamp when the phone number was last updated. required: - id - number - agent - created_at - updated_at ProviderResponse: title: Provider description: >- The telephony provider associated with a phone number. One of `Twilio`, `Cartesia`, or `SIP Trunk`, determined by the `type` field. For SIP trunk numbers, `inbound` and `outbound` are not returned here — use `GET /agents/phone-numbers/providers/{id}` to retrieve them. oneOf: - $ref: '#/components/schemas/TwilioProviderResponse' - $ref: '#/components/schemas/CartesiaProviderResponse' - $ref: '#/components/schemas/SIPTrunkEmbeddedResponse' discriminator: propertyName: type mapping: twilio: $ref: '#/components/schemas/TwilioProviderResponse' cartesia: $ref: '#/components/schemas/CartesiaProviderResponse' sip_trunk: $ref: '#/components/schemas/SIPTrunkEmbeddedResponse' TwilioProviderResponse: title: Twilio type: object description: >- A linked Twilio account. The `api_key_sid` field is partially masked in responses. properties: type: type: string enum: - twilio description: Always `"twilio"`. id: type: string description: Unique identifier for the provider. account_sid: type: string description: The Twilio account SID. api_key_sid: type: string description: The Twilio API key SID (partially masked). region: $ref: '#/components/schemas/TelephonyRegion' label: type: string nullable: true description: A human-readable label for the provider. required: - type - id - account_sid - api_key_sid - region CartesiaProviderResponse: title: Cartesia type: object description: A Cartesia-managed provider. US phone numbers only. properties: type: type: string enum: - cartesia description: Always `"cartesia"`. required: - type SIPTrunkEmbeddedResponse: title: SIP Trunk type: object description: A linked SIP trunk provider. properties: type: type: string enum: - sip_trunk description: Always `"sip_trunk"`. id: type: string description: Unique identifier for the provider. label: type: string nullable: true description: A human-readable label for the provider. required: - type - id securitySchemes: APIKeyAuth: type: http scheme: bearer bearerFormat: API Key description: >- Cartesia API key (`sk_car_...`). Get one at [play.cartesia.ai/keys](https://play.cartesia.ai/keys). x-default: $CARTESIA_API_KEY ````