> ## Documentation Index > Fetch the complete documentation index at: https://docs.lobbystack.com/llms.txt > Use this file to discover all available pages before exploring further. # Find extra numbers to buy > Searches the carrier for numbers a business that has its first number can buy for another of its agents. Starter, Pro and Enterprise sell them, each at the carrier's monthly price for its country and kind with no markup, billed monthly through the extra phone numbers add-on; monthly_price says what each costs. A self-hosted server's cost nothing extra. A business without a paid plan, without a number yet, or a partner's business is a 409. Each offer expires after 5 minutes, and searches count against the same limit as POST /phone-numbers/search. Partner platform keys can't buy extra numbers. ## OpenAPI ````yaml /api-reference/openapi.json post /phone-numbers/extra/search openapi: 3.1.0 info: title: LobbyStack API version: v1 description: >- Read calls, contacts, appointments and messages, book appointments, and subscribe to webhooks. Authenticate with an API key in the Authorization header. A platform key also names the business it acts on in the LobbyStack-Business header. Each key allows 120 requests per minute by default. servers: - url: https://app.lobbystack.com/api/v1 security: - bearerAuth: [] tags: - name: Business - name: Receptionist - name: Agents - name: Billing - name: Phone numbers - name: Onboarding - name: Team - name: Website chat - name: Calendars - name: Notifications - name: Calls - name: Contacts - name: Appointments - name: Messages - name: Knowledge - name: Webhooks - name: Platform - name: Partner paths: /phone-numbers/extra/search: post: tags: - Phone numbers summary: Find extra numbers to buy description: >- Searches the carrier for numbers a business that has its first number can buy for another of its agents. Starter, Pro and Enterprise sell them, each at the carrier's monthly price for its country and kind with no markup, billed monthly through the extra phone numbers add-on; monthly_price says what each costs. A self-hosted server's cost nothing extra. A business without a paid plan, without a number yet, or a partner's business is a 409. Each offer expires after 5 minutes, and searches count against the same limit as POST /phone-numbers/search. Partner platform keys can't buy extra numbers. operationId: searchExtraPhoneNumbers parameters: - name: LobbyStack-Business in: header description: >- The business a platform key acts on. Required with a platform key. A per-business key may leave it out; if it sends one, it must be the key's own business. schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExtraPhoneNumberSearch' responses: '200': description: OK content: application/json: schema: type: object required: - data - next_cursor - has_more properties: data: type: array items: $ref: '#/components/schemas/ExtraPhoneNumberOffer' next_cursor: type: - string - 'null' description: >- Pass as cursor to get the next page. Null on the last page. has_more: type: boolean '400': description: >- The request is invalid (invalid_request), or a platform key sent no LobbyStack-Business header (business_required). content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: The API key is missing, invalid, or revoked (unauthorized). content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Refused. insufficient_scope: the key lacks the phone_numbers:manage scope. forbidden: a per-business key named another business in LobbyStack-Business. key_owner_inactive: the person the key acts for can't any more: a per-business key's creator is no longer an owner or admin, or a platform key's owner_email has no verified LobbyStack account. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: A platform key named a business it cannot act on (not_found). content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: The request conflicts with the current state. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Too many requests (rate_limited). Wait for the Retry-After header's number of seconds. content: application/json: schema: $ref: '#/components/schemas/Error' headers: Retry-After: schema: type: integer description: Seconds to wait. security: - bearerAuth: [] components: schemas: ExtraPhoneNumberSearch: type: object properties: country: description: Defaults to the country of the business's time zone, or US. type: string enum: - US - CA - PR - GB - AU - NZ kind: description: >- Defaults to local. GB and AU numbers are always mobile, and NZ numbers local. A kind a country doesn't sell as an extra number is a 400. type: string enum: - local - mobile - toll_free area_code: type: string pattern: ^\d{1,6}$ city: type: string minLength: 1 maxLength: 100 region: description: A state or province, such as ON or NY. type: string minLength: 1 maxLength: 64 postal_code: type: string minLength: 1 maxLength: 16 limit: description: How many offers to return. Defaults to 10. type: integer minimum: 1 maximum: 20 additionalProperties: false ExtraPhoneNumberOffer: type: object properties: phone_number: type: string pattern: ^\+[1-9]\d{6,14}$ description: Phone number in E.164 format. country: type: string enum: - US - CA - PR - GB - AU - NZ kind: type: string enum: - local - mobile - toll_free locality: description: The city or area the number belongs to, when the carrier says. type: - string - 'null' region: type: - string - 'null' capabilities: type: object properties: voice: type: boolean sms: type: boolean required: - voice - sms additionalProperties: false monthly_price: anyOf: - type: object properties: amount_cents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 currency: type: string const: USD required: - amount_cents - currency additionalProperties: false - type: 'null' description: >- What the number costs each month, the carrier's price for its country and kind with no markup. Null on a self-hosted server, where extra numbers cost nothing extra. add_on_active: type: boolean description: >- Whether the business has the extra phone numbers add-on, which bills its extra numbers monthly. A priced number can't be bought without it: get it with POST /billing/extra-numbers/checkout. offer_token: type: string description: >- Buy the number with this before expires_at. Only this business and the account the key acts as can use it. expires_at: type: string format: date-time description: ISO 8601 timestamp in UTC. required: - phone_number - country - kind - locality - region - capabilities - monthly_price - add_on_active - offer_token - expires_at additionalProperties: false description: >- A number the business can buy for one of its agents, on top of the one its plan includes. Error: type: object properties: error: type: object properties: code: type: string enum: - invalid_request - unauthorized - forbidden - insufficient_scope - not_found - conflict - idempotency_key_reused - idempotency_request_in_progress - booking_disabled - booking_requires_confirmation - slot_unavailable - rate_limited - rate_limit_unavailable - method_not_allowed - internal_error - business_required - key_owner_inactive - plan_limit_reached - phone_numbers_unavailable message: type: string details: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: false required: - code - message additionalProperties: false required: - error additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key from Settings > API keys (lsk_...), which acts on its own business, or a platform key from the PLATFORM_API_KEYS setting (lsp_...), which onboards and manages businesses. Scopes: business:read, business:write, calls:read, contacts:read, contacts:write, appointments:read, appointments:write, messages:read, knowledge:read, knowledge:write, webhooks:manage, billing:manage, phone_numbers:manage, team:manage, businesses:create, users:create, phone_numbers:purchase, partner:read, partner.businesses:write, partner.demos:write, partner.packages:write, partner.branding:write, partner.templates:write, partner.team:write, partner.billing:read, partner.billing:write. Only platform keys can hold businesses:create and users:create, and only a key a partner made in its console can hold the partner scopes, which the Partner endpoints use. Only a partner's owners grant partner.billing:read and partner.billing:write. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.