Reserving and Provisioning Phone Numbers via API
This guide outlines how to use the Convirza API to search for, reserve, and provision phone numbers. Numbers are sourced from inventory or carriers, with inventory numbers having a number_id and carrier-available numbers having a null number_id.
Overview
This guide walks you through the process of identifying, reserving, and provisioning available phone numbers using the Convirza API.
Convirza provides numbers from two sources:
- Inventory Numbers (with number_id): Already available in your Convirza account and ready for immediate use.
- Carrier-Available Numbers (with number_id: null): Available at the carrier level, not yet in inventory, but can be reserved and then provisioned.
Step 1: Search for a Number
Use the GET /number/search endpoint to search for a number matching your desired criteria.
Response Example:
[
{
"number_id": null,
"number": "9482013920",
"source": 20002
},
{
"number_id": 12345,
"number": "9482013930",
"source": 10001
}
]
Interpretation:
- If number_id is present, the number is already in Convirza inventory.
- If number_id is null, the number is available from the carrier and can be reserved.
Step 2: Reserve Carrier-Available Numbers
If the number has number_id: null, you can reserve it using the POST /number/reserve endpoint.
Payload Example:
{
"number_id": null,
"number": "9482013920",
"source": 20002
}
After this step, the number is reserved and becomes part of your inventory.
Step 3: Provision the Reserved Number
After a successful reservation, provision the number using the POST /callflow endpoint.
Use the details returned in the reservation response:
"number": {
"phone_number_id": 67890,
"phone_number": "9482013920"
}
Important Note
You do not need to exclude results where number_id is null in your searches. These are valid numbers available from the carrier and can be fully utilized through the reserve + provision flow outlined above.
Summary
|
Scenario |
number_id |
Action Required |
|
Number already in inventory |
Not null |
Search & Directly provision |
|
Number available from carrier |
null |
Search, Reserve first, then provision |
If you need help at any step, feel free to reach out to our support team at support@convirza.com