Orders

Customer orders are the primary way to request virtual numbers in bulk for your applications. On this page, we'll dive into the different customer orders endpoints you can use to manage virtual number orders programmatically. We'll look at how to list, create, query, and update orders, and how to follow an order's fulfillment timeline.

All endpoints are scoped to your customer account via the {customer_slug} path segment and require authentication with an API key — sent as Authorization: Bearer xn_... (or alternatively in an X-API-Key header). API keys are created in the customer portal under Settings → API Keys.

The order model

The order model contains all the information about virtual number orders in your customer account, including quantities, status, and fulfillment details.

Properties

Name
order_id
Type
uuid
Description
Primary Key - Unique identifier for the order.
Name
order_number
Type
string
Description
Unique - Human-readable sequential order number (e.g., "#0042").
Name
number_type
Type
string
Description
Type of numbers requested (e.g., "mobile", "landline").
Name
country_code
Type
string
Description
ISO 3166-1 alpha-2 country code for the numbers (e.g., "US", "CA").
Name
quantity
Type
integer
Description
Total number of virtual numbers requested (1-10,000).
Name
status
Type
string
Description
Current order status: "pending", "processing", "fulfilled", "cancelled".
Name
fulfilled_quantity
Type
integer
Description
Number of virtual numbers successfully allocated (default: 0).
Name
notes
Type
string
Description
Optional notes or comments about the order (max 1,000 characters, nullable).
Name
requested_at
Type
timestamp
Description
Timestamp when the order was placed.
Name
fulfilled_at
Type
timestamp
Description
Timestamp when the order was completed (nullable).
Name
created_at
Type
timestamp
Description
Record creation timestamp.
Name
updated_at
Type
timestamp
Description
Last record update timestamp.

GET/customers/{customer_slug}/orders

List all orders

This endpoint allows you to retrieve a paginated list of all orders for your customer account with comprehensive filtering and sorting options. By default, a maximum of ten orders are shown per page. The response meta also includes status_counts — per-status totals across all your orders matching the current filters, ignoring the active status filter (useful for filter tabs).

Optional attributes

Name
page
Type
integer
Description
Page number for pagination (default: 1, min: 1).
Name
limit
Type
integer
Description
Number of orders per page (default: 10, min: 1, max: 100).
Name
search
Type
string
Description
Search string matched against order number and notes (1-50 characters).
Name
number_type
Type
string
Description
Filter by number type. Accepts a comma-separated list (e.g., "mobile,landline").
Name
country_code
Type
string
Description
Filter by country code. Accepts a comma-separated list of 2-uppercase-letter codes (e.g., "US,CA").
Name
status
Type
string
Description
Filter by order status. Accepts a comma-separated list (e.g., "pending,processing").
Name
quantity_min
Type
integer
Description
Only include orders with at least this quantity (min: 1).
Name
quantity_max
Type
integer
Description
Only include orders with at most this quantity (min: 1).
Name
requested_from
Type
string
Description
Only include orders requested on or after this ISO 8601 date (inclusive, start of day).
Name
requested_to
Type
string
Description
Only include orders requested on or before this ISO 8601 date (inclusive, end of day).
Name
fulfilled_from
Type
string
Description
Only include orders fulfilled on or after this ISO 8601 date (inclusive, start of day).
Name
fulfilled_to
Type
string
Description
Only include orders fulfilled on or before this ISO 8601 date (inclusive, end of day).
Name
sort_by
Type
string
Description
Sort field: "order_number", "number_type", "country_code", "quantity", "status", "requested_at", "fulfilled_at", "created_at" (default: "created_at").
Name
sort_order
Type
string
Description
Sort direction: "asc" or "desc" (default: "desc").

Request

GET

/orders

curl -G https://api.xnumbers.io/api/customers/acme/orders \
  -H "Authorization: Bearer xn_your_api_key" \
  -d page=1 \
  -d limit=10 \
  -d status=pending \
  -d country_code=US \
  -d sort_by=created_at \
  -d sort_order=desc

Response

{
  "data": [
    {
      "order_id": "12345678-1234-1234-1234-123456789abc",
      "order_number": "#0042",
      "number_type": "mobile",
      "country_code": "US",
      "quantity": 100,
      "status": "pending",
      "fulfilled_quantity": 0,
      "notes": "Urgent order for marketing campaign",
      "requested_at": "2026-06-01T15:30:00.000Z",
      "fulfilled_at": null,
      "created_at": "2026-06-01T15:30:00.000Z",
      "updated_at": "2026-06-01T15:30:00.000Z"
    }
  ],
  "meta": {
    "total": 250,
    "page": 1,
    "limit": 10,
    "totalPages": 25,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "status_counts": {
      "pending": 12,
      "processing": 3,
      "fulfilled": 230,
      "cancelled": 5
    }
  }
}

GET/customers/{customer_slug}/orders/{order_id}

Retrieve an order

This endpoint allows you to retrieve detailed information about a specific order using its unique identifier. A 404 Not Found is returned if the order does not exist or does not belong to your customer account.

Request

GET

/orders/0b571121-b6b1-4aaa-b22c-3408dcb23797

curl https://api.xnumbers.io/api/customers/acme/orders/0b571121-b6b1-4aaa-b22c-3408dcb23797 \
  -H "Authorization: Bearer xn_your_api_key"

Response

{
  "order_id": "0b571121-b6b1-4aaa-b22c-3408dcb23797",
  "order_number": "#0002",
  "number_type": "mobile",
  "country_code": "US",
  "quantity": 270,
  "status": "fulfilled",
  "fulfilled_quantity": 270,
  "notes": null,
  "requested_at": "2026-05-23T11:52:18.897Z",
  "fulfilled_at": "2026-05-23T11:55:20.898Z",
  "created_at": "2026-05-23T11:52:18.897Z",
  "updated_at": "2026-05-23T11:55:20.898Z"
}

POST/customers/{customer_slug}/orders

Create an order

This endpoint allows you to create a new virtual number order for your customer account. New orders start in "pending" status and are fulfilled by the xNumbers team. The country_code and number_type combination must be currently orderable; otherwise the request fails with a 400 Bad Request.

Required attributes

Name
number_type
Type
string
Description
Type of numbers to order (1-50 characters).
Name
country_code
Type
string
Description
ISO 3166-1 alpha-2 country code (exactly 2 uppercase letters).
Name
quantity
Type
integer
Description
Number of virtual numbers to request (1-10,000).

Optional attributes

Name
notes
Type
string
Description
Optional notes about the order (max 1,000 characters).

Request

POST

/orders

curl https://api.xnumbers.io/api/customers/acme/orders \
  -H "Authorization: Bearer xn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "number_type": "mobile",
    "country_code": "US",
    "quantity": 100,
    "notes": "Urgent order for marketing campaign"
  }'

Response

{
  "order_id": "12345678-1234-1234-1234-123456789abc",
  "order_number": "#0043",
  "number_type": "mobile",
  "country_code": "US",
  "quantity": 100,
  "status": "pending",
  "fulfilled_quantity": 0,
  "notes": "Urgent order for marketing campaign",
  "requested_at": "2026-06-01T15:30:00.000Z",
  "fulfilled_at": null,
  "created_at": "2026-06-01T15:30:00.000Z",
  "updated_at": "2026-06-01T15:30:00.000Z"
}

PUT/customers/{customer_slug}/orders/{order_id}

Update an order

This endpoint allows you to update an existing order. Orders can only be updated while they are in pending status. Once an order is processing, fulfilled, or cancelled, it cannot be modified.

Optional attributes

Name
number_type
Type
string
Description
Type of numbers to order (1-50 characters).
Name
country_code
Type
string
Description
ISO 3166-1 alpha-2 country code (exactly 2 uppercase letters).
Name
quantity
Type
integer
Description
Number of virtual numbers to request (1-10,000).
Name
notes
Type
string
Description
Optional notes about the order (max 1,000 characters).

Important Notes

order_id must be a valid UUID
Only orders with status "pending" can be updated; other statuses result in a 403 Forbidden error
All body fields are optional — only provide the fields you want to update

Request

PUT

/orders/0b571121-b6b1-4aaa-b22c-3408dcb23797

curl -X PUT https://api.xnumbers.io/api/customers/acme/orders/0b571121-b6b1-4aaa-b22c-3408dcb23797 \
  -H "Authorization: Bearer xn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 150,
    "notes": "Updated quantity for campaign"
  }'

Response

{
  "order_id": "0b571121-b6b1-4aaa-b22c-3408dcb23797",
  "order_number": "#0002",
  "number_type": "mobile",
  "country_code": "US",
  "quantity": 150,
  "status": "pending",
  "fulfilled_quantity": 0,
  "notes": "Updated quantity for campaign",
  "requested_at": "2026-05-23T11:52:18.897Z",
  "fulfilled_at": null,
  "created_at": "2026-05-23T11:52:18.897Z",
  "updated_at": "2026-05-23T12:30:45.123Z"
}