> ## Documentation Index > Fetch the complete documentation index at: https://docs.blujay.io/llms.txt > Use this file to discover all available pages before exploring further. # List phone numbers > Returns the Blujay numbers in your workspace. For each number you get whether it can send right now (`send_status`), what it supports (`capabilities`), and its link rules (`outbound_policy`). Dedicated numbers also report `health_status`, `queue`, and `limits`. Sending limits and queue capacity, such as how many new contacts a number can message per day, are specific to each number and change over time. Read the live values from `limits` and `queue` instead of hard-coding them. ## OpenAPI ````yaml /api-reference/openapi.yaml get /v1/phone-numbers openapi: 3.1.0 info: title: Blujay API version: 1.0.0 description: >- The Blujay API lets you send and receive iMessage, RCS and SMS messages from your Blujay phone numbers, manage contacts, and receive real-time webhooks. Every response uses the same JSON envelope and carries a `trace_id` you can share with support. Authenticate with your workspace API key. servers: - url: https://api.blujay.io description: Production security: - PublicApiKey: [] tags: - name: Auth description: Check which workspace and credential a request is using. - name: Chats description: >- Direct and group conversations between your Blujay numbers and your contacts. - name: Messages description: Send, read, edit, unsend and retry messages. - name: Phone Numbers description: >- Your Blujay numbers, whether each can send right now, and their live sending limits. - name: Capability description: >- Check whether a phone number can be reached by iMessage, RCS or SMS before you send. - name: Contacts description: Create, find, update, tag, assign and opt out contacts. - name: vCards description: >- Saved contact cards that you can send in a message. Recipients get a native contact card over iMessage, SMS or RCS. - name: Team Members description: People in your workspace you can assign contacts to. - name: Workflows description: Enroll contacts in workflows you start manually. - name: Attachments description: >- Upload files once and reuse them in messages, or download files from messages. - name: Webhooks description: Subscribe to events, inspect delivery attempts and verify signatures. paths: /v1/phone-numbers: get: tags: - Phone Numbers summary: List phone numbers description: > Returns the Blujay numbers in your workspace. For each number you get whether it can send right now (`send_status`), what it supports (`capabilities`), and its link rules (`outbound_policy`). Dedicated numbers also report `health_status`, `queue`, and `limits`. Sending limits and queue capacity, such as how many new contacts a number can message per day, are specific to each number and change over time. Read the live values from `limits` and `queue` instead of hard-coding them. operationId: listPublicPhoneNumbers responses: '200': description: >- Your active phone numbers, oldest first. Retired numbers are left out; read one with `GET /v1/phone-numbers/{phone_number_id}`. headers: X-Trace-ID: $ref: '#/components/headers/XTraceID' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object required: - data properties: data: type: object required: - phone_numbers properties: phone_numbers: type: array items: $ref: '#/components/schemas/PublicPhoneNumber' examples: availableSender: summary: A dedicated number value: status: success data: phone_numbers: - phone_number_id: phone_abc123 display_number: '+15555550100' label: Sales status: active line_type: outbound access_type: dedicated send_status: allowed: true health_status: status: healthy score: 98 as_of: '2026-10-14T17:00:00.000Z' freshness: fresh limits: new_contacts: used_today: 12 limit_per_day: 50 remaining_today: 38 reset_at: '2026-10-15T07:00:00.000Z' daily: used_today: 140 guideline: 250 remaining_to_guideline: 110 enforced: false queue: pending: 3 capacity: 1500 remaining: 1497 capabilities: messaging: outbound: true inbound: true media_attachments: true link_parts: true voice: outbound_ready: true inbound_forwarding_ready: true outbound_policy: inbound_first: false first_message_links_allowed: false follow_up_links_allowed: true daily_total_enforced: false trace_id: trc_8f2a1c0e4b7d timestamp: '2026-10-14T17:00:00.000Z' security: - PublicApiKey: [] components: headers: XTraceID: description: >- Unique ID for this request. It matches `trace_id` in the body. Include it when you contact Blujay support. schema: $ref: '#/components/schemas/TraceId' schemas: SuccessEnvelope: type: object description: Wraps every successful response. The result is in `data`. required: - status - trace_id - timestamp properties: status: type: string enum: - success trace_id: $ref: '#/components/schemas/TraceId' timestamp: type: string examples: - '2026-10-14T17:01:00.000Z' format: date-time client_request_id: type: string description: >- Your `X-Request-ID` header value, echoed back when you send one. Not included on the send responses (`POST /v1/chats`, `POST /v1/chats/{chat_id}/messages`, `POST /v1/messages/{message_id}/retry`); keep your own mapping from your request ID to the returned message ID there. PublicPhoneNumber: type: object description: >- A Blujay number in your workspace and what it can do right now. Numbers on the Shared Free Plan omit health, limits, queue and calling readiness. additionalProperties: false required: - phone_number_id - display_number - status - line_type - access_type - send_status - capabilities - outbound_policy properties: phone_number_id: $ref: '#/components/schemas/PhoneNumberId' display_number: type: string examples: - '+15555550100' label: type: string examples: - Support line status: type: string enum: - active - unavailable line_type: type: string enum: - outbound access_type: type: string enum: - shared - dedicated description: >- `dedicated` for a number that belongs to your workspace; `shared` for a number on the Shared Free Plan. send_status: type: object description: >- Whether the number can send right now. When `allowed` is false, `reason_code` and `reason` say why. additionalProperties: false required: - allowed properties: allowed: type: boolean reason: type: string reason_code: type: string enum: - sender_retired - number_inactive - number_setup_incomplete description: > - `sender_retired`: the phone number was retired. Send from an active number. - `number_inactive`: the phone number isn't active. - `number_setup_incomplete`: the phone number isn't set up for messaging yet. health_status: type: object description: Dedicated-line health. Omitted on the Shared Free Plan. additionalProperties: false required: - status properties: status: type: string enum: - healthy - degraded - critical - unknown score: type: number examples: - 98 minimum: 0 maximum: 100 as_of: type: string examples: - '2026-10-14T17:01:00.000Z' format: date-time freshness: type: string examples: - fresh limits: type: object description: >- Live sending limits for a dedicated number. The values are specific to each number and change over time, so read them here each time instead of hard-coding them. Omitted on the Shared Free Plan. additionalProperties: false required: - new_contacts - daily properties: new_contacts: type: object description: >- New contacts this number has messaged today, against its daily limit. additionalProperties: false required: - used_today - limit_per_day - remaining_today - reset_at properties: used_today: type: integer minimum: 0 limit_per_day: type: integer minimum: 0 remaining_today: type: integer minimum: 0 reset_at: type: string examples: - '2026-10-14T17:01:00.000Z' format: date-time daily: type: object description: >- Messages sent today, against a recommended daily total. When `enforced` is false, the guideline is advice, not a hard limit. additionalProperties: false required: - used_today - guideline - remaining_to_guideline - enforced properties: used_today: type: integer minimum: 0 guideline: type: integer minimum: 0 remaining_to_guideline: type: integer minimum: 0 enforced: type: boolean queue: type: object description: >- Messages waiting to send from this dedicated number. Capacity is specific to each number and can change over time, so read it here each time instead of hard-coding it. When `remaining` reaches 0, sends return `429 QUEUE_FULL`. Omitted on the Shared Free Plan. additionalProperties: false required: - pending - capacity - remaining properties: pending: type: integer minimum: 0 capacity: type: integer minimum: 0 remaining: type: integer minimum: 0 capabilities: type: object additionalProperties: false required: - messaging properties: messaging: type: object additionalProperties: false required: - outbound - inbound - media_attachments - link_parts properties: outbound: type: boolean inbound: type: boolean media_attachments: type: boolean link_parts: type: boolean voice: type: object description: >- Whether this number is ready for calling. Omitted on the Shared Free Plan. additionalProperties: false required: - outbound_ready - inbound_forwarding_ready properties: outbound_ready: type: boolean inbound_forwarding_ready: type: boolean outbound_policy: type: object description: >- Sending rules for this number, such as whether it can start conversations and whether links are allowed in a chat's first message. additionalProperties: false required: - inbound_first - first_message_links_allowed - follow_up_links_allowed - daily_total_enforced properties: inbound_first: type: boolean description: >- True when this number can only message people who texted it first (Free Plan and AI Agent numbers). Skip these when you start conversations; a first send from one returns `CONTACT_NOT_VERIFIED` or `CONTACT_MUST_TEXT_FIRST`. first_message_links_allowed: type: boolean follow_up_links_allowed: type: boolean daily_total_enforced: type: boolean TraceId: type: string examples: - trc_8f2a1c0e4b7d pattern: ^trc_[A-Za-z0-9_-]+$ PhoneNumberId: type: string examples: - phone_abc123 pattern: ^phone_[A-Za-z0-9_-]+$ securitySchemes: PublicApiKey: type: http scheme: bearer bearerFormat: blu_... description: > Your workspace API key, sent as `Authorization: Bearer blu_...`. Workspace admins can find it in the Blujay app under **API**. An API key has full access to your workspace and works on every endpoint. There is no test mode: every key sends real messages and changes real data, so keep it secret and use it only from your server. Each API key can make 600 read requests and 120 write requests per minute, plus 60 attachment requests per minute. Over a limit you get `429 RATE_LIMIT_EXCEEDED` with `Retry-After`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.