> ## 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. # Claim a number > Buys the offered number for the business and connects it to the receptionist. It costs money, so Idempotency-Key is required. Returns the claim at once; poll GET /phone-numbers/claims/{claim_id} until its status is claimed or failed. A business that already has a number, including one still being released, or another claim in progress gets a 409. Claims are limited to 3 an hour, 2 a day and 5 in 30 days, past which they are a 429. Platform keys count each business's claims; other keys count the claims of the account they act as. A trial offer starts the business's 14-day free trial. As in the dashboard, each business, account and verified phone gets one trial. The dashboard also allows one trial per network in 30 days, and the API doesn't: an integration claims for all of its customers from the same addresses. ## OpenAPI ````yaml /api-reference/openapi.json post /phone-numbers/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: 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 paths: /phone-numbers/claims: post: tags: - Phone numbers summary: Claim a number description: >- Buys the offered number for the business and connects it to the receptionist. It costs money, so Idempotency-Key is required. Returns the claim at once; poll GET /phone-numbers/claims/{claim_id} until its status is claimed or failed. A business that already has a number, including one still being released, or another claim in progress gets a 409. Claims are limited to 3 an hour, 2 a day and 5 in 30 days, past which they are a 429. Platform keys count each business's claims; other keys count the claims of the account they act as. A trial offer starts the business's 14-day free trial. As in the dashboard, each business, account and verified phone gets one trial. The dashboard also allows one trial per network in 30 days, and the API doesn't: an integration claims for all of its customers from the same addresses. operationId: createPhoneNumberClaim 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/PhoneNumberClaimCreate' 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: PhoneNumberClaimCreate: type: object properties: offer_token: type: string minLength: 1 maxLength: 4000 description: An offer_token from POST /phone-numbers/search. required: - offer_token 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 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. Only platform keys can hold businesses:create and users:create. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.