> ## 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. # Buy an extra number > Buys the offered number for the agent and adds its monthly price to the business's bill, with the same checks as the dashboard. It costs money every month, so Idempotency-Key is required and accept_monthly_price_cents must repeat the offer's price, or null for a free offer: anything else is a 400. Without the extra phone numbers add-on, from POST /billing/extra-numbers/checkout, a priced offer is a 409. A price that changed since the search is a 409 too; search again. Returns the claim at once; poll GET /phone-numbers/claims/{claim_id} until its status is claimed or failed. Claims are limited to 3 an hour, 2 a day and 5 in 30 days, past which they are a 429. ## OpenAPI ````yaml /api-reference/openapi.json post /phone-numbers/extra/claims 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/claims: post: tags: - Phone numbers summary: Buy an extra number description: >- Buys the offered number for the agent and adds its monthly price to the business's bill, with the same checks as the dashboard. It costs money every month, so Idempotency-Key is required and accept_monthly_price_cents must repeat the offer's price, or null for a free offer: anything else is a 400. Without the extra phone numbers add-on, from POST /billing/extra-numbers/checkout, a priced offer is a 409. A price that changed since the search is a 409 too; search again. Returns the claim at once; poll GET /phone-numbers/claims/{claim_id} until its status is claimed or failed. Claims are limited to 3 an hour, 2 a day and 5 in 30 days, past which they are a 429. operationId: createExtraPhoneNumberClaim 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 - name: Idempotency-Key in: header required: true description: >- Required. A unique value, up to 255 characters, that makes retries of this request safe. schema: type: string maxLength: 255 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExtraPhoneNumberClaimCreate' responses: '202': description: Accepted content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/PhoneNumberClaim' '400': description: >- The request is invalid (invalid_request), including a missing Idempotency-Key. 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' '422': description: >- The Idempotency-Key was already used with a different request body (idempotency_key_reused). 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: ExtraPhoneNumberClaimCreate: type: object properties: offer_token: type: string minLength: 1 maxLength: 4000 description: An offer_token from POST /phone-numbers/extra/search. agent_id: type: string format: uuid description: The agent whose calls the number takes. accept_monthly_price_cents: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' description: >- The offer's monthly_price.amount_cents, or null when its monthly_price is null. Anything else is a 400, so a script can't buy a number at a price it didn't read. required: - offer_token - agent_id - accept_monthly_price_cents additionalProperties: false PhoneNumberClaim: type: object properties: id: type: string format: uuid description: Stable identifier (UUID). status: type: string enum: - pending - provisioning - claimed - failed description: >- pending: waiting to be bought. provisioning: LobbyStack is buying the number and connecting it to the receptionist. claimed: the number is live and phone_number_id names it. failed: error says why; search again for another number. phone_number: type: string pattern: ^\+[1-9]\d{6,14}$ description: The number being claimed. phone_number_id: anyOf: - type: string format: uuid - type: 'null' description: The number's id once the claim is claimed. replaces_phone_number_id: anyOf: - type: string format: uuid - type: 'null' description: >- For a replacement, the number it replaces. That number keeps working until 30 days after the new one goes live. error: type: - string - 'null' created_at: type: string format: date-time description: ISO 8601 timestamp in UTC. updated_at: type: string format: date-time description: ISO 8601 timestamp in UTC. required: - id - status - phone_number - phone_number_id - replaces_phone_number_id - error - created_at - updated_at additionalProperties: false description: A request to buy a phone number for the business. 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.