> ## Documentation Index > Fetch the complete documentation index at: https://docs.talkpilot.io/llms.txt > Use this file to discover all available pages before exploring further. # Assign a phone number > Assigns a free number from the TalkPilot number pool to the agent. The numbers in the pool are already fully wired, so the agent answers calls on the new number from the next call on. **Dashboard login only:** requires a JWT of a `super_admin` or `dev_admin`. API keys are rejected with `403 FORBIDDEN`, even with `agents:write`. The only supported `source` is `pool`. An agent that already has a phone number gets `409 AGENT_HAS_NUMBER`; if no pool number is free, the response is `409 POOL_EMPTY`. The number is also written to the agent's employees and forwarding slots (`agent_phone_number`), which is how call routing finds them at runtime. When the number is released (`DELETE`) or the agent is deleted later, the number goes into a 90-day quarantine and then returns to the pool automatically. ## OpenAPI ````yaml post /v1/agents/{agentId}/phone-number openapi: 3.1.0 info: title: TalkPilot API version: 1.0.0 description: > The TalkPilot API allows you to programmatically manage your call center agents, employees, forwarding slots, knowledge base, and more. ## Authentication All API requests require an API key passed via the `X-API-Key` header: ``` X-API-Key: tp_live_abc123def456... ``` An API key can reach every organization its creator is a member of (see `GET /v1/organization`) and can be restricted to specific agents and permissions. Create and manage keys in the TalkPilot Dashboard under **Settings > API** (Dev-Admin only). ## Rate Limiting Default limits per API key: **60 requests/minute** and **1,000 requests/hour** (both enforced, both configurable per key). Rate limit headers are included in every response to a request authenticated with an API key (Dashboard JWT requests are not rate limited): - `X-RateLimit-Limit` — Max requests per minute - `X-RateLimit-Remaining` — Remaining requests in the current minute window - `X-RateLimit-Reset` — Unix timestamp roughly 60 seconds in the future When rate limited, the API returns `429 Too Many Requests` with `Retry-After: 60` (minute window) or `Retry-After: 3600` (hour window). ## Pagination List endpoints support pagination via query parameters: - `page` — Page number (default: 1) - `limit` — Items per page (default: 20, max: 100) Paginated responses include a `pagination` object with `page`, `limit`, `total`, and `pages`. ## Error Format All errors follow a consistent format: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Human-readable description", "details": [{ "field": "name", "message": "Required" }], "request_id": "req_abc123" } } ``` contact: name: TalkPilot Support email: support@talkpilot.io license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.talkpilot.io description: Production security: - apiKey: [] tags: - name: Health description: API health and status - name: Agents description: Manage AI agent configurations - name: Workflow description: Multi-state conversation flow of an agent - name: Tools description: Manage agent tools (HTTP requests, call transfers, etc.) - name: Employees description: Manage employees linked to agents - name: Contacts description: >- Customer contacts (customer_database) per agent — the voice agent recognises callers and greets them by name or tag from here - name: Forwarding Slots description: Manage call forwarding slot assignments - name: Knowledge Base description: Manage agent knowledge base documents - name: Calls description: Read call records and transcripts - name: Performance description: >- Read call performance/QA data (latencies, token stats, redflags, transcript incl. tool calls) - name: Organization description: Organization-level settings - name: API Keys description: Manage API keys (Dashboard JWT auth only; dev_admin) paths: /v1/agents/{agentId}/phone-number: post: tags: - Agents summary: Assign a phone number description: > Assigns a free number from the TalkPilot number pool to the agent. The numbers in the pool are already fully wired, so the agent answers calls on the new number from the next call on. **Dashboard login only:** requires a JWT of a `super_admin` or `dev_admin`. API keys are rejected with `403 FORBIDDEN`, even with `agents:write`. The only supported `source` is `pool`. An agent that already has a phone number gets `409 AGENT_HAS_NUMBER`; if no pool number is free, the response is `409 POOL_EMPTY`. The number is also written to the agent's employees and forwarding slots (`agent_phone_number`), which is how call routing finds them at runtime. When the number is released (`DELETE`) or the agent is deleted later, the number goes into a 90-day quarantine and then returns to the pool automatically. operationId: assignPhoneNumber parameters: - $ref: '#/components/parameters/AgentId' requestBody: required: true content: application/json: schema: type: object required: - source additionalProperties: false properties: source: type: string enum: - pool description: Where the number comes from. Only `pool` is supported. example: source: pool responses: '201': description: Phone number assigned content: application/json: schema: type: object required: - phone_number - pool_remaining properties: phone_number: type: string description: Assigned number in E.164 format pool_remaining: type: integer description: >- Number of pool numbers that are still assignable afterwards example: phone_number: '+4930123456789' pool_remaining: 4 '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': description: > Called with an API key, or the dashboard role is not `super_admin`/`dev_admin`. content: application/json: schema: $ref: '#/components/schemas/Error' examples: apiKey: value: error: code: FORBIDDEN message: >- Nummern-Zuweisung nur mit Dashboard-Login (JWT), nicht per API-Key request_id: req_abc123 role: value: error: code: FORBIDDEN message: 'Insufficient role for permission: agents:write' request_id: req_abc123 '404': $ref: '#/components/responses/NotFound' '409': description: The agent already has a phone number, or the pool is empty content: application/json: schema: $ref: '#/components/schemas/Error' examples: agentHasNumber: value: error: code: AGENT_HAS_NUMBER message: Agent already has a phone number request_id: req_abc123 poolEmpty: value: error: code: POOL_EMPTY message: >- Keine freie Pool-Nummer — `provision_number.py pool-auffuellen` request_id: req_abc123 '429': $ref: '#/components/responses/RateLimited' components: parameters: AgentId: name: agentId in: path required: true description: Agent UUID schema: type: string format: uuid responses: ValidationError: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: VALIDATION_ERROR message: Invalid request body details: - field: llm_temperature message: Must be between 0 and 2 request_id: req_abc123 Unauthorized: description: Missing or invalid authentication content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Invalid or missing API key request_id: req_abc123 NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Agent not found request_id: req_abc123 RateLimited: description: Too many requests for this API key (60/minute or 1,000/hour by default) headers: Retry-After: description: >- Seconds to wait before retrying — 60 for the minute window, 3600 for the hour window schema: type: integer X-RateLimit-Limit: schema: type: integer X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: RATE_LIMITED message: Rate limit exceeded. Try again in 60 seconds. request_id: req_abc123 schemas: Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string enum: - VALIDATION_ERROR - UNAUTHORIZED - FORBIDDEN - AGENT_NOT_ACCESSIBLE - NOT_FOUND - CONFLICT - AGENT_HAS_NUMBER - POOL_EMPTY - NOT_POOL_NUMBER - RATE_LIMITED - INTERNAL_ERROR message: type: string details: type: array items: type: object properties: field: type: string message: type: string request_id: type: string securitySchemes: apiKey: type: apiKey in: header name: X-API-Key description: | API key for external access. Format: `tp_live_<32-hex-chars>`. Create keys in the TalkPilot Dashboard under Settings > API. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.