> ## 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 numbers to claim > Searches the carrier for numbers that take calls; a self-hosted business gets only numbers that also take texts. Each offer expires after 5 minutes. On the cloud, a business on a paid plan gets numbers it buys. One without a paid plan gets free trial offers (trial: true) when the account the key acts as verified a mobile number for it in the dashboard, in a country with trials, and no trial was used; otherwise it gets a 409. The account a key acts as can search 20 times in 10 minutes; searches refused before that don't count. Send replaces to find a replacement for an active number; a business can replace its number once. ## OpenAPI ````yaml /api-reference/openapi.json post /phone-numbers/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: 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/search: post: tags: - Phone numbers summary: Find numbers to claim description: >- Searches the carrier for numbers that take calls; a self-hosted business gets only numbers that also take texts. Each offer expires after 5 minutes. On the cloud, a business on a paid plan gets numbers it buys. One without a paid plan gets free trial offers (trial: true) when the account the key acts as verified a mobile number for it in the dashboard, in a country with trials, and no trial was used; otherwise it gets a 409. The account a key acts as can search 20 times in 10 minutes; searches refused before that don't count. Send replaces to find a replacement for an active number; a business can replace its number once. operationId: searchPhoneNumbers 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/PhoneNumberSearch' responses: '200': description: OK content: application/json: schema: type: object required: - data - next_cursor - has_more properties: data: type: array items: $ref: '#/components/schemas/PhoneNumberOffer' 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: PhoneNumberSearch: type: object properties: country: description: >- Defaults to the country of the business's time zone, or US. When the account the key acts as verified a mobile number for this business, that number's country decides. A deployment offers US and CA, and GB, AU and NZ once its carrier is set up for them. type: string enum: - US - CA - GB - AU - NZ kind: description: >- Defaults to local. GB and AU numbers are always mobile, and NZ numbers local. 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 replaces: description: >- The id of an active number to replace. The offers are then replacements, which only POST /phone-numbers/{phone_number_id}/replace accepts. type: string format: uuid additionalProperties: false PhoneNumberOffer: 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 - 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 trial: type: boolean description: >- A free trial number, offered to a cloud business without a paid plan, as in the dashboard: once per business, per account and verified phone, and per network in 30 days. It stops answering when the trial ends unless the business starts a paid plan. offer_token: type: string description: >- Claim 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 - trial - offer_token - expires_at additionalProperties: false description: A number the business can claim. 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.