> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nedzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Give an agent a phone number

> Give a voice agent a number to answer and call from, or a caller ID to call from. Give a chat agent a number to text on.

<Note>
  This endpoint is for the VIP plan only. Other plans get a `403`. See [Plan access](/api-reference/introduction#plan-access).
</Note>

<ParamField path="agentId" type="string" required>
  Agent UUID
</ParamField>

<ParamField body="phoneNumberId" type="string">
  A number the workspace owns. A voice agent answers and calls from it. A chat agent answers texts on it.
</ParamField>

<ParamField body="verifiedCallerIdId" type="string">
  A verified caller ID the workspace owns. Voice agents only. The agent calls from it and answers on no number. Ask support for this id. The API cannot list caller IDs yet.
</ParamField>

Send exactly one of the two.

* A voice agent keeps its other numbers when you give it a new one. To take them away, [take the agent's phone numbers away](/api-reference/agents/unassign-phone-number) first.
* A chat agent texts on one number. Giving it a new one takes the old one away.
* A number or caller ID another agent holds returns `409`. Take it off that agent first.

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://api.nedzo.ai/v1/agents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/phone-number" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "phoneNumberId": "4d1f6b52-8c0e-4a51-9b7d-2f3c4e5a6b7c" }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "agentId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "phoneNumberId": "4d1f6b52-8c0e-4a51-9b7d-2f3c4e5a6b7c",
    "verifiedCallerIdId": null,
    "releasedPhoneNumberIds": []
  }
  ```
</ResponseExample>

## Errors

| Status | When |
| - | - |
| `400` | Neither or both fields were sent, a web agent was named, or a caller ID was sent for a chat agent |
| `404` | The agent, number or caller ID is not found, or not in this API key's scope. The number and the agent must be in the same workspace |
| `409` | Another agent holds this number or caller ID |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.