Overview
Bulk number orders (inexplicit orders) allow you to purchase phone numbers by specifying search criteria and quantity, without needing to identify and select specific phone numbers beforehand. The API automatically searches for available numbers matching your criteria, reserves them, and creates number orders on your account. This differs from the standard ordering workflow where you first search for available numbers, review the results, and then create orders for specific phone numbers. The bulk ordering process handles the search, reservation, and ordering steps automatically in a single API request. Orders are processed asynchronously, with processing time varying based on your search criteria, quantity requested, and current inventory availability.Constraints
- Bulk orders are only available for phone numbers in the US and CA.
- Maximum of 10,000 phone numbers per bulk order.
- The API will only order numbers that are available at the time of processing. Availability is not guaranteed and depends on current inventory levels. You can use the inventory coverage API to check inventory levels prior to ordering.
Ordering Groups
You can include multiple ordering groups in a single bulk order request. Each ordering group is processed independently and can have different search criteria and strategies. For example, you could create one bulk order that includes:- 5 local phone numbers in California, US with voice features.
- 3 toll-free phone numbers in US with SMS features.
- 10 local phone numbers in area code 212, New York, US.
count_requested, count_allocated, and status fields independently.
Order Statuses
Each ordering group within a bulk order has a status that indicates its current progress:| Status | Description |
|---|---|
| pending | The bulk order is queued and awaiting processing. |
| processing | The order is actively being processed. |
| success | The order was fully processed without errors. All requested phone numbers were ordered. |
| partial_success | The order was processed, but only partially completed. Some numbers could not be purchased due to insufficient inventory or errors encountered during number ordering. |
| failed | The order could not be processed successfully. |
How It Works
Step 1: Create a bulk order
Use the POST /v2/inexplicit_number_orders endpoint to create an order. Eachordering_group requires country_iso (US or CA), count_requested, and phone_number_type.
Optionally include search filters to narrow down results.
You can specify a strategy that controls behavior when inventory is insufficient: always (default) orders whatever quantity is available, while never only places the order if the full quantity can be fulfilled.
You can also configure connection_id, messaging_profile_id, billing_group_id, or customer_reference to automatically apply settings to all ordered phone numbers.
Step 2: Monitor order status
You can check the status of your bulk orders using the following endpoints:- GET /v2/inexplicit_number_orders: List all bulk orders with pagination support.
- GET /v2/inexplicit_number_orders/: Retrieve a specific bulk order by ID.
status field to track progress, and compare count_allocated to count_requested to see how many numbers were successfully ordered in each ordering group.
Step 3: Access the created number orders
When the bulk order completes processing, theorders array in the API response shows the number orders that were created to fulfill your request. Each entry includes:
- number_order_id: The ID of the parent number order.
- sub_number_order_ids: An array of sub number order IDs associated with the parent order.
- GET /v2/number_orders/: Retrieve the parent number order.
- GET /v2/sub_number_orders: List sub number orders.