Available numbers

Search for phone numbers that are available to order. Use this endpoint for national and mobile numbers. For local numbers, use the verification group endpoint instead.

Endpoint

GET /v1/phone-numbers/available

Query Parameters

Parameter	Type	Required	Default	Description
`number_type`	string	No	`national`	Type of numbers: `national` or `mobile`
`query`	string	No	-	Filter by phone number pattern
`limit`	integer	No	`20`	Maximum results (1-50)

Note: For local numbers, you must use /v1/verification-groups/{id}/available-phone-numbers with an approved verification group.

Example Request

Example Response

{
  "data": [
    {
      "phone_number": "+31851234567",
      "number_type": "national",
      "locality": null,
      "features": ["voice", "sms"],
      "cost": {
        "monthly": "2.00",
        "currency": "EUR",
        "credits": 10
      },
      "reservable": true
    },
    {
      "phone_number": "+31851234568",
      "number_type": "national",
      "locality": null,
      "features": ["voice"],
      "cost": {
        "monthly": "2.00",
        "currency": "EUR",
        "credits": 10
      },
      "reservable": true
    }
  ],
  "meta": {
    "total_results": 2,
    "number_type": "national",
    "requires_verification": false
  }
}

Response Fields

Field	Type	Description
`phone_number`	string	Available phone number in E.164 format
`number_type`	string	Type of number
`locality`	string	City/region (null for national/mobile)
`features`	array	Supported features: `voice`, `sms`
`cost.monthly`	string	Monthly cost in EUR
`cost.credits`	integer	Credits required to order (10)
`reservable`	boolean	Whether this number can be ordered

Response JSON Schema

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "phone_number": { "type": "string" },
          "number_type": { "type": "string" },
          "locality": { "type": "string", "nullable": true },
          "features": { 
            "type": "array", 
            "items": { "type": "string" } 
          },
          "cost": {
            "type": "object",
            "properties": {
              "monthly": { "type": "string" },
              "currency": { "type": "string" },
              "credits": { "type": "integer" }
            }
          },
          "reservable": { "type": "boolean" }
        }
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "total_results": { "type": "integer" },
        "number_type": { "type": "string" },
        "requires_verification": { "type": "boolean" }
      }
    }
  }
}

Next:
Ready to order? See order a phone number.

Endpoint#

Query Parameters#

Example Request#

Example Response#