Tutorial¶

Prerequisites¶

Before managing customers, you need:

An authentication token with admin permissions. Obtain one via POST /auth/login or use an access key from GET /accesskeys.
(For creation) A unique username and password for the new customer account.
(Optional) A webhook URI to receive event notifications for the customer.

Note

AI Implementation Hint

Customer creation requires admin-level permissions. Regular agents cannot create or delete customers. The password field is required when creating a customer but is write-only and never returned in API responses. When a customer is created, a guest agent with admin permissions is automatically created for that account.

Get list of customers¶

$ curl --location --request GET 'https://api.voipbin.net/v1.0/customers?token=<YOUR_AUTH_TOKEN>'

{
    "result": [
        {
            "id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
            "name": "Acme Corporation",
            "detail": "Enterprise customer account",
            "email": "admin@acme-corp.com",
            "phone_number": "+15551234567",
            "address": "123 Main St, San Francisco, CA 94105",
            "webhook_method": "POST",
            "webhook_uri": "https://webhooks.acme-corp.com/voipbin",
            "billing_account_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
            "metadata": {
                "rtp_debug": false
            },
            "email_verified": true,
            "status": "active",
            "identity_verification_status": "verified",
            "tm_deletion_scheduled": null,
            "tm_create": "2024-01-15T10:30:00Z",
            "tm_update": "2024-06-20T14:22:35Z",
            "tm_delete": null
        }
    ],
    "next_page_token": "2024-01-15T10:30:00Z"
}

Get detail of customer¶

Example

$ curl --location --request GET 'https://api.voipbin.net/v1.0/customers/5e4a0680-804e-11ec-8477-2fea5968d85b?token=<YOUR_AUTH_TOKEN>'

{
    "id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "name": "Acme Corporation",
    "detail": "Enterprise customer account",
    "email": "admin@acme-corp.com",
    "phone_number": "+15551234567",
    "address": "123 Main St, San Francisco, CA 94105",
    "webhook_method": "POST",
    "webhook_uri": "https://webhooks.acme-corp.com/voipbin",
    "billing_account_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "metadata": {
        "rtp_debug": false
    },
    "email_verified": true,
    "status": "active",
    "identity_verification_status": "verified",
    "tm_deletion_scheduled": null,
    "tm_create": "2024-01-15T10:30:00Z",
    "tm_update": "2024-06-20T14:22:35Z",
    "tm_delete": null
}

Create a new customer¶

Requires ProjectSuperAdmin permission. name, detail, email, phone_number, address, webhook_method, and webhook_uri are all required. There is no username/password field on this endpoint – agent credentials are created separately via the Agent API (a guest agent with admin permission is auto-created for the new customer).

Example

$ curl --location --request POST 'https://api.voipbin.net/v1.0/customers?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "name": "Test Company",
        "detail": "Test customer account",
        "email": "admin@test-company.com",
        "phone_number": "",
        "address": "",
        "webhook_method": "POST",
        "webhook_uri": "https://webhooks.test-company.com/voipbin"
    }'

{
    "id": "ff424526-f65d-483f-bc36-3b2357c6c6a9",
    "name": "Test Company",
    "detail": "Test customer account",
    "email": "admin@test-company.com",
    "phone_number": "",
    "address": "",
    "webhook_method": "POST",
    "webhook_uri": "https://webhooks.test-company.com/voipbin",
    "billing_account_id": "00000000-0000-0000-0000-000000000000",
    "metadata": {},
    "email_verified": false,
    "status": "initial",
    "identity_verification_status": "none",
    "tm_deletion_scheduled": null,
    "tm_create": "2024-03-10T15:57:08Z",
    "tm_update": "2024-03-10T15:57:08Z",
    "tm_delete": null
}

Delete customer¶

Note

AI Implementation Hint

Deleting a customer is a destructive operation that removes the customer account and all associated resources (agents, numbers, flows, etc.). This cannot be undone. The API returns the deleted customer object with tm_delete set to the deletion timestamp.

Example

$ curl --location --request DELETE 'https://api.voipbin.net/v1.0/customers/ff424526-f65d-483f-bc36-3b2357c6c6a9?token=<YOUR_AUTH_TOKEN>'

{
    "id": "ff424526-f65d-483f-bc36-3b2357c6c6a9",
    "name": "Test Company",
    "detail": "Test customer account",
    "email": "admin@test-company.com",
    "phone_number": "",
    "address": "",
    "webhook_method": "POST",
    "webhook_uri": "https://webhooks.test-company.com/voipbin",
    "billing_account_id": "00000000-0000-0000-0000-000000000000",
    "metadata": {},
    "email_verified": false,
    "status": "deleted",
    "identity_verification_status": "none",
    "tm_deletion_scheduled": null,
    "tm_create": "2024-03-10T15:57:08Z",
    "tm_update": "2024-03-10T15:57:08Z",
    "tm_delete": "2024-03-10T15:59:08Z"
}

Update customer metadata¶

Update configuration flags for your customer account, such as enabling RTP debug capture.

Note

AI Implementation Hint

The rtp_debug flag enables RTP packet capture for debugging audio quality issues. Only agents with CustomerAdmin permission can update metadata. Enabling this increases storage usage — disable after debugging.

To configure outbound codec preferences, use the POST /outbound_configs endpoint instead of customer metadata.

Example

$ curl --location --request PUT 'https://api.voipbin.net/v1.0/customer/metadata?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "rtp_debug": true
    }'

{
    "id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "name": "Acme Corporation",
    "detail": "Enterprise customer account",
    "email": "admin@acme-corp.com",
    "phone_number": "+15551234567",
    "address": "123 Main St, San Francisco, CA 94105",
    "webhook_method": "POST",
    "webhook_uri": "https://webhooks.acme-corp.com/voipbin",
    "billing_account_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "metadata": {
        "rtp_debug": true
    },
    "email_verified": true,
    "status": "active",
    "identity_verification_status": "verified",
    "tm_deletion_scheduled": null,
    "tm_create": "2024-01-15T10:30:00Z",
    "tm_update": "2024-06-20T14:22:35Z",
    "tm_delete": null
}

Update customer’s default billing account¶

Change the default billing account used for your customer account. Requires CustomerAdmin permission. The billing account must exist and be validated before the update is applied.

Example

$ curl --location --request PUT 'https://api.voipbin.net/v1.0/customer/billing_account_id?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "billing_account_id": "b8c9d0e1-f2a3-4567-8901-23456789abcd"
    }'

{
    "id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "name": "Acme Corporation",
    "detail": "Enterprise customer account",
    "email": "admin@acme-corp.com",
    "phone_number": "+15551234567",
    "address": "123 Main St, San Francisco, CA 94105",
    "webhook_method": "POST",
    "webhook_uri": "https://webhooks.acme-corp.com/voipbin",
    "billing_account_id": "b8c9d0e1-f2a3-4567-8901-23456789abcd",
    "metadata": {
        "rtp_debug": false
    },
    "email_verified": true,
    "status": "active",
    "identity_verification_status": "verified",
    "tm_deletion_scheduled": null,
    "tm_create": "2024-01-15T10:30:00Z",
    "tm_update": "2024-06-20T14:31:00Z",
    "tm_delete": null
}

Admin-only customer operations¶

The following endpoints require ProjectSuperAdmin permission and are intended for platform operators, not regular customer accounts. They act on any customer by id (obtained from GET /customers) and return the extended CustomerAdmin representation, which additionally includes terms_agreed_version and terms_agreed_ip (see Customer Struct).

Freeze a customer account (schedule deletion)

$ curl --location --request POST 'https://api.voipbin.net/v1.0/customers/5e4a0680-804e-11ec-8477-2fea5968d85b/freeze?token=<YOUR_ADMIN_TOKEN>'

{
    "id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "status": "frozen",
    "tm_deletion_scheduled": "2024-07-20T14:22:35Z",
    "...": "..."
}

Recover a frozen customer account

$ curl --location --request POST 'https://api.voipbin.net/v1.0/customers/5e4a0680-804e-11ec-8477-2fea5968d85b/recover?token=<YOUR_ADMIN_TOKEN>'

{
    "id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "status": "active",
    "tm_deletion_scheduled": null,
    "...": "..."
}

Update a customer’s billing account ID (admin)

$ curl --location --request PUT 'https://api.voipbin.net/v1.0/customers/5e4a0680-804e-11ec-8477-2fea5968d85b/billing_account_id?token=<YOUR_ADMIN_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "billing_account_id": "b8c9d0e1-f2a3-4567-8901-23456789abcd"
    }'

Update a customer’s internal metadata (admin)

$ curl --location --request PUT 'https://api.voipbin.net/v1.0/customers/5e4a0680-804e-11ec-8477-2fea5968d85b/metadata?token=<YOUR_ADMIN_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "rtp_debug": true
    }'

Note

AI Implementation Hint

Regular agents (even CustomerAdmin) receive 403 Permission Denied on all /customers (plural) endpoints. Only accounts with ProjectSuperAdmin permission may list, create, update, delete, freeze, recover, or manage another customer’s billing account or metadata this way. Regular customers use the singular /customer endpoints instead (GET /customer, PUT /customer, PUT /customer/metadata, PUT /customer/billing_account_id), and self-service deletion via POST /auth/unregister / DELETE /auth/unregister.

Unregister account (schedule deletion)¶

Request account deletion with a 30-day grace period. The account transitions to frozen status and a deletion date is scheduled.

Example

$ curl --location --request POST 'https://api.voipbin.net/auth/unregister' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <YOUR_AUTH_TOKEN>' \
    --data-raw '{
        "password": "yourPassword"
    }'

{
    "id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "name": "Acme Corporation",
    "detail": "Enterprise customer account",
    "email": "admin@acme-corp.com",
    "phone_number": "+15551234567",
    "address": "123 Main St, San Francisco, CA 94105",
    "webhook_method": "POST",
    "webhook_uri": "https://webhooks.acme-corp.com/voipbin",
    "billing_account_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "metadata": {
        "rtp_debug": false
    },
    "email_verified": true,
    "status": "frozen",
    "identity_verification_status": "verified",
    "tm_deletion_scheduled": "2024-07-20T14:22:35Z",
    "tm_create": "2024-01-15T10:30:00Z",
    "tm_update": "2024-06-20T14:22:35Z",
    "tm_delete": null
}

Unregister account immediately¶

Skip the 30-day grace period and permanently delete the account immediately. password and confirmation_phrase are mutually exclusive – provide exactly one: password for password-based accounts, or confirmation_phrase set to "DELETE" for SSO or API-key authenticated requests.

Example (SSO / API-key authenticated request)

$ curl --location --request POST 'https://api.voipbin.net/auth/unregister' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <YOUR_AUTH_TOKEN>' \
    --data-raw '{
        "confirmation_phrase": "DELETE",
        "immediate": true
    }'

{
    "id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "name": "",
    "detail": "",
    "email": "",
    "phone_number": "",
    "address": "",
    "webhook_method": "",
    "webhook_uri": "",
    "billing_account_id": "00000000-0000-0000-0000-000000000000",
    "metadata": {},
    "email_verified": false,
    "status": "deleted",
    "identity_verification_status": "none",
    "tm_deletion_scheduled": null,
    "tm_create": "2024-01-15T10:30:00Z",
    "tm_update": "2024-06-20T14:25:00Z",
    "tm_delete": "2024-06-20T14:25:00Z"
}

Note

AI Implementation Hint

Immediate deletion cannot be undone. All customer resources are cascade-deleted: agents, numbers, flows, queues, trunks, extensions, files, billing accounts, tags, transcriptions, and contacts. PII is anonymized – notice how name, detail, email, and other personal fields are empty in the response. The confirmation_phrase must be exactly "DELETE" (case-sensitive). Do not call this endpoint unless the user has explicitly confirmed permanent, irreversible deletion.

Cancel unregistration (recover account)¶

During the 30-day grace period, cancel the scheduled deletion and restore the account to active status.

Example

$ curl --location --request DELETE 'https://api.voipbin.net/auth/unregister' \
    --header 'Authorization: Bearer <YOUR_AUTH_TOKEN>'

{
    "id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "name": "Acme Corporation",
    "detail": "Enterprise customer account",
    "email": "admin@acme-corp.com",
    "phone_number": "+15551234567",
    "address": "123 Main St, San Francisco, CA 94105",
    "webhook_method": "POST",
    "webhook_uri": "https://webhooks.acme-corp.com/voipbin",
    "billing_account_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "metadata": {
        "rtp_debug": false
    },
    "email_verified": true,
    "status": "active",
    "identity_verification_status": "verified",
    "tm_deletion_scheduled": null,
    "tm_create": "2024-01-15T10:30:00Z",
    "tm_update": "2024-06-20T14:30:00Z",
    "tm_delete": null
}