IllyVoIPdevelopers

Phone Numbers

Quote DID order

Returns a time-limited customer-facing quote before order creation.

Try in API Playground ↗Sign in to prepare and run this request.
POST/api/v1/dids/orders/quote

Before you start

Select the number and rental choices before creating an order.

Result

Review rental, setup and calling charges; pass pricing_fingerprint into the order request.

Charges and safe retries

A quote does not place an order. Review conditions and current availability before buying.

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 POST "https://api.illyvoip.com/api/v1/dids/orders/quote" \
  -H "X-Api-Key: ${ILLYVOIP_API_KEY:?Set ILLYVOIP_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "country_iso": "CA",
    "region_code": "249",
    "number_type": "local",
    "product_reference": "YOUR_PRODUCT_REFERENCE",
    "quantity": 1
}'

Node.js

Node.js
const response = await fetch("https://api.illyvoip.com/api/v1/dids/orders/quote", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.ILLYVOIP_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "country_iso": "CA",
    "region_code": "249",
    "number_type": "local",
    "product_reference": "YOUR_PRODUCT_REFERENCE",
    "quantity": 1
})
});

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

PHP

PHP
<?php
$ch = curl_init('https://api.illyvoip.com/api/v1/dids/orders/quote');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('ILLYVOIP_API_KEY'),
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => '{
    "country_iso": "CA",
    "region_code": "249",
    "number_type": "local",
    "product_reference": "YOUR_PRODUCT_REFERENCE",
    "quantity": 1
}',
]);

$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(
    "POST",
    "https://api.illyvoip.com/api/v1/dids/orders/quote",
    headers={
        "X-Api-Key": os.environ["ILLYVOIP_API_KEY"],
        'Content-Type': 'application/json'
    },
    json=json.loads("{\n    \"country_iso\": \"CA\",\n    \"region_code\": \"249\",\n    \"number_type\": \"local\",\n    \"product_reference\": \"YOUR_PRODUCT_REFERENCE\",\n    \"quantity\": 1\n}"),
)

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 body

application/json

Body required.

country_isostringoptional
region_codestringoptional
number_typestringoptional
product_referencestringrequired

Opaque product reference returned by number search.

quantityintegeroptional

Number of phone numbers, from 1 to 500.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "country_iso": {
      "type": "string"
    },
    "region_code": {
      "type": "string"
    },
    "number_type": {
      "type": "string"
    },
    "product_reference": {
      "type": "string",
      "description": "Opaque product reference returned by number search."
    },
    "quantity": {
      "type": "integer",
      "description": "Number of phone numbers, from 1 to 500."
    }
  },
  "required": [
    "product_reference"
  ]
}
Example body
JSON
{
  "country_iso": "CA",
  "region_code": "249",
  "number_type": "local",
  "product_reference": "YOUR_PRODUCT_REFERENCE",
  "quantity": 1
}

Request behavior

Send the opaque product_reference from number search. Use the returned public quote.fingerprint as pricing_fingerprint when creating the order. per_number.connection_fee is charged once per connected incoming call, separately from the per-minute usage rate. It is not included in totals.due_now or monthly rental. Version 2 quotes include this fee; display it before the customer confirms. Display data.kyc_eligibility.message before ordering. Only enable a new purchase when allowed is true. Eligibility uses the issuing country of the approved identity document, not nationality, residence, phone number or IP location. allowed_countries lists the permitted ISO2 countries for a restricted policy; Worldwide has no issuing-country restriction. Missing document evidence does not satisfy a restricted policy. An approved account exception is reported as mode: account_exception; it covers only issuing-country restrictions and still requires verified identity and other ordering requirements. A quote is not an eligibility reservation: requirements are checked again when accepting the purchase.

Response fields

  • status: Request outcome. Read the resource state separately; success does not always mean delivery or completion.
  • data: Endpoint-specific result object. Its nested fields are shown in the sample response.

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",
  "data": {
    "product_reference": "didpr_PUBLIC_PRODUCT_REFERENCE",
    "criteria": {
      "country_iso": "CA",
      "region_code": "249",
      "number_type": "local"
    },
    "quote": {
      "version": 2,
      "fingerprint": "didqt_PUBLIC_QUOTE_TOKEN",
      "pricing_date": "2026-08-24",
      "issued_at": "2026-08-24T10:00:00+00:00",
      "expires_at": "2026-08-24T10:10:00+00:00",
      "currency": "EUR",
      "quantity": 1,
      "per_number": {
        "setup": 1,
        "monthly": 1,
        "per_minute": 0.01,
        "connection_fee": 0,
        "prorated": 0.25,
        "second_month": 1
      },
      "totals": {
        "setup": 1,
        "prorated": 0.25,
        "second_month": 1,
        "due_now": 2.25
      },
      "proration": {
        "remaining_days": 7,
        "days_in_month": 31
      }
    }
  }
}
statusstringrequired
enum ["success"]
dataobjectrequired
View nested fields
product_referencestringrequired
criteriaobjectrequired
View nested fields
country_isostringrequired
region_codestringrequired
number_typestringrequired

Additional properties: not allowed.

kyc_eligibilityobjectoptional

Document issuing-country eligibility for this number. Display the message before ordering; the server checks again when accepting a new purchase.

nullable true
View nested fields
modestringoptional
enum ["worldwide", "region", "countries", "account_exception", "unavailable"]
regionstringoptional
nullable true
labelstringoptional
sourcestringoptional
enum ["document_issuing_country"]
allowed_countriesarray<string>optional
View nested fields

Array items

Type: string

Constraints
{
  "pattern": "^[A-Z]{2}$"
}
requirementstringoptional
allowedbooleanoptional
reasonstringoptional
messagestringoptional

Additional properties: not allowed.

quoteobjectrequired
View nested fields
versionintegerrequired
fingerprintstringrequired
pricing_datestringrequired
issued_atstringrequired
expires_atstringrequired
currencystringrequired
quantityintegerrequired
per_numberobjectrequired
View nested fields
setupintegerrequired
monthlyintegerrequired
per_minutenumberrequired
connection_feenumberrequired

Customer connection charge per incoming call in EUR, when available.

nullable true
proratednumberrequired
second_monthintegerrequired

Additional properties: not allowed.

totalsobjectrequired
View nested fields
setupintegerrequired
proratednumberrequired
second_monthintegerrequired
due_nownumberrequired

Additional properties: not allowed.

prorationobjectrequired
View nested fields
remaining_daysintegerrequired
days_in_monthintegerrequired

Additional properties: not allowed.

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"
      ]
    },
    "data": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "product_reference": {
          "type": "string"
        },
        "criteria": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "country_iso": {
              "type": "string"
            },
            "region_code": {
              "type": "string"
            },
            "number_type": {
              "type": "string"
            }
          },
          "required": [
            "country_iso",
            "region_code",
            "number_type"
          ]
        },
        "kyc_eligibility": {
          "type": "object",
          "nullable": true,
          "additionalProperties": false,
          "description": "Document issuing-country eligibility for this number. Display the message before ordering; the server checks again when accepting a new purchase.",
          "properties": {
            "mode": {
              "type": "string",
              "enum": [
                "worldwide",
                "region",
                "countries",
                "account_exception",
                "unavailable"
              ]
            },
            "region": {
              "type": "string",
              "nullable": true
            },
            "label": {
              "type": "string"
            },
            "source": {
              "type": "string",
              "enum": [
                "document_issuing_country"
              ]
            },
            "allowed_countries": {
              "type": "array",
              "items": {
                "type": "string",
                "pattern": "^[A-Z]{2}$"
              }
            },
            "requirement": {
              "type": "string"
            },
            "allowed": {
              "type": "boolean"
            },
            "reason": {
              "type": "string"
            },
            "message": {
              "type": "string"
            }
          }
        },
        "quote": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "version": {
              "type": "integer"
            },
            "fingerprint": {
              "type": "string"
            },
            "pricing_date": {
              "type": "string"
            },
            "issued_at": {
              "type": "string"
            },
            "expires_at": {
              "type": "string"
            },
            "currency": {
              "type": "string"
            },
            "quantity": {
              "type": "integer"
            },
            "per_number": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "setup": {
                  "type": "integer"
                },
                "monthly": {
                  "type": "integer"
                },
                "per_minute": {
                  "type": "number"
                },
                "connection_fee": {
                  "type": "number",
                  "nullable": true,
                  "description": "Customer connection charge per incoming call in EUR, when available."
                },
                "prorated": {
                  "type": "number"
                },
                "second_month": {
                  "type": "integer"
                }
              },
              "required": [
                "setup",
                "monthly",
                "per_minute",
                "connection_fee",
                "prorated",
                "second_month"
              ]
            },
            "totals": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "setup": {
                  "type": "integer"
                },
                "prorated": {
                  "type": "number"
                },
                "second_month": {
                  "type": "integer"
                },
                "due_now": {
                  "type": "number"
                }
              },
              "required": [
                "setup",
                "prorated",
                "second_month",
                "due_now"
              ]
            },
            "proration": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "remaining_days": {
                  "type": "integer"
                },
                "days_in_month": {
                  "type": "integer"
                }
              },
              "required": [
                "remaining_days",
                "days_in_month"
              ]
            }
          },
          "required": [
            "version",
            "fingerprint",
            "pricing_date",
            "issued_at",
            "expires_at",
            "currency",
            "quantity",
            "per_number",
            "totals",
            "proration"
          ]
        }
      },
      "required": [
        "product_reference",
        "criteria",
        "quote"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}
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."
    }
  }
}
404 The requested owned resource was not found.

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."
    }
  }
}
409 The request conflicts with the current resource or operation state.

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, unavailable

Try this operation in Sandbox · Environment setup and limitations

List DID countriesList DID regionsSearch DID numbersGet DID routing configSave DID routing configList DID ordersCreate DID orderCancel DID numberUpload DID documentsResubmit regulation

Search API operations, parameters, SDK and webhooks.