Customer

A customer represents an account on the VoIPBIN platform, containing billing details, permissions, and configuration for all owned resources.

API Reference: Customer endpoints

Overview

Note

AI Context

Complexity: Low
Cost: Free (customer management operations incur no charges)
Async: No. All customer operations are synchronous and return immediately.

VoIPBIN’s Customer API provides account-level management for your organization within the platform. A customer represents a tenant account that owns resources like agents, numbers, flows, and billing. The Customer API enables you to manage account settings, view usage, and configure organization-wide preferences.

With the Customer API you can:

View and update customer account information
Manage account-level settings and preferences
Monitor resource usage and limits
Configure default behaviors for the account
Access account metadata and timestamps

How Customers Work

A customer is the top-level organizational unit in VoIPBIN that owns all other resources.

Customer Architecture

+-----------------------------------------------------------------------+
|                         Customer Account                              |
+-----------------------------------------------------------------------+

+-------------------+
|     Customer      |
|  (organization)   |
+--------+----------+
         |
         | owns
         v
+--------+----------+--------+----------+--------+----------+
|                   |                   |                   |
v                   v                   v                   v
+----------+   +----------+   +----------+   +----------+
|  Agents  |   | Numbers  |   |  Flows   |   | Billing  |
+----------+   +----------+   +----------+   +----------+
     |              |              |              |
     v              v              v              v
+---------+    +---------+    +---------+    +---------+
| Users   |    | Phone   |    | Call    |    | Account |
| Skills  |    | Lines   |    | Logic   |    | Balance |
+---------+    +---------+    +---------+    +---------+

Key Components

Customer: The tenant account that owns all resources
Agents: Users who handle calls and messages
Numbers: Phone numbers provisioned for the account
Flows: Call and message handling logic
Billing: Account balance and payment information

Customer Properties

Key properties of a customer account.

Core Properties

Property	Description
id	(UUID) Unique identifier for the customer account
name	(String) Display name of the organization
detail	(String) Additional description or notes
email	(String) Email address associated with the account
phone_number	(String) Phone number associated with the account
address	(String) Physical or mailing address
webhook_method	(enum string) HTTP method for webhooks: POST, GET, PUT, DELETE
webhook_uri	(String) URI for webhook event notifications
billing_account_id	(UUID) Default billing account. From `GET /billing_accounts`
email_verified	(Boolean) Whether the email address has been verified
status	(enum string) Account status: initial, active, frozen, deleted, expired

Timestamps

Property	Description
tm_deletion_scheduled	(ISO 8601, nullable) When permanent deletion is scheduled
tm_create	(ISO 8601) When the account was created
tm_update	(ISO 8601) When the account was last modified
tm_delete	(ISO 8601, nullable) When the account was deleted

Managing Customers

Access and update customer account information.

Get Customer Information

$ curl -X GET 'https://api.voipbin.net/v1.0/customer?token=<token>'

Response:

{
    "id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "name": "Acme Corporation",
    "detail": "Enterprise customer account",
    "email": "[email protected]",
    "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",
    "email_verified": true,
    "status": "active",
    "tm_deletion_scheduled": null,
    "tm_create": "2024-01-01T00:00:00Z",
    "tm_update": "2024-01-15T10:30:00Z",
    "tm_delete": null
}

Update Customer Information

$ curl -X PUT 'https://api.voipbin.net/v1.0/customer?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "name": "Acme Corporation Inc.",
        "detail": "Updated enterprise account"
    }'

Account Deletion Lifecycle

Customer accounts follow a defined status lifecycle that governs account creation, verification, and deletion.

Status Lifecycle

Signup              Email Verified         Unregister          Grace Period
+----------+       +----------+           +----------+       +----------+
| initial  | ----> |  active  | --------> |  frozen  | ----> | deleted  |
+----------+       +----------+           +----------+       +----------+
     |                                         |
     | (no verification                        | (cancel unregister)
     |  within timeout)                        |
     v                                         v
+----------+                              +----------+
| expired  |                              |  active  |
+----------+                              +----------+

Status Values

Self-Service Unregistration

A customer can request account deletion via the unregister endpoint. This freezes the account and schedules permanent deletion after a 30-day grace period.

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

When an account is frozen:

Active calls and operations are terminated
New resource creation and operations are blocked
The tm_deletion_scheduled field is set to the scheduled deletion date
The status changes to frozen

Immediate Deletion

To skip the 30-day grace period and delete the account immediately, include "immediate": true and a confirmation phrase.

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

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. Do not call this endpoint unless the user has explicitly confirmed they want permanent, irreversible deletion.

Cancel Unregistration (Recover Account)

During the 30-day grace period, a frozen account can be recovered by cancelling the unregistration.

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

This restores the account to active status, clears the tm_deletion_scheduled field, and re-enables all operations.

What Happens on Permanent Deletion

When the grace period expires (or immediate deletion is requested), the following resources are cascade-deleted:

Agents
Numbers
Flows
Queues
Trunks
Extensions
Files
Billing accounts
Tags
Transcriptions
Contacts

All personally identifiable information (PII) is anonymized and the account status transitions to deleted.

Resource Ownership

All resources in VoIPBIN are scoped to a customer.

Resource Hierarchy

Customer: "Acme Corp"
+-----------------------------------------------------------------------+
|                                                                       |
|  Agents (10)                                                          |
|  +-- John Smith (agent-001)                                          |
|  +-- Jane Doe (agent-002)                                            |
|  +-- ... (8 more)                                                    |
|                                                                       |
|  Numbers (5)                                                          |
|  +-- +15551234567 (main line)                                        |
|  +-- +15559876543 (support)                                          |
|  +-- ... (3 more)                                                    |
|                                                                       |
|  Flows (8)                                                            |
|  +-- IVR Main Menu                                                   |
|  +-- Support Queue Router                                            |
|  +-- ... (6 more)                                                    |
|                                                                       |
|  Queues (3)                                                           |
|  +-- Sales Queue                                                     |
|  +-- Support Queue                                                   |
|  +-- Billing Queue                                                   |
|                                                                       |
+-----------------------------------------------------------------------+

Resource Isolation

+-------------------+        +-------------------+
|   Customer A      |        |   Customer B      |
+-------------------+        +-------------------+
| Agents: A1, A2    |        | Agents: B1, B2    |
| Numbers: +1555... |        | Numbers: +1666... |
| Flows: Flow-A     |        | Flows: Flow-B     |
+-------------------+        +-------------------+
       |                            |
       |  ISOLATED                  |
       |  (cannot access            |
       |   each other's resources)  |
       +----------------------------+

Guest Agent

Every customer account automatically has a guest agent created for administrative access.

Customer Created
       |
       v
+-------------------+
| Auto-create       |
| Guest Agent       |
+--------+----------+
         |
         v
+-------------------+
| Properties:       |
| o Admin permission|
| o Cannot delete   |
| o Cannot change   |
|   password        |
+-------------------+

The guest agent ensures every account has at least one administrator for recovery purposes.

Note

AI Implementation Hint

The customer id is the top-level scoping identifier for all resources in VoIPBIN. When creating agents, numbers, flows, or any other resource, they are automatically associated with the customer of the authenticated user. You do not need to pass customer_id explicitly in most creation requests – it is derived from the authentication token.

Common Scenarios

Scenario 1: Account Setup

Initial configuration of a new customer account.

1. Customer account created
   +--------------------------------------------+
   | Customer: "New Company LLC"               |
   | Status: active                            |
   | Guest agent: auto-created                 |
   +--------------------------------------------+

2. Create additional agents
   POST /agents { "username": "admin@..." }

3. Provision numbers
   POST /numbers { "number": "+1555..." }

4. Create flows
   POST /flows { "name": "Main IVR" }

5. Configure resources
   Link numbers to flows, agents to queues

Scenario 2: Multi-Department Setup

Organize resources by department.

Customer: "Enterprise Corp"
+--------------------------------------------+
|                                            |
| Sales Department:                          |
| - Agents: sales-1, sales-2, sales-3       |
| - Queue: Sales Queue (tags: sales)        |
| - Number: +18005551111                    |
|                                            |
| Support Department:                        |
| - Agents: support-1, support-2            |
| - Queue: Support Queue (tags: support)    |
| - Number: +18005552222                    |
|                                            |
| Billing Department:                        |
| - Agents: billing-1                       |
| - Queue: Billing Queue (tags: billing)    |
| - Number: +18005553333                    |
|                                            |
+--------------------------------------------+

Scenario 3: Account Review

Periodic review of account resources.

Review Checklist:
+--------------------------------------------+
| 1. Check active agents                     |
|    GET /agents -> count, statuses          |
|                                            |
| 2. Review provisioned numbers              |
|    GET /numbers -> count, usage            |
|                                            |
| 3. Audit flows                             |
|    GET /flows -> active, last updated      |
|                                            |
| 4. Check billing status                    |
|    GET /billing_accounts -> balance        |
+--------------------------------------------+

Best Practices

1. Account Organization

Use descriptive customer names
Document account purpose in detail field
Keep resource naming consistent

2. Security

Limit admin permissions to necessary agents
Regularly audit agent access
Use strong passwords for all agents

3. Resource Management

Clean up unused numbers and flows
Monitor agent activity
Archive inactive resources

4. Monitoring

Track account usage metrics
Set up alerts for unusual activity
Review billing regularly

Troubleshooting

Access Issues

Symptom	Solution
Cannot access customer data	Verify API token is valid; check agent has admin permission
Resources not visible	Ensure accessing correct customer ID; verify resource exists

Account Issues

Customer

{
    "id": "<string>",
    "name": "<string>",
    "detail": "<string>",
    "email": "<string>",
    "phone_number": "<string>",
    "address": "<string>",
    "webhook_method": "<string>",
    "webhook_uri": "<string>",
    "billing_account_id": "<string>",
    "email_verified": <boolean>,
    "status": "<string>",
    "tm_deletion_scheduled": "<string>",
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}

id (UUID): The customer’s unique identifier. Returned when retrieving the customer via GET https://api.voipbin.net/v1.0/customer.
name (String, Optional): The display name of the customer organization.
detail (String, Optional): An optional description or notes about the customer account.
email (String, Optional): The email address associated with the customer account.
phone_number (String, Optional): The phone number associated with the customer account.
address (String, Optional): The physical or mailing address of the customer.
webhook_method (enum string, Optional): The HTTP method used for webhook notifications. One of: POST, GET, PUT, DELETE.
webhook_uri (String, Optional): The URI where webhook event notifications are sent for this customer.
billing_account_id (UUID, Optional): The default billing account ID for this customer. Obtained from GET https://api.voipbin.net/v1.0/billing_accounts.
email_verified (Boolean): Whether the customer’s email address has been verified. true if verified, false otherwise.
status (enum string): The current account status. One of:
- initial: Account created, pending email verification.
- active: Normal operation, fully verified.
- frozen: Deletion scheduled, 30-day grace period (or immediate deletion in progress).
- deleted: Permanently deleted, PII anonymized.
- expired: Unverified signup expired.
tm_deletion_scheduled (String, ISO 8601, nullable): Timestamp when the account is scheduled for permanent deletion. Set when the account transitions to frozen status. null if no deletion is scheduled.
tm_create (String, ISO 8601): Timestamp when the customer was created.
tm_update (String, ISO 8601): Timestamp when the customer was last updated.
tm_delete (String, ISO 8601, nullable): Timestamp when the customer was deleted. null if the customer has not been deleted.

Note

AI Implementation Hint

The status field determines what operations are allowed on the account. Only active accounts can create resources and make calls. A frozen account has deletion scheduled but can be recovered by cancelling unregistration before the grace period expires. A deleted account cannot be recovered – all PII has been anonymized and all resources cascade-deleted. The tm_deletion_scheduled field is only set when status is frozen.

Example

{
    "id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "name": "Acme Corporation",
    "detail": "Enterprise customer account",
    "email": "[email protected]",
    "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",
    "email_verified": true,
    "status": "active",
    "tm_deletion_scheduled": null,
    "tm_create": "2024-01-15T10:30:00Z",
    "tm_update": "2024-06-20T14:22:35Z",
    "tm_delete": null
}

Tutorial

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": "[email protected]",
            "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",
            "email_verified": true,
            "status": "active",
            "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": "[email protected]",
    "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",
    "email_verified": true,
    "status": "active",
    "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

Example

$ curl --location --request POST 'https://api.voipbin.net/v1.0/customers?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "username": "test1",
        "password": "ee5f3d14-5ac6-11ed-808e-6f7d676a444b",
        "name": "Test Company",
        "detail": "Test customer account",
        "email": "[email protected]",
        "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": "[email protected]",
    "phone_number": "",
    "address": "",
    "webhook_method": "POST",
    "webhook_uri": "https://webhooks.test-company.com/voipbin",
    "billing_account_id": "00000000-0000-0000-0000-000000000000",
    "email_verified": false,
    "status": "initial",
    "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": "[email protected]",
    "phone_number": "",
    "address": "",
    "webhook_method": "POST",
    "webhook_uri": "https://webhooks.test-company.com/voipbin",
    "billing_account_id": "00000000-0000-0000-0000-000000000000",
    "email_verified": false,
    "status": "deleted",
    "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"
}

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": "[email protected]",
    "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",
    "email_verified": true,
    "status": "frozen",
    "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. Requires a confirmation phrase and password.

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",
        "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",
    "email_verified": false,
    "status": "deleted",
    "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": "[email protected]",
    "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",
    "email_verified": true,
    "status": "active",
    "tm_deletion_scheduled": null,
    "tm_create": "2024-01-15T10:30:00Z",
    "tm_update": "2024-06-20T14:30:00Z",
    "tm_delete": null
}

Customer

Overview

How Customers Work

Customer Properties

Managing Customers

Account Deletion Lifecycle

Resource Ownership

Guest Agent

Common Scenarios

Best Practices

Troubleshooting

Related Documentation

Customer

Customer

Example

Tutorial

Get list of customers

Get detail of customer

Create a new customer

Delete customer

Unregister account (schedule deletion)

Unregister account immediately

Cancel unregistration (recover account)