> ## Documentation Index > Fetch the complete documentation index at: https://docs.vocobase.com/llms.txt > Use this file to discover all available pages before exploring further. # Assign an agent to a DID > Updates a phone number's agent assignment, inbound-routing flag, friendly name, or status. Active duplicate DIDs are allowed for outbound caller ID reuse, but only one active row per DID can have `inbound_enabled=true`. When inbound routing changes for Plivo or Vobiz, Vocobase first updates the carrier Application binding and then updates the local record. If carrier sync fails, the local assignment is not committed. ## OpenAPI ````yaml /openapi.json put /phone-numbers/{id} openapi: 3.1.0 info: title: Vocobase Partner API version: '2.0' description: >- API for managing voice AI agents, documents, and calls on the Vocobase platform. servers: - url: https://api.vocobase.com/api/v2 description: Production security: - bearerAuth: [] tags: - name: Config description: >- Read and update partner configuration, webhook settings, and telephony credentials. - name: Agents description: Create, read, update, and delete voice AI agents. - name: Voices description: >- List voice tiers, available voices, and stream preview audio for agent configuration. - name: Documents description: Upload, manage, and delete knowledge base documents. - name: Agent Documents description: Link and unlink documents to agents for knowledge base integration. - name: Calls description: Initiate outbound calls and view call history. - name: Phone Numbers description: >- Import DIDs, assign agents for inbound routing, and re-sync carrier Application bindings. - name: Inbound Routing Policies description: >- Define pre-answer routing decisions for inbound calls before AI sessions are created. - name: Telephony Connections description: Create, list, rename, and disconnect named V2 telephony connections. - name: VoiceLink Management description: Manage VoiceLink reseller clients, DID mapping, and readiness sync. - name: Projects description: Organize agents into projects. Every agent belongs to exactly one project. - name: Dictionaries description: Speech-recognition dictionary CRUD and agent attachment. - name: Sessions description: Browser-initiated WebRTC voice sessions for in-app voice agents. paths: /phone-numbers/{id}: put: tags: - Phone Numbers summary: Assign an agent to a DID description: >- Updates a phone number's agent assignment, inbound-routing flag, friendly name, or status. Active duplicate DIDs are allowed for outbound caller ID reuse, but only one active row per DID can have `inbound_enabled=true`. When inbound routing changes for Plivo or Vobiz, Vocobase first updates the carrier Application binding and then updates the local record. If carrier sync fails, the local assignment is not committed. operationId: updatePhoneNumber parameters: - name: id in: path required: true schema: type: string format: uuid description: Phone number ID from `GET /phone-numbers`. requestBody: required: true content: application/json: schema: type: object properties: agent_id: type: - string - 'null' format: uuid description: >- Agent ID to assign. Use `null` or an empty string to clear assignment. If `inbound_enabled` is omitted, assigning an agent enables inbound routing and clearing the agent disables it. inbound_enabled: type: boolean description: >- Whether this DID should receive inbound calls for the assigned agent. Set `false` to keep the row available for outbound caller ID use only. friendly_name: type: - string - 'null' maxLength: 200 status: type: string enum: - ACTIVE - INACTIVE minProperties: 1 example: agent_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 inbound_enabled: true responses: '200': description: Phone number updated. content: application/json: schema: type: object properties: success: type: boolean const: true data: $ref: '#/components/schemas/PhoneNumber' example: success: true data: id: f1a2c3d4-1111-2222-3333-444455556666 phone_number: '+918065480085' provider: VOBIZ friendly_name: null status: ACTIVE is_default: false inbound_enabled: true agent: id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 name: Inbound Test Agent '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': description: >- The DID is already enabled for inbound routing on another active row. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: VALIDATION_ERROR message: >- Phone number +918065480085 is already enabled for inbound routing on connection 9b7f1c44-c87f-4f0c-9124-3c802a9c1a20. Disable inbound routing there before assigning it to another inbound agent. '500': $ref: '#/components/responses/InternalError' '502': description: >- Carrier Application sync failed. The local assignment was not committed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: vobiz: value: success: false error: code: VOBIZ_SYNC_FAILED message: Vobiz sync failed plivo: value: success: false error: code: PLIVO_SYNC_FAILED message: Plivo sync failed components: schemas: PhoneNumber: type: object description: Imported carrier DID managed through the V2 phone-numbers API. properties: id: type: string format: uuid connection_id: type: string format: uuid description: Telephony connection that owns this DID. connection_name: type: - string - 'null' description: Display name of the owning telephony connection. phone_number: type: string description: >- DID in E.164 format. A connection-detail response may also include the MCube default exeNumber in national format; manually imported MCube DIDs are always E.164. example: '+918065480085' provider: type: string enum: - TWILIO - EXOTEL - PLIVO - VOBIZ - TATA_SMARTFLO - SIP - VOICELINK - MCUBE description: Carrier connection that owns this DID. friendly_name: type: - string - 'null' status: type: string enum: - ACTIVE - INACTIVE is_default: type: boolean description: True when this DID is the connection's default outbound from-number. inbound_enabled: type: boolean description: >- True when this active DID is eligible to receive inbound calls for its assigned agent. Only one active row per DID can have this set to true. agent: type: - object - 'null' properties: id: type: string format: uuid name: type: string description: >- Assigned agent, or null when unassigned. The DID receives inbound calls only when `inbound_enabled` is true. created_at: type: string format: date-time updated_at: type: string format: date-time ErrorResponse: type: object properties: success: type: boolean const: false error: type: object properties: code: type: string message: type: string required: - code - message required: - success - error responses: ValidationError: description: Validation error in request body or parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: VALIDATION_ERROR message: agent_name is required and must be max 50 characters Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing API key NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Resource not found InternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_ERROR message: An unexpected error occurred securitySchemes: bearerAuth: type: http scheme: bearer description: >- API key in format: `rg_live_xxxx`. Pass as a Bearer token in the Authorization header. ````