IllyVoIPdevelopers

Phone Numbers

Create DID order

Creates a new phone number order from live catalog inventory.

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

Before you start

Obtain a quote and use its pricing fingerprint with an Idempotency-Key.

Result

Store the returned order ID and follow its status and document requirements.

Charges and safe retries

This purchases a number and may charge your balance. Reuse the same key for the identical order retry.

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" \
  -H "X-Api-Key: ${ILLYVOIP_API_KEY:?Set ILLYVOIP_API_KEY}" \
  -H "Idempotency-Key: YOUR_UNIQUE_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country_iso": "CA",
    "region_code": "249",
    "number_type": "local",
    "product_reference": "YOUR_PRODUCT_REFERENCE",
    "pricing_fingerprint": "YOUR_QUOTE_FINGERPRINT",
    "quantity": 1
}'

Node.js

Node.js
const response = await fetch("https://api.illyvoip.com/api/v1/dids/orders", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.ILLYVOIP_API_KEY,
    "Idempotency-Key": "YOUR_UNIQUE_IDEMPOTENCY_KEY",
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "country_iso": "CA",
    "region_code": "249",
    "number_type": "local",
    "product_reference": "YOUR_PRODUCT_REFERENCE",
    "pricing_fingerprint": "YOUR_QUOTE_FINGERPRINT",
    "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');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('ILLYVOIP_API_KEY'),
        'Idempotency-Key: YOUR_UNIQUE_IDEMPOTENCY_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => '{
    "country_iso": "CA",
    "region_code": "249",
    "number_type": "local",
    "product_reference": "YOUR_PRODUCT_REFERENCE",
    "pricing_fingerprint": "YOUR_QUOTE_FINGERPRINT",
    "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",
    headers={
        "X-Api-Key": os.environ["ILLYVOIP_API_KEY"],
        "Idempotency-Key": "YOUR_UNIQUE_IDEMPOTENCY_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    \"pricing_fingerprint\": \"YOUR_QUOTE_FINGERPRINT\",\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 parameters

Header parameters

Idempotency-Keystringrequired

Unique retry key for this mutation. Reuse the same key only when retrying the same request.

minLength 8maxLength 128

Request body

application/json

Body required.

country_isostringrequired

Country ISO2 code.

region_codestringoptional
number_typestringoptional
product_referencestringrequired

Opaque product reference returned by the number search API.

pricing_fingerprintstringrequired

The quote fingerprint returned by the quote endpoint.

quantityintegeroptional

Defaults to 1; explicit quantities must be between 1 and 500.

browse_modebooleanoptional

Set true to buy exact returned numbers; omit or set false for quantity-based requests.

numbersarray<string>optional

Exact numbers returned by search when browse_mode is true. Use the same selection in the quote.

View nested fields

Array items

Type: string

documentsarray<object>optional

Required when indicated by the selected product. Each entry has name matching document_labels, MIME type, and base64 value.

View nested fields

Array items

Type: object

regulation_addressobjectoptional

When required: salutation (MR, MS or COMPANY), firstName/lastName or companyName, buildingNumber, streetName, zipCode, city and countryCodeA3 (valid ISO2 or ISO3 country code). Preserve local/national address requirements.

regulation_identityobjectoptional

When required: identityDocumentType, identityDocumentNumber and nationality (ISO2 or ISO3 country code). Include issuingAuthority and issuingDate if required. Never send a country name in place of its code.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "country_iso": {
      "type": "string",
      "description": "Country ISO2 code."
    },
    "region_code": {
      "type": "string"
    },
    "number_type": {
      "type": "string"
    },
    "product_reference": {
      "type": "string",
      "description": "Opaque product reference returned by the number search API."
    },
    "pricing_fingerprint": {
      "type": "string",
      "description": "The quote fingerprint returned by the quote endpoint."
    },
    "quantity": {
      "type": "integer",
      "description": "Defaults to 1; explicit quantities must be between 1 and 500."
    },
    "browse_mode": {
      "type": "boolean",
      "description": "Set true to buy exact returned numbers; omit or set false for quantity-based requests."
    },
    "numbers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Exact numbers returned by search when browse_mode is true. Use the same selection in the quote."
    },
    "documents": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      },
      "description": "Required when indicated by the selected product. Each entry has name matching document_labels, MIME type, and base64 value."
    },
    "regulation_address": {
      "type": "object",
      "additionalProperties": true,
      "description": "When required: salutation (MR, MS or COMPANY), firstName/lastName or companyName, buildingNumber, streetName, zipCode, city and countryCodeA3 (valid ISO2 or ISO3 country code). Preserve local/national address requirements."
    },
    "regulation_identity": {
      "type": "object",
      "additionalProperties": true,
      "description": "When required: identityDocumentType, identityDocumentNumber and nationality (ISO2 or ISO3 country code). Include issuingAuthority and issuingDate if required. Never send a country name in place of its code."
    }
  },
  "required": [
    "country_iso",
    "product_reference",
    "pricing_fingerprint"
  ]
}
Example body
JSON
{
  "country_iso": "CA",
  "region_code": "249",
  "number_type": "local",
  "product_reference": "YOUR_PRODUCT_REFERENCE",
  "pricing_fingerprint": "YOUR_QUOTE_FINGERPRINT",
  "quantity": 1
}

Request behavior

If the number requires regulation or KYC, the response indicates the next step. Duplicate-charge protection is enabled; the Playground generates its retry key automatically.

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.
  • meta: Additional documented result metadata; consult the example for this endpoint.

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",
    "order": {
      "order_id": 123,
      "order_ids": [
        123
      ],
      "order_reference": "CART-A1B2C3D4E5F6",
      "status": "pending",
      "number": "+12494251304",
      "numbers": [
        "+12494251304"
      ],
      "requested_quantity": 1,
      "quantity_fulfilled": 1,
      "created_at": "2026-08-24T10:00:00Z"
    },
    "payment": {
      "currency": "EUR",
      "quantity": 1,
      "per_number": {
        "setup": 1,
        "monthly": 1,
        "per_minute": 0.01,
        "connection_fee": 0,
        "prorated": 0.25
      },
      "totals": {
        "setup": 1,
        "prorated": 0.25,
        "second_month": 1,
        "due_now": 2.25
      }
    },
    "regulation": {
      "required": false,
      "documents_required": false,
      "address_required": false,
      "identity_required": false
    }
  },
  "meta": {
    "country_iso": "CA",
    "region_code": "249",
    "number_type": "local"
  }
}
statusstringrequired
enum ["success"]
dataobjectrequired
View nested fields
product_referencestringrequired
orderobjectrequired
View nested fields
order_idintegerrequired
order_idsarray<integer>required
View nested fields

Array items

Type: integer

order_referencestringrequired
statusstringrequired
numberstringrequired
numbersarray<string>required
View nested fields

Array items

Type: string

requested_quantityintegerrequired
quantity_fulfilledintegerrequired
created_atstringrequired

Additional properties: not allowed.

paymentobjectrequired
View nested fields
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

Additional properties: not allowed.

totalsobjectrequired
View nested fields
setupintegerrequired
proratednumberrequired
second_monthintegerrequired
due_nownumberrequired

Additional properties: not allowed.

Additional properties: not allowed.

regulationobjectrequired
View nested fields
requiredbooleanrequired
documents_requiredbooleanrequired
address_requiredbooleanrequired
identity_requiredbooleanrequired

Additional properties: not allowed.

Additional properties: not allowed.

metaobjectrequired
View nested fields
country_isostringrequired
region_codestringrequired
number_typestringrequired

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"
        },
        "order": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "order_id": {
              "type": "integer"
            },
            "order_ids": {
              "type": "array",
              "items": {
                "type": "integer"
              }
            },
            "order_reference": {
              "type": "string"
            },
            "status": {
              "type": "string"
            },
            "number": {
              "type": "string"
            },
            "numbers": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "requested_quantity": {
              "type": "integer"
            },
            "quantity_fulfilled": {
              "type": "integer"
            },
            "created_at": {
              "type": "string"
            }
          },
          "required": [
            "order_id",
            "order_ids",
            "order_reference",
            "status",
            "number",
            "numbers",
            "requested_quantity",
            "quantity_fulfilled",
            "created_at"
          ]
        },
        "payment": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "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"
                }
              },
              "required": [
                "setup",
                "monthly",
                "per_minute",
                "connection_fee",
                "prorated"
              ]
            },
            "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"
              ]
            }
          },
          "required": [
            "currency",
            "quantity",
            "per_number",
            "totals"
          ]
        },
        "regulation": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "required": {
              "type": "boolean"
            },
            "documents_required": {
              "type": "boolean"
            },
            "address_required": {
              "type": "boolean"
            },
            "identity_required": {
              "type": "boolean"
            }
          },
          "required": [
            "required",
            "documents_required",
            "address_required",
            "identity_required"
          ]
        }
      },
      "required": [
        "product_reference",
        "order",
        "payment",
        "regulation"
      ]
    },
    "meta": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "country_iso": {
          "type": "string"
        },
        "region_code": {
          "type": "string"
        },
        "number_type": {
          "type": "string"
        }
      },
      "required": [
        "country_iso",
        "region_code",
        "number_type"
      ]
    }
  },
  "required": [
    "status",
    "data",
    "meta"
  ]
}
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."
    }
  }
}
402 The account has insufficient available credit.

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, completed, pending-documents, rejected, quote-changed, insufficient-credit

Try this operation in Sandbox · Environment setup and limitations

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

Search API operations, parameters, SDK and webhooks.