Inventory

Virtual numbers are the core asset in your telecommunications platform. On this page, we'll dive into the different inventory endpoints you can use to manage virtual numbers programmatically. We'll look at how to query, assign, update, return, and analyze your number inventory.

The number model

The number model contains all the information about virtual numbers in your inventory, including their assignment status, geographical details, capabilities, and user assignment information.

Properties

Name
number_id
Type
string
Description
Unique identifier for the virtual number.
Name
number
Type
string
Description
The actual phone number in E.164 format.
Name
number_type
Type
string
Description
Number type (e.g., "local", "toll-free", "mobile").
Name
country_code
Type
string
Description
ISO 3166-1 alpha-2 country code for the number.
Name
assigned_at
Type
timestamp
Description
Timestamp when the number was assigned to a user.
Name
capabilities
Type
array
Description
Array of supported features: ["voice", "sms", "mms", "fax"].
Name
returned_on
Type
timestamp
Description
Timestamp when the number was returned (if applicable).
Name
status
Type
string
Description
Assignment status: "Assign", "Unassign", or "Returned".
Name
created_at
Type
timestamp
Description
Timestamp when the number was created.
Name
updated_at
Type
timestamp
Description
Timestamp when the number was last updated.

GET/customers/{customerSlug}/numbers

List all numbers

This endpoint allows you to retrieve a paginated list of all virtual numbers assigned to the specified customer with optional filters. By default, a maximum of 10 numbers are shown per page.

Path parameters

Name
customerSlug
Type
string
Description
The unique slug identifier for the customer account.

Query parameters

Name
page
Type
integer
Description
Page number for pagination (default: 1, min: 1).
Name
limit
Type
integer
Description
Number of results per page (default: 10, min: 1, max: 100).
Name
search
Type
string
Description
Search term to filter numbers.
Name
number_type
Type
string
Description
Filter by number type.
Name
country_code
Type
string
Description
Filter by ISO country code (e.g., "US", "CA").
Name
status
Type
string
Description
Filter by assignment status.
Name
sort_by
Type
string
Description
Field to sort by. Options: 'number', 'number_type', 'country_code', 'status', 'assigned_at', 'created_at', 'updated_at' (default: 'created_at').
Name
sort_order
Type
string
Description
Sort direction. Options: 'asc', 'desc' (default: 'desc').

Request

GET

/customers/{customerSlug}/numbers

curl -G https://api.xnumbers.io/customers/acme-corp/numbers \
  -H "Authorization: Bearer {token}" \
  -d page=1 \
  -d limit=10 \
  -d country_code=US \
  -d number_type=local \
  -d search="555"

Response

{
  "data": [
    {
      "number_id": "550e8400-e29b-41d4-a716-446655440000",
      "number": "12125551234",
      "number_type": "local",
      "country_code": "US",
      "status": "active",
      "capabilities": ["voice", "sms"],
      "assigned_at": "2024-01-15T10:30:00.000Z",
      "returned_on": null,
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-15T14:30:00.000Z"
    },
    {
      "number_id": "550e8400-e29b-41d4-a716-446655440001",
      "number": "12125555678",
      "number_type": "toll-free",
      "country_code": "US",
      "status": "active",
      "capabilities": ["voice", "sms", "mms"],
      "assigned_at": "2024-01-10T08:15:00.000Z",
      "returned_on": null,
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-10T08:15:00.000Z"
    }
  ],
  "meta": {
    "total": 25,
    "page": 1,
    "limit": 10,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

GET/numbers/:id

Retrieve a number

This endpoint allows you to retrieve complete information about a single virtual number by providing its unique identifier.

Request

GET

/numbers/550e8400-e29b-41d4-a716-446655440000

curl https://api.xnumbers.io/v1/numbers/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer {token}"

Response

{
  "number_id": "550e8400-e29b-41d4-a716-446655440000",
  "number": "12125551234",
  "number_type": "local",
  "country_code": "US",
  "assigned_at": "1992-05-15T10:00:00Z",
  "capabilities": ["voice", "sms"],
  "returned_on": null,
  "status": "Assign",
  "hasIssue": false
}

PATCH/customers/{customerSlug}/numbers/{numberId}/status

Update number status

This endpoint allows customers to update the status of their assigned virtual numbers. Customers can only change status between "available" and "assigned" states.

Path parameters

Name
customerSlug
Type
string
Description
The unique slug identifier for the customer account.
Name
numberId
Type
uuid
Description
The unique identifier for the number to update.

Required attributes

Name
status
Type
string
Description
New assignment status. Must be either "available" or "assigned".

Request

PATCH

/customers/{customerSlug}/numbers/{numberId}/status

curl -X PATCH https://api.xnumbers.io/customers/acme-corp/numbers/550e8400-e29b-41d4-a716-446655440000/status \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "available"
  }'

Response

{
  "number_id": "550e8400-e29b-41d4-a716-446655440000",
  "number": "12125551234",
  "number_type": "local",
  "country_code": "US",
  "status": "available",
  "capabilities": ["voice", "sms"],
  "assigned_at": "2024-01-15T10:30:00.000Z",
  "returned_on": null,
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-24T16:45:00.000Z"
}

GET/customers/{customerSlug}/return-requests

List return requests

This endpoint allows you to retrieve a paginated list of all return requests for the specified customer, including their status, file information, and processing details.

Path parameters

Name
customerSlug
Type
string
Description
The unique slug identifier for the customer account.

Query parameters

Name
page
Type
integer
Description
Page number for pagination (default: 1, min: 1).
Name
limit
Type
integer
Description
Number of return requests per page (default: 10, min: 1).
Name
status
Type
string
Description
Filter by return request status. Options: 'pending', 'approved', 'rejected'.

Request

GET

/customers/{customerSlug}/return-requests

curl -G https://api.xnumbers.io/customers/acme-corp/return-requests \
  -H "Authorization: Bearer {token}" \
  -d page=1 \
  -d limit=10 \
  -d status=pending

Response

{
  "data": [
    {
      "request_id": "e650d145-bfc4-4f09-919f-af8927966ff1",
      "request_number": "#0001",
      "file_name": "return_numbers.csv",
      "status": "pending",
      "total_numbers_count": 100,
      "processed_numbers_count": 0,
      "notes": null,
      "requested_at": "2025-09-24T01:49:33.929Z",
      "approved_at": null,
      "processed_at": null,
      "created_at": "2025-09-24T01:49:33.929Z",
      "updated_at": "2025-09-24T01:49:33.929Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

POST/customers/{customerSlug}/return-requests/upload

Upload return request

This endpoint allows you to upload a CSV file containing phone numbers to create a return request. The CSV must contain phone numbers in a single column. The request will be pending and require admin approval.

Path parameters

Name
customerSlug
Type
string
Description
The unique slug identifier for the customer account.

Required attributes

Name
file
Type
file
Description
CSV file containing phone numbers to return (max 10MB).

Optional attributes

Name
notes
Type
string
Description
Optional notes about the return request.
Name
numberColumn
Type
string
Description
Column name containing phone numbers (if different from default).
Name
hasHeader
Type
boolean
Description
Whether the CSV file has a header row (default: auto-detect).

Request

POST

/customers/{customerSlug}/return-requests/upload

curl -X POST https://api.xnumbers.io/customers/acme-corp/return-requests/upload \
  -H "Authorization: Bearer {token}" \
  -F "file=@phone_numbers.csv" \
  -F "notes=End of service contract" \
  -F "hasHeader=true"

Response

{
  "request_id": "e650d145-bfc4-4f09-919f-af8927966ff1",
  "request_number": "#0001",
  "customer_id": "51d57d4f-90c3-4857-8d14-0c54f9a63af4",
  "customer_name": "xNumbers",
  "file_name": "return_numbers.csv",
  "status": "pending",
  "requested_by": "3d93e518-9c8d-4af1-84af-2e52d9567604",
  "requested_by_name": "admin Name",
  "approved_by": null,
  "approved_by_name": " ",
  "processed_numbers_count": 0,
  "total_numbers_count": 100,
  "notes": null,
  "requested_at": "2025-09-24T01:49:33.929Z",
  "approved_at": null,
  "processed_at": null,
  "created_at": "2025-09-24T01:49:33.929Z",
  "updated_at": "2025-09-24T01:49:33.929Z",
  "created_by": "3d93e518-9c8d-4af1-84af-2e52d9567604",
  "updated_by": null
}

GET/customers/{customerSlug}/return-requests/{id}

Get return request details

This endpoint allows you to retrieve detailed information about a specific return request, including its current status, processing progress, and approval information.

Path parameters

Name
customerSlug
Type
string
Description
The unique slug identifier for the customer account.
Name
id
Type
uuid
Description
The unique identifier for the return request.

Request

GET

/customers/{customerSlug}/return-requests/{id}

curl https://api.xnumbers.io/customers/acme-corp/return-requests/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer {token}"

Response

{
  "request_id": "e650d145-bfc4-4f09-919f-af8927966ff1",
  "request_number": "#0001",
  "file_name": "return_numbers.csv",
  "status": "pending",
  "total_numbers_count": 100,
  "processed_numbers_count": 0,
  "notes": null,
  "requested_at": "2025-09-24T01:49:33.929Z",
  "approved_at": null,
  "processed_at": null,
  "created_at": "2025-09-24T01:49:33.929Z",
  "updated_at": "2025-09-24T01:49:33.929Z"
}

GET/customers/{customerSlug}/return-requests/{id}/download

Download return request CSV

This endpoint allows you to download the original CSV file that was uploaded for a specific return request.

Path parameters

Name
customerSlug
Type
string
Description
The unique slug identifier for the customer account.
Name
id
Type
uuid
Description
The unique identifier for the return request.

Request

GET

/customers/{customerSlug}/return-requests/{id}/download

curl https://api.xnumbers.io/customers/acme-corp/return-requests/550e8400-e29b-41d4-a716-446655440000/download \
  -H "Authorization: Bearer {token}" \
  -o phone_numbers.csv

Returns the CSV file as a download with appropriate headers:

Content-Type: text/csv
Content-Disposition: attachment; filename="phone_numbers.csv"

GET/customers/{customerSlug}/numbers/stats

Get customer number statistics

This endpoint returns statistical data about the customer's number inventory, providing counts by status with optional filtering by number type and country code. Useful for reporting and inventory management.

Path parameters

Name
customerSlug
Type
string
Description
The unique slug identifier for the customer account.

Query parameters

Name
number_type
Type
string
Description
Filter by number type. Options: 'local', 'toll_free', 'international', 'mobile', 'premium'.
Name
country_code
Type
string
Description
Filter by country code (2-letter ISO format, e.g., 'US').

Request

GET

/customers/{customerSlug}/numbers/stats

curl -G https://api.xnumbers.io/customers/acme-corp/numbers/stats \
  -H "Authorization: Bearer {token}" \
  -d number_type=local \
  -d country_code=US

Response

{
  "total_numbers": 1247,
  "breakdown": {
    "available": 847,
    "assigned": 312,
    "reserved": 73,
    "quarantined": 15
  },
  "generated_at": "2024-01-01T10:00:00.000Z"
}