Overview

Note

AI Context

• Complexity: Low – These are shared data structures and conventions used across all VoIPBIN APIs. No API calls are specific to this section.

• Cost: Free. Common structures are reference documentation only; no operations are performed.

• Async: N/A. This section documents conventions, not API endpoints.

This section covers common data structures, patterns, and concepts used throughout the VoIPBIN API. Understanding these foundational elements will help you work more effectively with all VoIPBIN resources.

Note

AI Implementation Hint

All VoIPBIN timestamps use the format YYYY-MM-DD HH:MM:SS.microseconds in UTC. A tm_delete value of 9999-01-01 00:00:00.000000 means the resource has not been deleted (sentinel value). When filtering by time ranges, use URL-encoded timestamps as query parameters (e.g., ?page_token=2022-06-17%2006%3A06%3A14.948432).

Common Data Structures

Address Structure

The Address structure is used throughout VoIPBIN to represent communication endpoints, including phone numbers, SIP addresses, and extension numbers. See the detailed structure documentation at here.

Timestamp Format

All timestamps in VoIPBIN follow the format YYYY-MM-DD HH:MM:SS.microseconds and are in UTC timezone unless otherwise specified.

Example: 2022-05-01 15:10:38.785510878

UUID Format

VoIPBIN uses UUIDs (Universally Unique Identifiers) to identify resources. All resource IDs follow the standard UUID v4 format.

Example: d9d32881-12fd-4b19-a6b2-6d5b6b6acf76

Empty UUID

The empty UUID 00000000-0000-0000-0000-000000000000 is used to represent null or unset references.

Common Patterns

Pagination

List endpoints support pagination using the next_page_token parameter. When a response includes a next_page_token field, pass this value in your next request to retrieve the next page of results.

Response format:

{
    "result": [
        { ... },
        { ... }
    ],
    "next_page_token": "2022-06-17 06:06:14.948432"
}

Fetching the next page:

GET https://api.voipbin.net/v1.0/calls?page_token=2022-06-17%2006%3A06%3A14.948432

When next_page_token is empty or not present, you have reached the last page.

Filtering and Searching

Many list endpoints support filtering and searching through query parameters. Common filter parameters include:

• status: Filter by resource status

• customer_id: Filter by customer

• tm_create: Filter by creation time range

Check the specific endpoint documentation for available filter options.

Soft Deletion

VoIPBIN uses soft deletion for most resources. Deleted resources have their tm_delete timestamp set to the deletion time. Non-deleted resources have tm_delete set to 9999-01-01 00:00:00.000000.

Non-deleted resource:

"tm_delete": "9999-01-01 00:00:00.000000"

Deleted resource:

"tm_delete": "2024-03-15 10:30:00.000000"

HTTP Status Codes

VoIPBIN API uses standard HTTP status codes to indicate success or failure.

Success Codes

Code	Description
200 OK	Request succeeded. Response contains requested data.
201 Created	Resource created successfully.
204 No Content	Request succeeded with no response body (e.g., DELETE).

Client Error Codes

Code	Description
400 Bad Request	Invalid request format or parameters.
401 Unauthorized	Missing or invalid authentication token.
403 Forbidden	Valid token but insufficient permissions.
404 Not Found	Resource does not exist.
409 Conflict	Resource state conflict (e.g., duplicate creation).
422 Unprocessable Entity	Valid format but semantic errors.
429 Too Many Requests	Rate limit exceeded. Retry after delay.

Server Error Codes

Code	Description
500 Internal Server Error	Unexpected server error.
502 Bad Gateway	Upstream service unavailable.
503 Service Unavailable	Service temporarily unavailable.

Error Responses

All 4xx and 5xx responses share a single canonical envelope shape. See Error Response Envelope in the RESTful API page for the field definitions, status-to-HTTP mapping, and AI implementation hints.

The reason-code catalog grouped by originating manager is at Error Reason Codes.

Request/Response Formats

All API requests and responses use JSON format.

Request headers:

Content-Type: application/json
Authorization: Bearer <YOUR_ACCESS_TOKEN>

Note

AI Implementation Hint

Besides the Authorization: Bearer <token> header, VoIPBIN also accepts the token as a token query parameter (e.g., ?token=<token>, used throughout this documentation for curl examples and required for the WebSocket endpoint since it cannot send custom headers) or as a token cookie.

Single resource response:

{
    "id": "d9d32881-12fd-4b19-a6b2-6d5b6b6acf76",
    "name": "Example Resource",
    "status": "active",
    "tm_create": "2022-05-01 15:10:38.785510",
    "tm_update": "2022-05-01 15:10:38.785510",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

List response:

{
    "result": [
        { ... },
        { ... }
    ],
    "next_page_token": "..."
}

Rate Limiting

VoIPBIN applies two independent layers of rate limiting to API requests:

• A per-client-IP limit (in-memory, per server instance), enforced in three tiers:

  • Unauthenticated /auth/* endpoints (signup, login/boot, password reset, etc. — see Auth for the full list): up to approximately 10 requests/second, burst of 20.

  • Authenticated account-management endpoints (/auth/unregister, /auth/delegate): up to approximately 10 requests/second, burst of 20.

  • The rest of the authenticated /v1.0/* API surface (calls, messages, and the rest of the platform API): up to approximately 200 requests/second, burst of 400.

• A per-customer global quota (Redis-backed, shared state across all server instances — not just an order-of-magnitude guide but an actual hard ceiling), enforced only on the authenticated /v1.0/* surface after your credentials are validated:

  • Agent and accesskey credentials for the same customer share one bucket: approximately 16.7 requests/second, burst of 33.

  • Direct (resource-scoped) tokens: approximately 50 requests/second, burst of 100.

  • Delegate tokens: approximately 8.3 requests/second, burst of 16.

The per-IP figures are per-server-instance, not an exact guaranteed ceiling — the effective limit for a given client can vary with backend scaling, so treat them as an order-of-magnitude guide. The per-customer figures, by contrast, are enforced against shared state and hold as a true global ceiling for your account regardless of which server instance handles the request. When either limit is exceeded, the API returns a 429 Too Many Requests response using the same canonical error envelope described in Error Response Envelope, with reason code RATE_LIMIT_EXCEEDED, a Retry-After header (seconds to wait before retrying), and error.details[0].limited_by set to "ip" or "customer" depending on which layer rejected the request.

{
    "error": {
        "status": "RESOURCE_EXHAUSTED",
        "reason": "RATE_LIMIT_EXCEEDED",
        "message": "Too many requests. Please try again later.",
        "details": [
            { "limited_by": "customer" }
        ]
    }
}

Note

AI Implementation Hint

The rate limit response includes a Retry-After: <seconds> header on every 429. Prefer waiting the exact number of seconds it specifies over blind exponential backoff, and fall back to exponential backoff only if the header is unexpectedly absent.

Handling rate limits:

1. Detect the 429 status code and RATE_LIMIT_EXCEEDED reason

2. Read the Retry-After header and wait that many seconds before retrying (fall back to exponential backoff if the header is missing)

3. Inspect error.details[0].limited_by to distinguish an IP-level limit from a customer-level (account-wide) limit

4. Cache responses when possible to reduce API calls