Pricing

Search rates by prefix

Searches routed destinations by prefix, country, or destination label.

Try in API Playground ↗Sign in to prepare and run this request.

GET/api/v1/rates/search

Before you start

Provide a country or prefix filter to narrow the results.

Result

Read the matching destination and rate; use a full-number quote before dialing.

Charges and safe retries

A prefix result is not a guarantee that a particular number can be called.

Authentication

Send your account API key in the X-Api-Key header. Keep it on your server; never embed it in browser code.

Request examples

Replace the example values with your own inputs. Examples do not run on this page. Production requests can change your account or incur charges.

cURL

curl -X GET "https://api.illyvoip.com/api/v1/rates/search?q=4420&limit=25" \
  -H "X-Api-Key: ${ILLYVOIP_API_KEY:?Set ILLYVOIP_API_KEY}"

Node.js

const response = await fetch("https://api.illyvoip.com/api/v1/rates/search?q=4420&limit=25", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.ILLYVOIP_API_KEY
  }
});

const data = await response.json();
console.log(response.status, data);

PHP

<?php
$ch = curl_init('https://api.illyvoip.com/api/v1/rates/search?q=4420&limit=25');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('ILLYVOIP_API_KEY')
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response;

Python

import os
import json
import requests

response = requests.request(
    "GET",
    "https://api.illyvoip.com/api/v1/rates/search?q=4420&limit=25",
    headers={
        "X-Api-Key": os.environ["ILLYVOIP_API_KEY"]
    },
)

print(response.status_code)
print(response.json())

Node.js examples run on the server (Node.js 22.17+). Python examples require requests; PHP examples require cURL. Set the environment variables referenced in each example.

Request parameters

Query parameters

qstringoptional

Prefix or free-text search.

countrystringoptional

Optional country filter. Omit it to search prefixes across all countries.

limitintegeroptional

Row limit.

default 100minimum 1maximum 500

Request behavior

Use this when you need an exact selling rate for a prefix before placing a call.

Response fields

status: Request outcome. Read the resource state separately; success does not always mean delivery or completion.
package_name: Display name of your calling package.
rows: Matching results for the requested filter.
has_more: Whether another result page is available.
next_offset: Offset to use for the next result page when supplied.

HTTP responses

Expand a status to inspect its documented response format and examples. Example prices, IDs and timestamps are illustrative values, not quotes or account records.

200 Successful customer-facing response.

application/json

JSON

{
  "status": "success",
  "package_name": "Global Voice",
  "rows": [
    {
      "prefix": "4420",
      "destination": "United Kingdom · Fixed Line · GB London Region",
      "enabled": true,
      "rate_per_minute": "0.0400",
      "billing": {
        "init_seconds": 1,
        "increment_seconds": 1
      }
    }
  ],
  "has_more": false,
  "next_offset": 25
}

statusstringrequired

enum ["success"]

package_namestringrequired

Display name of the account package.

rowsarray<object>required

View nested fields

Array items

prefixstringrequired

destinationstringrequired

enabledbooleanrequired

rate_per_minutestringrequired

billingobjectrequired

View nested fields

init_secondsintegerrequired

increment_secondsintegerrequired

Additional properties: not allowed.

has_morebooleanrequired

next_offsetintegerrequired

nullable trueminimum 0

Additional properties: not allowed.

Full schema

Schema

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success"
      ]
    },
    "package_name": {
      "type": "string",
      "description": "Display name of the account package."
    },
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "prefix": {
            "type": "string"
          },
          "destination": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "rate_per_minute": {
            "type": "string"
          },
          "billing": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "init_seconds": {
                "type": "integer"
              },
              "increment_seconds": {
                "type": "integer"
              }
            },
            "required": [
              "init_seconds",
              "increment_seconds"
            ]
          }
        },
        "required": [
          "prefix",
          "destination",
          "enabled",
          "rate_per_minute",
          "billing"
        ]
      }
    },
    "has_more": {
      "type": "boolean"
    },
    "next_offset": {
      "type": "integer",
      "nullable": true,
      "minimum": 0
    }
  },
  "required": [
    "status",
    "package_name",
    "rows",
    "has_more",
    "next_offset"
  ]
}

400 The request failed validation.

application/json

statusstringrequired

enum ["error"]

messagestringrequired

error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true

fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema

Schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}

401 The API key or browser token is missing or invalid.

application/json

statusstringrequired

enum ["error"]

messagestringrequired

error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true

fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema

Schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}

403 The account is not allowed to perform this operation.

application/json

statusstringrequired

enum ["error"]

messagestringrequired

error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true

fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema

Schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}

429 The request rate limit was exceeded.

application/json

statusstringrequired

enum ["error"]

messagestringrequired

error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true

fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema

Schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}

500 An unexpected service error occurred.

application/json

statusstringrequired

enum ["error"]

messagestringrequired

error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true

fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema

Schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}

503 The service is temporarily unavailable.

application/json

statusstringrequired

enum ["error"]

messagestringrequired

error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true

fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema

Schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}

Sandbox scenarios

Use https://sandbox-api.illyvoip.com with Sandbox credentials and the X-Illyvoip-Sandbox-Scenario header. Omit the header for the documented success default. This header belongs to sandbox requests.

success, not-found, rate-limited, forbidden, service-unavailable

Try this operation in Sandbox · Environment setup and limitations

Search rates by prefix

Before you start

Result

Charges and safe retries

Authentication

Request examples

cURL

Node.js

PHP

Python

Request parameters

Query parameters

Request behavior

Response fields

HTTP responses

application/json

application/json

application/json

application/json

application/json

application/json

application/json

Sandbox scenarios

Related reference