# Phone Numbers
Provision and manage phone numbers
## List phone numbers
> Retrieves all phone numbers for the organization or available inventory numbers for purchase.\
> Supports filtering:\
> \- \`action=assigned\` → Returns numbers owned by the organization (default behavior)\
> \- \`action=available\` → Returns inventory numbers available for purchase
```json
{"openapi":"3.0.3","info":{"title":"KrosAI Cockpit API","version":"1.3.0"},"tags":[{"name":"Phone Numbers","description":"Provision and manage phone numbers"}],"servers":[{"url":"https://api.krosai.com/v1","description":"Production API"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key in format `kros_live_xxxx` for production or `kros_test_xxxx` for testing.\nAlso accepts JWT tokens from Supabase Auth for dashboard sessions.\n\n**Alternative:** You can also use the `x-api-key` header instead of Authorization Bearer.\n"}},"parameters":{"OrganizationId":{"name":"x-organization-id","in":"header","required":false,"description":"Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.","schema":{"type":"string","format":"uuid"}}},"schemas":{"PhoneNumber":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"e164":{"type":"string","description":"E.164 formatted phone number"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"type":{"type":"string","enum":["local","mobile","toll_free"]},"status":{"type":"string","enum":["active","inactive","pending"]},"endpoint_id":{"type":"string","format":"uuid","nullable":true},"allow_inbound":{"type":"boolean","default":true},"allow_outbound":{"type":"boolean","default":false},"sip_uri":{"type":"string","description":"SIP URI for inbound routing"},"organization_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"},"details":{"type":"object","additionalProperties":true,"description":"Additional error details"}}}},"responses":{"Unauthorized":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/phone-numbers":{"get":{"tags":["Phone Numbers"],"summary":"List phone numbers","description":"Retrieves all phone numbers for the organization or available inventory numbers for purchase.\nSupports filtering:\n- `action=assigned` → Returns numbers owned by the organization (default behavior)\n- `action=available` → Returns inventory numbers available for purchase\n","operationId":"listPhoneNumbers","parameters":[{"$ref":"#/components/parameters/OrganizationId"},{"name":"action","in":"query","description":"Filter phone numbers by status.\n- `assigned` → Numbers owned by the organization\n- `available` → Inventory numbers available for purchase\n","schema":{"type":"string","enum":["assigned","available"],"default":"assigned"}},{"name":"country","in":"query","description":"ISO 3166-1 alpha-2 country code (required when action=available)\n","schema":{"type":"string"}},{"name":"type","in":"query","description":"Number type filter (only applies when action=available)","schema":{"type":"string","enum":["local","mobile","toll_free"]}},{"name":"limit","in":"query","description":"Number of results (default 20, max 100)","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}},{"name":"offset","in":"query","description":"Pagination offset","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"List of phone numbers","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PhoneNumber"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```
## Purchase a phone number
> Purchases a new phone number from the inventory.
```json
{"openapi":"3.0.3","info":{"title":"KrosAI Cockpit API","version":"1.3.0"},"tags":[{"name":"Phone Numbers","description":"Provision and manage phone numbers"}],"servers":[{"url":"https://api.krosai.com/v1","description":"Production API"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key in format `kros_live_xxxx` for production or `kros_test_xxxx` for testing.\nAlso accepts JWT tokens from Supabase Auth for dashboard sessions.\n\n**Alternative:** You can also use the `x-api-key` header instead of Authorization Bearer.\n"}},"parameters":{"OrganizationId":{"name":"x-organization-id","in":"header","required":false,"description":"Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.","schema":{"type":"string","format":"uuid"}}},"schemas":{"PhoneNumber":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"e164":{"type":"string","description":"E.164 formatted phone number"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"type":{"type":"string","enum":["local","mobile","toll_free"]},"status":{"type":"string","enum":["active","inactive","pending"]},"endpoint_id":{"type":"string","format":"uuid","nullable":true},"allow_inbound":{"type":"boolean","default":true},"allow_outbound":{"type":"boolean","default":false},"sip_uri":{"type":"string","description":"SIP URI for inbound routing"},"organization_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"},"details":{"type":"object","additionalProperties":true,"description":"Additional error details"}}}},"responses":{"Unauthorized":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Forbidden - Insufficient permissions or KYC required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/phone-numbers":{"post":{"tags":["Phone Numbers"],"summary":"Purchase a phone number","description":"Purchases a new phone number from the inventory.\n","operationId":"purchasePhoneNumber","parameters":[{"$ref":"#/components/parameters/OrganizationId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Supports two purchase flows:\n- **API flow**: Provide `inventory_id` only. The system resolves e164, country, and type from inventory.\n- **Dashboard flow**: Provide `e164`, `country`, and `type` explicitly.\nAt least one flow's required fields must be present.\n","properties":{"inventory_id":{"type":"string","format":"uuid","description":"ID of the phone number from inventory (API flow)"},"e164":{"type":"string","description":"E.164 formatted phone number (Dashboard flow)"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code (Dashboard flow)"},"type":{"type":"string","enum":["local","mobile","toll_free"],"description":"Number type (Dashboard flow)"},"endpointId":{"type":"string","format":"uuid","description":"Endpoint to attach immediately after purchase"},"totalCostCents":{"type":"integer","description":"Total cost in cents (setup + first month)"},"setupCostCents":{"type":"integer","description":"One-time setup cost in cents"},"monthlyCostCents":{"type":"integer","description":"Recurring monthly cost in cents"}}}}}},"responses":{"201":{"description":"Phone number purchased successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumber"}}}},"400":{"description":"Bad request. Possible error codes:\n- `MISSING_FIELDS` — Neither `inventory_id` nor `e164`/`country`/`type` provided\n- `KYC_NOT_SUBMITTED` — KYC verification not yet submitted\n- `KYC_INITIATED` — KYC submitted but not yet reviewed\n- `KYC_DECLINED` — KYC verification was declined\n- `KYC_PENDING` — KYC verification is still pending\n- `NUMBER_NOT_AVAILABLE` — The requested number is no longer available\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Insufficient balance (`INSUFFICIENT_BALANCE`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"$ref":"#/components/responses/Forbidden"}}}}}}
```
## Get phone number details
> Retrieves details including SIP credentials for routing
```json
{"openapi":"3.0.3","info":{"title":"KrosAI Cockpit API","version":"1.3.0"},"tags":[{"name":"Phone Numbers","description":"Provision and manage phone numbers"}],"servers":[{"url":"https://api.krosai.com/v1","description":"Production API"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key in format `kros_live_xxxx` for production or `kros_test_xxxx` for testing.\nAlso accepts JWT tokens from Supabase Auth for dashboard sessions.\n\n**Alternative:** You can also use the `x-api-key` header instead of Authorization Bearer.\n"}},"parameters":{"PhoneNumberId":{"name":"id","in":"path","required":true,"description":"Phone number UUID","schema":{"type":"string","format":"uuid"}},"OrganizationId":{"name":"x-organization-id","in":"header","required":false,"description":"Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.","schema":{"type":"string","format":"uuid"}}},"schemas":{"PhoneNumberDetail":{"allOf":[{"$ref":"#/components/schemas/PhoneNumber"},{"type":"object","properties":{"sip_credentials":{"type":"object","properties":{"sip_domain":{"type":"string"},"sip_port":{"type":"integer"},"sip_username":{"type":"string"},"sip_password":{"type":"string","description":"Only shown to owner/admin roles"}}},"inventory":{"type":"object","properties":{"monthly_cost_cents":{"type":"integer"},"setup_cost_cents":{"type":"integer"},"capabilities":{"type":"object","properties":{"voice":{"type":"boolean"},"sms":{"type":"boolean"},"fax":{"type":"boolean"}}}}}}}]},"PhoneNumber":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"e164":{"type":"string","description":"E.164 formatted phone number"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"type":{"type":"string","enum":["local","mobile","toll_free"]},"status":{"type":"string","enum":["active","inactive","pending"]},"endpoint_id":{"type":"string","format":"uuid","nullable":true},"allow_inbound":{"type":"boolean","default":true},"allow_outbound":{"type":"boolean","default":false},"sip_uri":{"type":"string","description":"SIP URI for inbound routing"},"organization_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"},"details":{"type":"object","additionalProperties":true,"description":"Additional error details"}}}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/phone-numbers/{id}":{"get":{"tags":["Phone Numbers"],"summary":"Get phone number details","description":"Retrieves details including SIP credentials for routing","operationId":"getPhoneNumber","parameters":[{"$ref":"#/components/parameters/PhoneNumberId"},{"$ref":"#/components/parameters/OrganizationId"}],"responses":{"200":{"description":"Phone number details with SIP credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberDetail"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Release or delete phone number
> Removes a phone number from the organization.\
> \
> \*\*Two modes:\*\*\
> \- \*\*Hard delete\*\* (default, no query param): Permanently removes the phone number record and frees the inventory slot.\
> \- \*\*Soft release\*\* (\`?action=release\`): Marks the number as inactive and frees the inventory slot, but keeps the record for audit purposes.
```json
{"openapi":"3.0.3","info":{"title":"KrosAI Cockpit API","version":"1.3.0"},"tags":[{"name":"Phone Numbers","description":"Provision and manage phone numbers"}],"servers":[{"url":"https://api.krosai.com/v1","description":"Production API"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key in format `kros_live_xxxx` for production or `kros_test_xxxx` for testing.\nAlso accepts JWT tokens from Supabase Auth for dashboard sessions.\n\n**Alternative:** You can also use the `x-api-key` header instead of Authorization Bearer.\n"}},"parameters":{"PhoneNumberId":{"name":"id","in":"path","required":true,"description":"Phone number UUID","schema":{"type":"string","format":"uuid"}},"OrganizationId":{"name":"x-organization-id","in":"header","required":false,"description":"Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.","schema":{"type":"string","format":"uuid"}}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"},"details":{"type":"object","additionalProperties":true,"description":"Additional error details"}}}}},"paths":{"/phone-numbers/{id}":{"delete":{"tags":["Phone Numbers"],"summary":"Release or delete phone number","description":"Removes a phone number from the organization.\n\n**Two modes:**\n- **Hard delete** (default, no query param): Permanently removes the phone number record and frees the inventory slot.\n- **Soft release** (`?action=release`): Marks the number as inactive and frees the inventory slot, but keeps the record for audit purposes.\n","operationId":"releasePhoneNumber","parameters":[{"$ref":"#/components/parameters/PhoneNumberId"},{"$ref":"#/components/parameters/OrganizationId"},{"name":"action","in":"query","description":"Set to `release` to soft-release the number (marks inactive, keeps record).\nOmit for hard delete (removes record entirely).\n","schema":{"type":"string","enum":["release"]}}],"responses":{"200":{"description":"Phone number soft-released (when `?action=release`)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"action":{"type":"string"}}}}}},"204":{"description":"Phone number hard-deleted (default)"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## PATCH /phone-numbers/{id}
> Update phone number settings
```json
{"openapi":"3.0.3","info":{"title":"KrosAI Cockpit API","version":"1.3.0"},"tags":[{"name":"Phone Numbers","description":"Provision and manage phone numbers"}],"servers":[{"url":"https://api.krosai.com/v1","description":"Production API"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key in format `kros_live_xxxx` for production or `kros_test_xxxx` for testing.\nAlso accepts JWT tokens from Supabase Auth for dashboard sessions.\n\n**Alternative:** You can also use the `x-api-key` header instead of Authorization Bearer.\n"}},"parameters":{"PhoneNumberId":{"name":"id","in":"path","required":true,"description":"Phone number UUID","schema":{"type":"string","format":"uuid"}},"OrganizationId":{"name":"x-organization-id","in":"header","required":false,"description":"Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.","schema":{"type":"string","format":"uuid"}}},"schemas":{"PhoneNumber":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"e164":{"type":"string","description":"E.164 formatted phone number"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"type":{"type":"string","enum":["local","mobile","toll_free"]},"status":{"type":"string","enum":["active","inactive","pending"]},"endpoint_id":{"type":"string","format":"uuid","nullable":true},"allow_inbound":{"type":"boolean","default":true},"allow_outbound":{"type":"boolean","default":false},"sip_uri":{"type":"string","description":"SIP URI for inbound routing"},"organization_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"},"details":{"type":"object","additionalProperties":true,"description":"Additional error details"}}}},"responses":{"BadRequest":{"description":"Bad request - Invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/phone-numbers/{id}":{"patch":{"tags":["Phone Numbers"],"summary":"Update phone number settings","operationId":"updatePhoneNumber","parameters":[{"$ref":"#/components/parameters/PhoneNumberId"},{"$ref":"#/components/parameters/OrganizationId"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"endpointId":{"type":"string","format":"uuid","nullable":true,"description":"Endpoint to route calls to"},"allowInbound":{"type":"boolean","description":"Allow inbound calls"},"allowOutbound":{"type":"boolean","description":"Allow outbound calls"},"status":{"type":"string","enum":["active","inactive"]}}}}}},"responses":{"200":{"description":"Phone number updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumber"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.krosai.com/api-reference/reference/phone-numbers.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.