Tutorial

Prerequisites

Before working with numbers, you need:

• An authentication token. Obtain one via POST /auth/login or use an access key from GET /accesskeys.

• (For provisioning) A valid number from the available inventory. Search available numbers via GET /available_numbers.

• (For flow assignment) A flow ID (UUID). Create one via POST /flows or obtain from GET /flows.

Note

AI Implementation Hint

All phone numbers must be in E.164 format: start with +, followed by country code and number, no dashes or spaces. For example, +15551234567 (US) or +821012345678 (Korea). Virtual numbers always use the +899 prefix (e.g., +899100000001).

Get list of available numbers

Example

$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/available_numbers?token=<YOUR_AUTH_TOKEN>&country_code=US&page_size=5'

{
"result": [
    {
        "number": "+12182558711",
        "country": "US",
        "region": "MN",
        "postal_code": "",
        "features": [
            "emergency",
            "fax",
            "voice",
            "sms",
            "mms"
        ]
    },
    ...
]
}

Get list of available virtual numbers

Example

$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/available_numbers?token=<YOUR_AUTH_TOKEN>&type=virtual&page_size=5'

{
"result": [
    {
        "number": "+899100000001",
        "country": "",
        "region": "",
        "postal_code": "",
        "features": []
    },
    ...
]
}

Create virtual number

Virtual numbers use the +899 prefix and do not require a provider purchase.

Example

$ curl -k --location --request POST 'https://api.voipbin.net/v1.0/numbers?token=<YOUR_AUTH_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "number": "+899100000001"
}'

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "number": "+899100000001",
    "type": "virtual",
    "call_flow_id": "00000000-0000-0000-0000-000000000000",
    "message_flow_id": "00000000-0000-0000-0000-000000000000",
    "name": "",
    "detail": "",
    "status": "active",
    "t38_enabled": false,
    "emergency_enabled": false,
    "tm_create": "2024-01-15 10:30:00.000000",
    "tm_update": "",
    "tm_delete": ""
}

Get list of numbers

Example

$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/numbers?token=<YOUR_AUTH_TOKEN>&page_size=10'

{
    "result": [
        {
            "id": "b7ee1086-fcbc-4f6f-96e5-7f9271e25279",
            "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
            "number": "+16062067563",
            "type": "normal",
            "call_flow_id": "00000000-0000-0000-0000-000000000000",
            "message_flow_id": "00000000-0000-0000-0000-000000000000",
            "name": "",
            "detail": "",
            "status": "active",
            "t38_enabled": true,
            "emergency_enabled": false,
            "metadata": {},
            "tm_purchase": "2021-03-03 06:34:09.000000",
            "tm_renew": "",
            "tm_create": "2021-03-03 06:34:09.733751",
            "tm_update": "",
            "tm_delete": ""
        },
        {
            "id": "d5532488-0b2d-11eb-b18c-172ab8f2d3d8",
            "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
            "number": "+16195734778",
            "type": "normal",
            "call_flow_id": "decc2634-0b2a-11eb-b38d-87a8f1051188",
            "message_flow_id": "00000000-0000-0000-0000-000000000000",
            "name": "",
            "detail": "",
            "status": "active",
            "t38_enabled": false,
            "emergency_enabled": false,
            "metadata": {},
            "tm_purchase": "",
            "tm_renew": "",
            "tm_create": "2020-10-11 01:00:00.000001",
            "tm_update": "",
            "tm_delete": ""
        }
    ],
    "next_page_token": "2020-10-11 01:00:00.000001"
}

Get detail of number

Example

$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/numbers/d5532488-0b2d-11eb-b18c-172ab8f2d3d8?token=<YOUR_AUTH_TOKEN>'

{
    "id": "d5532488-0b2d-11eb-b18c-172ab8f2d3d8",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "number": "+16195734778",
    "type": "normal",
    "call_flow_id": "decc2634-0b2a-11eb-b38d-87a8f1051188",
    "message_flow_id": "00000000-0000-0000-0000-000000000000",
    "name": "",
    "detail": "",
    "status": "active",
    "t38_enabled": false,
    "emergency_enabled": false,
    "metadata": {},
    "tm_purchase": "",
    "tm_renew": "",
    "tm_create": "2020-10-11 01:00:00.000001",
    "tm_update": "",
    "tm_delete": ""
}

Delete number

Example

$ curl -k --location --request DELETE 'https://api.voipbin.net/v1.0/numbers/b7ee1086-fcbc-4f6f-96e5-7f9271e25279?token=<YOUR_AUTH_TOKEN>'

{
    "id": "b7ee1086-fcbc-4f6f-96e5-7f9271e25279",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "number": "+16062067563",
    "type": "normal",
    "call_flow_id": "00000000-0000-0000-0000-000000000000",
    "message_flow_id": "00000000-0000-0000-0000-000000000000",
    "name": "",
    "detail": "",
    "status": "deleted",
    "t38_enabled": true,
    "emergency_enabled": false,
    "metadata": {},
    "tm_purchase": "2021-03-03 06:34:09.000000",
    "tm_renew": "",
    "tm_create": "2021-03-03 06:34:09.733751",
    "tm_update": "2021-03-03 06:52:53.848439",
    "tm_delete": "2021-03-03 06:52:53.848439"
}

Update number metadata

Update per-number configuration flags. Requires CustomerAdmin or CustomerManager permission.

Note

AI Implementation Hint

The rtp_debug flag enables RTP packet capture (PCAP) for incoming calls to this specific number. It is OR’d with the customer-level rtp_debug flag – if either is true, capture is enabled. Use this when you need to debug audio issues on a specific number without enabling capture for all customer calls. Disable after debugging to reduce storage usage.

Example

$ curl -k --location --request PUT 'https://api.voipbin.net/v1.0/numbers/d5532488-0b2d-11eb-b18c-172ab8f2d3d8/metadata?token=<YOUR_AUTH_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "rtp_debug": true
}'

{
    "id": "d5532488-0b2d-11eb-b18c-172ab8f2d3d8",
    "number": "+16195734778",
    "type": "normal",
    "call_flow_id": "decc2634-0b2a-11eb-b38d-87a8f1051188",
    "message_flow_id": "00000000-0000-0000-0000-000000000000",
    "name": "Support Line",
    "detail": "",
    "status": "active",
    "t38_enabled": false,
    "emergency_enabled": false,
    "metadata": {
        "rtp_debug": true
    },
    "tm_create": "2020-10-11 01:00:00.000001",
    "tm_update": "2026-03-12 10:30:00.000000",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Create number

Note

AI Implementation Hint

POST /numbers with a normal (non-virtual) number triggers a real provider purchase that costs money. For development and testing, use virtual numbers (+899 prefix) instead. Virtual numbers are free and do not require provider involvement.

Example

$ curl -k --location --request POST 'https://api.voipbin.net/v1.0/numbers?token=<YOUR_AUTH_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "number": "+16062067563"
}'

{
    "id": "b7ee1086-fcbc-4f6f-96e5-7f9271e25279",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "number": "+16062067563",
    "type": "normal",
    "call_flow_id": "00000000-0000-0000-0000-000000000000",
    "message_flow_id": "00000000-0000-0000-0000-000000000000",
    "name": "",
    "detail": "",
    "status": "active",
    "t38_enabled": true,
    "emergency_enabled": false,
    "metadata": {},
    "tm_purchase": "2021-03-03 18:41:23.000000",
    "tm_renew": "",
    "tm_create": "2021-03-03 18:41:24.657788",
    "tm_update": "",
    "tm_delete": ""
}