IllyVoIPdevelopers

Pricing

Quick quote

Returns the billed rate for one destination number.

Try in API Playground ↗Sign in to prepare and run this request.
GET/api/v1/rates/quote

Before you start

Provide the complete destination number and the documented account options.

Result

Read the returned price for the destination and inspect any restrictions.

Charges and safe retries

A quote does not create a call or reserve a rate indefinitely.

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
curl -X GET "https://api.illyvoip.com/api/v1/rates/quote?number=YOUR_PHONE_NUMBER" \
  -H "X-Api-Key: ${ILLYVOIP_API_KEY:?Set ILLYVOIP_API_KEY}"

Node.js

Node.js
const response = await fetch("https://api.illyvoip.com/api/v1/rates/quote?number=YOUR_PHONE_NUMBER", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.ILLYVOIP_API_KEY
  }
});

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

PHP

PHP
<?php
$ch = curl_init('https://api.illyvoip.com/api/v1/rates/quote?number=YOUR_PHONE_NUMBER');
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

Python
import os
import json
import requests

response = requests.request(
    "GET",
    "https://api.illyvoip.com/api/v1/rates/quote?number=YOUR_PHONE_NUMBER",
    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

numberstringrequired

Destination number in international format.

Request behavior

Use this before dialing if you need a precise quote from the current package and routing config. The response also includes the same final lookup metadata used by the standalone lookup endpoint when it is available.

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.
  • lookup: Normalized number and the requested number information; missing optional fields are not proof of inactivity.
  • quote: Customer price estimate and applicable conditions for the selected request.

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",
  "lookup": {
    "requested_number": "+442045255794",
    "normalized_number": "+442045255794",
    "original_number": "+442045255794",
    "number_type": "Fixed Line",
    "location": "GB London Region",
    "region_code": "GB",
    "country_code": 44,
    "valid_number_format": true,
    "formatted_international": "+44 20 4525 5794",
    "formatted_national": "020 4525 5794",
    "formatted_e164": "+442045255794",
    "carrier": "GB London Region",
    "time_zones": [
      "Europe/London"
    ]
  },
  "quote": {
    "number": "+442045255794",
    "prefix": "4420",
    "destination": "United Kingdom · Fixed Line · GB London Region",
    "enabled": true,
    "rate_per_minute": "0.0400",
    "billing": {
      "init_seconds": 1,
      "increment_seconds": 1
    }
  }
}
statusstringrequired
enum ["success"]
package_namestringrequired

Display name of the account package.

lookupobjectrequired
View nested fields
requested_numberstringrequired
normalized_numberstringrequired
original_numberstringrequired
number_typestringrequired
locationstringrequired
region_codestringrequired
country_codeintegerrequired
valid_number_formatbooleanrequired
formatted_internationalstringrequired
formatted_nationalstringrequired
formatted_e164stringrequired
carrierstringrequired
time_zonesarray<string>required
View nested fields

Array items

Type: string

Additional properties: not allowed.

quoteobjectrequired
View nested fields
numberstringrequired
prefixstringrequired
destinationstringrequired
enabledbooleanrequired
rate_per_minutestringrequired
billingobjectrequired
View nested fields
init_secondsintegerrequired
increment_secondsintegerrequired

Additional properties: not allowed.

Additional properties: not allowed.

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."
    },
    "lookup": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "requested_number": {
          "type": "string"
        },
        "normalized_number": {
          "type": "string"
        },
        "original_number": {
          "type": "string"
        },
        "number_type": {
          "type": "string"
        },
        "location": {
          "type": "string"
        },
        "region_code": {
          "type": "string"
        },
        "country_code": {
          "type": "integer"
        },
        "valid_number_format": {
          "type": "boolean"
        },
        "formatted_international": {
          "type": "string"
        },
        "formatted_national": {
          "type": "string"
        },
        "formatted_e164": {
          "type": "string"
        },
        "carrier": {
          "type": "string"
        },
        "time_zones": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "requested_number",
        "normalized_number",
        "original_number",
        "number_type",
        "location",
        "region_code",
        "country_code",
        "valid_number_format",
        "formatted_international",
        "formatted_national",
        "formatted_e164",
        "carrier",
        "time_zones"
      ]
    },
    "quote": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "number": {
          "type": "string"
        },
        "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": [
        "number",
        "prefix",
        "destination",
        "enabled",
        "rate_per_minute",
        "billing"
      ]
    }
  },
  "required": [
    "status",
    "package_name",
    "lookup",
    "quote"
  ]
}
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

List priced countriesSearch rates by prefix

Search API operations, parameters, SDK and webhooks.