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 create, query, and retrieve order information.

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 order number (e.g., "ORD-2024-001234").
Name
number_type
Type
string
Description
Type of numbers requested (e.g., "mobile", "landline", "toll-free").
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", "partially_fulfilled", "fulfilled", "cancelled", "failed".
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).
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.

POST/customers/{customerSlug}/orders

Create an order

This endpoint allows you to create a new virtual number order for your customer account. Orders are processed asynchronously.

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/customers/acme-corp/orders \
  -H "Authorization: Bearer {token}" \
  -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": "ORD-2024-001234",
  "number_type": "mobile",
  "country_code": "US",
  "quantity": 100,
  "status": "pending",
  "fulfilled_quantity": 0,
  "notes": "Urgent order for marketing campaign",
  "requested_at": "2024-09-21T15:30:00.000Z",
  "fulfilled_at": null,
  "created_at": "2024-09-21T15:30:00.000Z",
  "updated_at": "2024-09-21T15:30:00.000Z"
}

GET/customers/{customerSlug}/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.

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
General search string (1-50 characters).
Name
number_type
Type
string
Description
Filter by number type (1-50 characters).
Name
country_code
Type
string
Description
Filter by country code (2 uppercase letters).
Name
status
Type
string
Description
Filter by order status (1-50 characters).
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/customers/acme-corp/orders \
  -H "Authorization: Bearer {token}" \
  -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": "ORD-2024-001234",
      "number_type": "mobile",
      "country_code": "US",
      "quantity": 100,
      "status": "pending",
      "fulfilled_quantity": 0,
      "notes": "Urgent order for marketing campaign",
      "requested_at": "2024-09-21T15:30:00.000Z",
      "fulfilled_at": null,
      "created_at": "2024-09-21T15:30:00.000Z",
      "updated_at": "2024-09-21T15:30:00.000Z"
    }
  ],
  "meta": {
    "total": 250,
    "page": 1,
    "limit": 10,
    "totalPages": 25,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

GET/customers/{customerSlug}/orders/{orderId}

Retrieve an order

This endpoint allows you to retrieve detailed information about a specific order using its unique identifier.

Request

GET

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

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

Response

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

PUT/customers/{customerSlug}/orders/{orderId}

Update an order

This endpoint allows you to update an existing order. Orders can only be updated when they are in pending status. Once an order is being processed, 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

Only orders with status "pending" can be updated
Attempting to update orders in other statuses will result in a 403 Forbidden error
All 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/customers/acme-corp/orders/0b571121-b6b1-4aaa-b22c-3408dcb23797 \
  -H "Authorization: Bearer {token}" \
  -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": "2025-09-23T11:52:18.897Z",
  "fulfilled_at": null,
  "created_at": "2025-09-23T11:52:18.897Z",
  "updated_at": "2025-09-23T12:30:45.123Z"
}

GET/customers/{customerSlug}/numbers?order_id={orderId}

Get fulfilled numbers

To retrieve all the phone numbers assigned to a specific order, use the List all numbers endpoint with the order_id query parameter. This will return only the numbers that were allocated during order fulfillment.

Query Parameters

Name
order_id
Type
uuid
Description
Required - The unique identifier of the order to get numbers for.

Use Cases

Get all phone numbers assigned to a completed order
Verify which numbers were allocated during fulfillment
Download or display assigned numbers to end users
Integrate fulfilled numbers into your application

Request

GET

/numbers?order_id=0b571121-b6b1-4aaa-b22c-3408dcb23797

curl -G https://api.xnumbers.io/customers/acme-corp/numbers \
  -H "Authorization: Bearer {token}" \
  -d order_id=0b571121-b6b1-4aaa-b22c-3408dcb23797

The response format is identical to the List all numbers endpoint, containing the complete number details and pagination metadata.