Common

Shared data structures and conventions used across multiple VoIPBIN API resources, including address formats, pagination parameters, and standard response envelopes.

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 /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

Client Error Codes

Server Error Codes

Error Response Format

When an error occurs, the API returns a JSON response with error details:

{
    "error": {
        "code": "invalid_parameter",
        "message": "The 'destination' field is required",
        "field": "destination"
    }
}

Error fields:

• code: Machine-readable error code

• message: Human-readable error description

• field: (Optional) Field that caused the error

Common Error Codes

Code	Description
invalid_parameter	Request parameter is invalid or missing.
resource_not_found	Requested resource does not exist.
permission_denied	Insufficient permissions for this operation.
duplicate_resource	Resource with same identifier already exists.
invalid_state	Operation not allowed in current resource state.
rate_limit_exceeded	Too many requests. Wait before retrying.

Request/Response Formats

All API requests and responses use JSON format.

Request headers:

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

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 rate limits to protect service stability. When you exceed the rate limit, the API returns a 429 Too Many Requests response.

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1609459200

Handling rate limits:

1. Check the Retry-After header for when to retry

2. Implement exponential backoff for retries

3. Cache responses when possible to reduce API calls

Address

Address

Defines source/destination address. This structure is used throughout VoIPBIN wherever communication endpoints are specified, including calls (POST /calls), messages (POST /messages), flows (connect/call actions), and number configurations.

{
    "type": "<string>",
    "target": "<string>",
    "target_name": "<string>",
    "name": "<string>",
    "detail": "<string>"
}

• type (enum string): Address type. Determines how target is interpreted. See Type.

• target (String): The address endpoint. Format depends on type: E.164 phone number for tel (e.g., +15551234567), extension number for extension (e.g., 2001), agent UUID for agent (obtained from GET /agents), or SIP URI for sip (e.g., user@domain.com).

• target_name (String): Display name associated with the address. For tel type, this is the caller ID name. Optional.

• name (String): A human-readable label for this address. Optional.

• detail (String): Additional description or metadata for this address. Optional.

Note

AI Implementation Hint

When constructing an Address, only type and target are required. For tel type, the target must be in E.164 format with a leading + and no spaces or special characters. For agent type, the target must be a valid agent UUID obtained from GET /agents.

Example

• The tel type address. The target is a phone number in E.164 format.

{
  "type": "tel",
  "target": "+821100000001"
}

• The extension type address. The target is an extension number.

{
  "type": "extension",
  "target": "2001"
}

• The agent type address. The target is the agent’s UUID, obtained from GET /agents.

{
  "type": "agent",
  "target": "eed6a98a-f18d-11ee-96d3-133e13eafff9"
}

• The sip type address. The target is a SIP URI.

{
  "type": "sip",
  "target": "[email protected]"
}

Type

Defines types of address.

Type	Description
agent	Address for calling an agent. target must be the agent’s UUID, obtained from GET /agents.
extension	Address for calling an extension number. target is the extension number string (e.g., 2001).
sip	SIP protocol address. target is a SIP URI (e.g., user@domain.com).
tel	Telephone number address. target must be in E.164 format (e.g., +15551234567).
line	Line type address. Used for LINE messaging integrations. target is the LINE user or channel ID.