HonkIOHonkIO

Reference

API reference

Every operation of the HonkIO REST API, one page per resource: parameters, request bodies, responses, the permission each one needs, and an example request.

Base URL

Every request goes to https://api.honkio.ca over HTTPS, and every path starts with /v1. Request bodies are JSON, sent with Content-Type: application/json, and so is every response body.

Authentication

Send an API key with every request, in either of these headers. A test key (mk_test_) runs the same checks as a live key without sending or charging anything. Authentication and API keys covers test mode and the permissions of each key.

HeaderDescription
Authorization: Bearer mk_live_YOUR_KEY

Use mk_live_... for production or mk_test_... for testing.

X-API-Key: mk_live_YOUR_KEY

Alternative to the Authorization header: send mk_live_... or mk_test_... as X-API-Key directly.

Only the price list (GET /v1/pricing) answers without a key.

Idempotency

Sending an SMS, a group broadcast or an email reads an Idempotency-Key header. Send a unique key with any request you might retry: a repeat with the same key returns the first response instead of sending, and charging, a second time.

Pagination

List operations page in one of three ways, depending on the resource: page and limit, limit and offset, or limit and a cursor. The parameters and response fields of each list operation show which one it uses.

Errors

An error answers with its HTTP status and the same JSON body on every route: a stable code, a message in the language of the request’s Accept-Language header, the message in English and in French, the status again, and on some errors a details value. Errors lists every code.

json
{
  "code": "NOT_FOUND",
  "message": "Resource not found.",
  "messageEn": "Resource not found.",
  "messageFr": "Ressource introuvable.",
  "statusCode": 404
}

Interactive explorer

To try a request from your browser, the interactive explorer runs every operation against the API with your own key. It is in English only.

Resources

One page per resource. Each operation lists its parameters, request body, responses and the permission it needs, with an example request.