API Docs - Ziett

Ziett is a powerful, developer-first communication platform designed to simplify high-volume messaging across multiple channels. Our API is organized around REST, using standard HTTP verbs, status codes, and JSON-formatted responses.

Whether you're sending transactional SMS, managing WhatsApp campaigns, or building complex notification workflows, the Ziett API provides the reliability and scalability your application requires.

Authentication

Ziett uses different authentication methods depending on the scope of the request.

API Keys (Public Service)

For programmatic integrations (sending messages, managing campaigns via SDKs or HTTP clients), use an API Key.

Header: X-API-KEY

Scope: Public paths (prefixed with /c/v1)

Your API Keys are secrets. Never share them in client-side code, public repositories, or with unauthorized personnel.

OAuth2 Bearer Tokens (Dashboard & Internal)

Resources prefixed with /v1 (Internal/Dashboard use) require an OAuth2 Bearer token obtained via our authentication service.

Header: Authorization: Bearer <your_token>

API Structure & Scopes

The API is divided into three logical layers to ensure security and clarity:

Public Service (/c/v1): The entry point for developers. This is where you send messages, create batches, and check delivery statuses.

Organization Management (/a): Used by the Ziett Dashboard to manage your organization, members, billing accounts, and settings.

Platform Administration (/m): Internal routes for Ziett platform oversight.

Success Responses

Ziett doesn't just return 200 OK. For asynchronous operations (like queuing a batch), we return a descriptive response to help you track the lifecycle of your request.

{
  "message": "Campaign validation successful. Processing 1,500 messages in the background.",
  "campaign_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error Handling

Ziett uses standard HTTP status codes to indicate the success or failure of an API request. Codes in the 4xx range indicate an error that resulted from the provided information (e.g., missing parameter, insufficient funds), while codes in the 5xx range indicate an error with Ziett's servers.

Error Object

All error responses return a consistent JSON payload:

Field	Type	Description
`code`	`string`	A machine-readable error category (e.g., `BILLING_INSUFFICIENT_FUNDS`).
`message`	`string`	A human-readable message describing the error.
`status`	`int`	The HTTP status code.
`trace_id`	`uuid`	A unique identifier for the request, useful for support troubleshooting.
`fields`	`object`	(Optional) Key-value pairs of specific validation errors.

Example Error

{
  "code": "AUTH_INVALID_SCOPE",
  "message": "Insufficient permissions (missing scope).",
  "status": 403,
  "trace_id": "d309f78ae57744358a9e7011c123c831",
  "timestamp": "2025-02-17T18:25:08.940951+00:00",
  "service": "core",
  "fields": {
    "apikey": "The provided key does not have the 'messages:send' scope."
  }
}

Pagination & Listing

All listing routes (e.g., GET /c/v1/messages) return a paginated response to ensure performance.

Query Parameters

Parameter	Default	Max	Description
`page`	`1`	-	The page index to retrieve.
`size`	`30`	`200`	Number of records per page.
`order_by`	`created_at`	-	Attribute to sort by.
`order`	`desc`	-	`asc` or `desc`.

Response Format

{
    "total": 1250,
    "page": 1,
    "size": 30,
    "pages": 42,
    "entries": [
        { ... },
        { ... }
    ]
}

Rate Limits

To ensure platform stability and protect against abuse, Ziett enforces rate limits on several endpoints.

Standard Limits: Most listing and retrieval endpoints allow for generous burst traffic.

Critical Operations: Endpoints like POST /c/v1/campaigns/batch are limited to 10 requests per minute per API Key.

When a limit is reached, the API returns a 429 Too Many Requests status. We recommend implementing an exponential backoff strategy in your integration.

Next Steps

Ready to build? Explore the rest of our documentation:

API Reference: Complete OpenAPI spec for all public endpoints.

SDKs: Official libraries for Python, Node.js, and more.

Webhooks: Real-time delivery and inbound message notifications.

Learning Center: Best practices for sender ID registration and message optimization.

API Docs - Ziett

Authentication#

API Keys (Public Service)#

OAuth2 Bearer Tokens (Dashboard & Internal)#

API Structure & Scopes#

Success Responses#

Error Handling#

Error Object#

Example Error#

Pagination & Listing#

Query Parameters#

Response Format#

Rate Limits#

Next Steps#