> ## Documentation Index > Fetch the complete documentation index at: https://hellotars.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List phone numbers > Find organization phone numbers by status, source, health, country, tag and use. > [!NOTE] > > This capability is in **beta**. Behavior can change before general availability. Filters include search, status, source, health, country, tag and use. Use can be voice, sms\_conversations or none. Omitting use lists every number. Page sizes are 10, 20, 50 or 100, with 50 as the default. The key needs **Read phone numbers**, an organization-wide permission. ## Related pages * [Authentication](https://hellotars.com/docs/developer/authentication.md) ## OpenAPI ````yaml api-reference/openapi.json GET /api/v1/phone-numbers openapi: 3.1.0 info: title: Tars API version: '1' description: >- Start conversations, send messages, manage contacts, send campaign messages, place and read calls, and manage webhook destinations. servers: - url: https://us.api.hellotars.com description: United States - url: https://eu.api.hellotars.com description: European Union - url: https://in.api.hellotars.com description: India - url: https://qa.api.hellotars.com description: Qatar security: - bearerAuth: [] tags: - name: Conversations description: Start conversations at a chat agent's trigger step. - name: Messages description: Send channel messages as a chat agent. - name: Contacts description: Read and manage contacts. - name: Campaigns description: Send webhook campaign messages. - name: Calls description: Place, read and manage phone calls. - name: Agents description: Read chat agents and voice agents. - name: Phone numbers description: Read your phone numbers. - name: Artefacts description: Download call recordings. - name: Webhooks description: Manage webhook destinations. paths: /api/v1/phone-numbers: get: tags: - Phone numbers summary: List phone numbers description: |- Lists your phone numbers. limit takes 10, 20, 50 or 100. Requires the Read phone numbers permission (`phone_numbers:read`). operationId: listPhoneNumbers parameters: - name: search in: query required: false schema: type: string description: Text to search for. - name: status in: query required: false schema: type: string enum: - purchasing - importing - verifying - unverified - active - suspended - failed - releasing - released - name: source in: query required: false schema: type: string enum: - tars - twilio_account - sip - name: health in: query required: false schema: type: string enum: - healthy - degraded - failed - unknown - name: country in: query required: false schema: type: string pattern: ^[A-Z]{2}$ description: ISO country code. - name: tag in: query required: false schema: type: string - name: use in: query required: false schema: type: string enum: - voice - sms_conversations - none description: Absent lists every number. - name: limit in: query required: false schema: type: integer enum: - 10 - 20 - 50 - 100 default: 50 - name: cursor in: query required: false schema: type: string maxLength: 1024 description: The nextCursor of the previous page. responses: '200': description: One page of results. content: application/json: schema: allOf: - $ref: '#/components/schemas/Page' - properties: items: type: array items: $ref: '#/components/schemas/PhoneNumber' '400': description: validation_failed, cursor_mismatch content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '401': description: unauthorized, invalid_key headers: WWW-Authenticate: schema: const: Bearer content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '403': description: organization_inactive, billing_locked, permission_missing content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '405': description: method_not_allowed headers: Allow: description: The methods this path accepts. schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '409': description: wrong_region content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '429': description: rate_limited headers: Retry-After: description: Whole seconds to wait before retrying. schema: type: integer minimum: 1 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '500': description: internal_error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - bearerAuth: [] components: schemas: Page: type: object description: One page of a list. properties: items: type: array items: {} nextCursor: type: - string - 'null' description: Pass it as cursor to read the next page. hasMore: type: boolean required: - items - nextCursor - hasMore PhoneNumber: type: object properties: id: type: string description: A phoneNumbers id. e164: type: string nickname: type: string source: enum: - tars - twilio_account - sip carrier: enum: - twilio - sip_generic platform: anyOf: - enum: - telnyx_own - vonage - genesys_cloud - avaya - five9 - amazon_connect - other - type: 'null' country: type: string numberType: enum: - local - toll_free status: enum: - purchasing - importing - verifying - unverified - active - suspended - failed - releasing - released health: enum: - healthy - degraded - failed - unknown tags: type: array items: type: string capabilities: type: object properties: voice: type: boolean sms: type: boolean required: - voice - sms phoneAccount: anyOf: - type: 'null' - type: object properties: id: type: string description: A phoneAccounts id. friendlyName: type: string accountSidMasked: type: string status: enum: - active - invalid_credentials - disconnecting - disconnected required: - id - friendlyName - accountSidMasked - status uses: type: object properties: calls: type: boolean texts: type: boolean smsConversations: type: boolean smsDeploymentName: anyOf: - type: string - type: 'null' required: - calls - texts - smsConversations - smsDeploymentName createdAt: type: number inbound: type: object properties: enabled: type: boolean targetCount: type: number firstAgentName: anyOf: - type: string - type: 'null' latestPublishedVersion: anyOf: - type: number - type: 'null' required: - enabled - targetCount - firstAgentName - latestPublishedVersion outbound: type: object properties: enabled: type: boolean targetCount: type: number firstAgentName: anyOf: - type: string - type: 'null' latestPublishedVersion: anyOf: - type: number - type: 'null' required: - enabled - targetCount - firstAgentName - latestPublishedVersion required: - id - e164 - nickname - source - carrier - platform - country - numberType - status - health - tags - capabilities - phoneAccount - uses - createdAt - inbound - outbound Problem: type: object description: >- RFC 9457 problem details. Clients switch on code, never on title or detail. properties: title: type: string description: The catalogue title of code. status: type: integer description: The HTTP status. detail: type: string description: A sentence about this failure, for a developer. instance: type: string description: The request id (req_…). Quote it when you contact support. code: type: string enum: - invalid_json - validation_failed - variable_key_not_allowed - invalid_variable_value - cursor_expired - cursor_mismatch - campaign_mode_invalid - unauthorized - invalid_key - session_invalid - insufficient_balance - organization_inactive - billing_locked - permission_missing - resource_not_allowed - entitlement_missing - origin_not_allowed - recaptcha_failed - consent_revoked - us_marketing_blocked - channel_test_mode - quota_exceeded - forbidden - not_found - method_not_allowed - wrong_region - conflict - contact_exists - idempotency_key_reuse - agent_unavailable - call_not_live - call_still_live - call_content_deleted - invalid_state - campaign_paused - template_version_drift - channel_unavailable - artefact_deleted - campaign_gone - payload_too_large - template_not_approved - channel_misconfigured - channel_reauth_required - meta_rejected - rate_limited - concurrency_limit_reached - worker_busy - meta_rate_limited - internal_error - upstream_unavailable - meta_unavailable - worker_not_deployed - worker_unavailable retryable: type: boolean description: true when the same request can succeed later. errors: type: array items: $ref: '#/components/schemas/ValidationIssue' required: type: string description: The permission the key lacks (permission_missing). region: type: string description: The organization's region (wrong_region). field: type: string enum: - email - phone contactId: type: string description: The contact that already has the email or phone. callId: type: string reason: type: string required: - title - status - detail - instance - code - retryable ValidationIssue: type: object description: One field that failed validation. properties: path: type: string description: >- Dotted path of the field (template.parameters.body.0), the query parameter name, or an empty string for the whole body. code: type: string description: >- Why the field failed, for example required, unknown_field, out_of_range or template_param_missing. message: type: string required: - path - code securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key (`tars_sk_…`) sent as `Authorization: Bearer `. Each operation names the permission it needs. Create keys in Settings → Integrations → API keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.