API reference

Accounts

Account management and API keys.

get/v1/accounts/{id}

Get account details

Permissionaccount:r

Requires account:r.

Parameters

Parameter	Type	Description
`id`requiredpath	string

Responses

200Account with its active API keys.

Field	Type	Description
`account`required	object	An account, as signup and PATCH /v1/accounts/{id} return it.
`id`required	string
`name`required	string
`email`required	string
`stripe_customer_id`required	string	Can be null
`email_verified_at`required	string	Format: date-time Can be null
`status`required	string	One of: PENDING_PAYMENT \| ACTIVE \| SUSPENDED \| CLOSED
`balance_cents`required	integer	Credit balance in cents CAD.
`verified_phone`required	string	Can be null
`phone_verified_at`required	string	Format: date-time Can be null
`email_undeliverable`required	boolean	True when platform email to this address is bouncing or being marked as spam.
`email_undeliverable_at`required	string	The bounce or complaint that made the address unreachable. Format: date-time Can be null
`email_undeliverable_reason`required	string	BOUNCE or COMPLAINT. Can be null
`terms_accepted_at`required	string	When the owner accepted the Terms of Service and Privacy Policy. Format: date-time Can be null
`terms_version`required	string	The Terms version (last-updated date) that was accepted. Can be null
`created_at`required	string	Format: date-time
`monthly_rent_cents`required	integer	Monthly rent owed on every number not yet released (ACTIVE and SUSPENDED).
`low_balance`required	boolean	True when the credit balance would not cover next month's phone-number rent.
`phone_number_limit`required	integer	Maximum phone numbers this account may hold.
`phone_numbers_used`required	integer	Numbers currently held (ACTIVE and SUSPENDED).
`email_domain_limit`	integer	Maximum live sending domains this account may hold. Present only while email is available.
`email_domains_used`	integer	Live sending domains held (every status but FAILED). Present only while email is available.
`inbound_email_daily_cap`	integer	Received emails this account may accept per rolling 24 h before further mail is stored rejected and uncharged (0 = unlimited); the account's own override, or the platform default. Present only while email is available.
`inbound_email_received_24h`	integer	Received emails counted against the cap above, in the current rolling 24 h window. Present only while email is available.
`inbound_sms_daily_cap`required	integer	Received texts this account may accept per rolling 24 h before further texts are stored uncharged and not delivered as message.received (0 = unlimited); the account's own override, or the platform default.
`inbound_sms_received_24h`required	integer	Received texts counted against the cap above, in the current rolling 24 h window.
`api_keys[]`required	object[]	The account's active USER keys (dashboard session keys are not listed).
`id`required	string
`keyPrefix`required	string	Non-secret prefix for display and identification.
`mode`required	string	One of: LIVE \| TEST
`label`required	string	Can be null
`createdAt`required	string	Format: date-time
`lastUsedAt`required	string	Format: date-time Can be null
`defaultDeny`required	boolean	Present on GET /v1/accounts/me and /v1/accounts/{id}; absent from the login response.
`permissions`required	object	Per-resource permissions. Each key is a resource name; value is a string of allowed operation letters: r=read, w=write/create, m=modify/update, d=delete. A missing key denies all access to that resource.
`email_domain_ids`required	string[]	The email domains this key may send from (ids from /v1/email-domains): null when unrestricted, [] when restricted to none (its domains were deleted). Present on GET /v1/accounts/me and /v1/accounts/{id}; absent from the login response. Can be null
`oauth_grant`required	boolean	True when an OAuth connection holds this key: it can be revoked but not rotated (409 CONFLICT, details.reason "oauth_grant"). Present on GET /v1/accounts/me and /v1/accounts/{id}; absent from the login response.
`features`required	object	Platform capabilities currently available to this account.
`email`required	boolean	True when the email product is live; false while it is still gated.

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403FORBIDDEN: the id is not the calling key's account, or the key lacks the permission this operation requires.The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl https://api.honkio.ca/v1/accounts/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

patch/v1/accounts/{id}

Update account name or settings

Permissionaccount:m

name is required: an omitted or empty value is refused with 422 VALIDATION_ERROR.

Requires account:m.

Parameters

Parameter	Type	Description
`id`requiredpath	string

Request body

Field	Type	Description
`name`	string	Required. At least 1 characters At most 200 characters

Responses

200The updated account.

Field	Type	Description
`id`required	string
`name`required	string
`email`required	string
`stripe_customer_id`required	string	Can be null
`email_verified_at`required	string	Format: date-time Can be null
`status`required	string	One of: PENDING_PAYMENT \| ACTIVE \| SUSPENDED \| CLOSED
`balance_cents`required	integer	Credit balance in cents CAD.
`verified_phone`required	string	Can be null
`phone_verified_at`required	string	Format: date-time Can be null
`email_undeliverable`required	boolean	True when platform email to this address is bouncing or being marked as spam.
`email_undeliverable_at`required	string	The bounce or complaint that made the address unreachable. Format: date-time Can be null
`email_undeliverable_reason`required	string	BOUNCE or COMPLAINT. Can be null
`terms_accepted_at`required	string	When the owner accepted the Terms of Service and Privacy Policy. Format: date-time Can be null
`terms_version`required	string	The Terms version (last-updated date) that was accepted. Can be null
`created_at`required	string	Format: date-time

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403FORBIDDEN: the id is not the calling key's account, or the key lacks the permission this operation requires.The standard error body.
422VALIDATION_ERROR: the request failed validation; details names the fields.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl -X PATCH https://api.honkio.ca/v1/accounts/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Clinics"
  }'

get/v1/accounts/me

Get the account the API key belongs to

Permissionaccount:r

Returns the same document as GET /v1/accounts/{id}, resolving the account from the API key so no id is needed.

Requires account:r.

Responses

200The account the API key belongs to.

Field	Type	Description
`account`required	object	An account, as signup and PATCH /v1/accounts/{id} return it.
`id`required	string
`name`required	string
`email`required	string
`stripe_customer_id`required	string	Can be null
`email_verified_at`required	string	Format: date-time Can be null
`status`required	string	One of: PENDING_PAYMENT \| ACTIVE \| SUSPENDED \| CLOSED
`balance_cents`required	integer	Credit balance in cents CAD.
`verified_phone`required	string	Can be null
`phone_verified_at`required	string	Format: date-time Can be null
`email_undeliverable`required	boolean	True when platform email to this address is bouncing or being marked as spam.
`email_undeliverable_at`required	string	The bounce or complaint that made the address unreachable. Format: date-time Can be null
`email_undeliverable_reason`required	string	BOUNCE or COMPLAINT. Can be null
`terms_accepted_at`required	string	When the owner accepted the Terms of Service and Privacy Policy. Format: date-time Can be null
`terms_version`required	string	The Terms version (last-updated date) that was accepted. Can be null
`created_at`required	string	Format: date-time
`monthly_rent_cents`required	integer	Monthly rent owed on every number not yet released (ACTIVE and SUSPENDED).
`low_balance`required	boolean	True when the credit balance would not cover next month's phone-number rent.
`phone_number_limit`required	integer	Maximum phone numbers this account may hold.
`phone_numbers_used`required	integer	Numbers currently held (ACTIVE and SUSPENDED).
`email_domain_limit`	integer	Maximum live sending domains this account may hold. Present only while email is available.
`email_domains_used`	integer	Live sending domains held (every status but FAILED). Present only while email is available.
`inbound_email_daily_cap`	integer	Received emails this account may accept per rolling 24 h before further mail is stored rejected and uncharged (0 = unlimited); the account's own override, or the platform default. Present only while email is available.
`inbound_email_received_24h`	integer	Received emails counted against the cap above, in the current rolling 24 h window. Present only while email is available.
`inbound_sms_daily_cap`required	integer	Received texts this account may accept per rolling 24 h before further texts are stored uncharged and not delivered as message.received (0 = unlimited); the account's own override, or the platform default.
`inbound_sms_received_24h`required	integer	Received texts counted against the cap above, in the current rolling 24 h window.
`api_keys[]`required	object[]	The account's active USER keys (dashboard session keys are not listed).
`id`required	string
`keyPrefix`required	string	Non-secret prefix for display and identification.
`mode`required	string	One of: LIVE \| TEST
`label`required	string	Can be null
`createdAt`required	string	Format: date-time
`lastUsedAt`required	string	Format: date-time Can be null
`defaultDeny`required	boolean	Present on GET /v1/accounts/me and /v1/accounts/{id}; absent from the login response.
`permissions`required	object	Per-resource permissions. Each key is a resource name; value is a string of allowed operation letters: r=read, w=write/create, m=modify/update, d=delete. A missing key denies all access to that resource.
`email_domain_ids`required	string[]	The email domains this key may send from (ids from /v1/email-domains): null when unrestricted, [] when restricted to none (its domains were deleted). Present on GET /v1/accounts/me and /v1/accounts/{id}; absent from the login response. Can be null
`oauth_grant`required	boolean	True when an OAuth connection holds this key: it can be revoked but not rotated (409 CONFLICT, details.reason "oauth_grant"). Present on GET /v1/accounts/me and /v1/accounts/{id}; absent from the login response.
`features`required	object	Platform capabilities currently available to this account.
`email`required	boolean	True when the email product is live; false while it is still gated.

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl https://api.honkio.ca/v1/accounts/me \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

get/v1/accounts/{id}/topup-allowance

Top-up allowance (balance cap and rolling 30-day cap)

Permissionaccount:r

Requires account:r.

Parameters

Parameter	Type	Description
`id`requiredpath	string

Responses

200How much may be added now. Amounts are CAD cents.

Field	Type	Description
`max_topup_now_cents`required	integer	The largest top-up accepted right now: the smaller of the two headrooms.
`headroom_balance_cents`required	integer	Room left under the balance cap.
`headroom_30d_cents`required	integer	Room left under the rolling 30-day cap.
`max_balance_cents`required	integer
`max_30d_cents`required	integer
`balance_cents`required	integer
`topped_up_30d_cents`required	integer

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403FORBIDDEN: the id is not the calling key's account, or the key lacks the permission this operation requires.The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl https://api.honkio.ca/v1/accounts/ID/topup-allowance \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

get/v1/accounts/{id}/usage

Get usage summary for a billing period

Permissionaccount:r

Message counts, billed cost and segments for the period (defaults to the current calendar month), plus live delivery health: "delivery" { liveOutbound, delivered, failed, undelivered, pending, failureRatePct } over live outbound messages (auto-replies excluded) and "byNumber", the same figures per sending number, busiest first. A rising failureRatePct usually means wrong numbers, landlines, or a script retrying one recipient; above 10 % over your last 50 sends you are emailed and account.delivery_warning fires.

Requires account:r.

Parameters

Parameter	Type	Description
`from`query	string	Start date (YYYY-MM-DD) Format: date
`to`query	string	End date (YYYY-MM-DD) Format: date
`id`requiredpath	string

Responses

200Usage for the period. Field names are camelCase, unlike the rest of the API.

Field	Type	Description
`totalMessages`required	integer	Every message in the period, inbound and test-mode included.
`testMessages`required	integer	How many of totalMessages were test-mode simulations, billed nothing.
`outboundMessages`required	integer
`inboundMessages`required	integer
`totalCostCents`required	integer	What LIVE messages cost, in CAD cents.
`segmentCount`required	integer	LIVE SMS parts billed.
`delivery`required	object
`liveOutbound`required	integer
`delivered`required	integer
`failed`required	integer
`undelivered`required	integer
`pending`required	integer	Accepted, no verdict from the carrier yet.
`failureRatePct`required	number	(failed + undelivered) / liveOutbound x 100, one decimal; 0 with no traffic.
`byNumber[]`required	object[]	The same delivery figures per sending number, busiest first.
`from`required	string
`liveOutbound`required	integer
`delivered`required	integer
`failed`required	integer
`undelivered`required	integer
`failureRatePct`required	number
`period`required	object
`from`required	string	Format: date-time
`to`required	string	Exclusive end of the period. Format: date-time

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403FORBIDDEN: the id is not the calling key's account, or the key lacks the permission this operation requires.The standard error body.
422VALIDATION_ERROR: a malformed date, or to before from.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl https://api.honkio.ca/v1/accounts/ID/usage \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

get/v1/accounts/{id}/transactions

List balance transactions (ledger), newest first

Permissionaccount:r

Every non-message balance movement: Stripe top-ups/refunds/disputes, phone rent, provisioning fees, and verification upcharges, paginated newest first. Per-message SMS/email costs are NOT included here; see the messages/emails list for those.

Requires account:r.

Parameters

Parameter	Type	Description
`limit`query	integer	Minimum: 1 Maximum: 100 Default: 50
`before`query	string	Id of the oldest transaction already seen. Returns the next (older) page.
`id`requiredpath	string

Responses

200Paginated balance transaction ledger

Field	Type	Description
`transactions[]`	object[]
`id`	string
`amount_cents`	integer	Signed: positive = credit, negative = debit
`balance_after_cents`	integer
`reason`	string	Why the balance moved: topup, refund, dispute, phone_rent, provisioning, activation, verification, and their *_refund reversals; admin_adjustment for staff changes. Per-message SMS charges do not appear here: they are on the messages themselves. One-off corrections carry their own reasons (inbound_backfill, overcharge_refund, sweep_reversal).
`tax_cents`	integer	Top-ups only, when sales tax was charged: the GST/HST charged on top of amount_cents. amount_cents is always the credit, before tax. Absent otherwise.
`charged_cents`	integer	Top-ups only, when sales tax was charged: what the card was charged, amount_cents plus tax_cents. Absent otherwise.
`created_at`	string	Format: date-time
`has_more`	boolean

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
404NOT_FOUND: also when the id is not the calling key's account (404 rather than 403, so the ledger's existence is not confirmed).The standard error body.
422VALIDATION_ERROR: the request failed validation; details names the fields.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl https://api.honkio.ca/v1/accounts/ID/transactions \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

post/v1/accounts/{id}/api-keys

Issue a new API key

Permissionapi_keys:w

Requires api_keys:w.

Parameters

Parameter	Type	Description
`id`requiredpath	string
`X-Step-Up-Token`header	string	A token from POST /v1/auth/step-up with the api_keys:elevate scope. Only needed to request permissions broader than the calling key's own, or when the calling key is a dashboard session key.

Request body

Field	Type	Description
`mode`	string	Defaults to the calling key's mode. A test key can only create test keys. One of: live \| test
`label`	string	At most 100 characters
`permissions`	object	Per-resource permissions. Each key is a resource name; value is a string of allowed operations: r=read, w=write, m=modify, d=delete. Omit a resource to deny all access to it. Example: { "messages": "rw", "contacts": "r" }. When omitted, the new key gets the calling key's permissions. A key can only grant permissions it holds itself, unless the request carries an `api_keys:elevate` step-up token (X-Step-Up-Token). A test key can only create test keys. A dashboard session key (the one login mints) always needs that step-up to create a key, even one no broader than itself.
`email_domain_ids`	string[]	Restrict the key to sending email from these domains (ids from /v1/email-domains). Omitted: the key inherits the calling key's restriction, if any. A restricted key can only create keys restricted to a subset of its own domains, unless the request carries an api_keys:elevate step-up token.

Responses

201API key issued. The raw key is shown only once: store it securely.

Field	Type	Description
`key`	string	Full API key (shown once only)
`prefix`	string	Non-secret prefix for display/identification
`mode`	string	One of: live \| test
`permissions`	object	Per-resource permissions.
`email_domain_ids`	string[]	Can be null
`notice`	string

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403FORBIDDEN (not your account), LIVE_KEY_REQUIRED (a test key asked for a live key), KEY_FENCED (the calling key has an allow/deny fence), or PERMISSION_ESCALATION (broader permissions or email domains than the calling key, or a dashboard session key, without an api_keys:elevate step-up).The standard error body.
422VALIDATION_ERROR: the request failed validation; details names the fields.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl -X POST https://api.honkio.ca/v1/accounts/ID/api-keys \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "live",
    "label": "Production server"
  }'

post/v1/accounts/{id}/api-keys/{keyId}/rotate

Rotate an API key (issue replacement and revoke the old one atomically)

Permissionapi_keys:w

Session keys (the ones minted by dashboard login) can't be rotated: they always expire on their own; rotating one returns 409 CONFLICT with details.reason "session_key". Rotate a USER key instead. A key an OAuth connection holds (oauth_grant on the keys list) can't be rotated either: the replacement would not belong to the connection, so the app would stop working. That returns 409 CONFLICT with details.reason "oauth_grant"; revoke the connection and reconnect instead.

Requires api_keys:w.

Parameters

Parameter	Type	Description
`id`requiredpath	string
`keyId`requiredpath	string
`X-Step-Up-Token`header	string	A token from POST /v1/auth/step-up with the api_keys:elevate scope. Only needed to rotate a key into one holding more than the calling key's own permissions, or when the calling key is a dashboard session key.

Responses

201The replacement key, shown once. The old key is revoked in the same step; the new one keeps its mode, label, permissions, default-deny setting, lists and email-domain restriction.

Field	Type	Description
`key`required	string	The full new API key (shown once only).
`prefix`required	string
`mode`required	string	One of: live \| test
`revoked_id`required	string	The id of the key this replaced.
`notice`required	string

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403FORBIDDEN (not your account), LIVE_KEY_REQUIRED (a test key rotating a live key), KEY_FENCED (a key with an allow/deny fence rotating any key but itself), or PERMISSION_ESCALATION (the target holds more than the calling key, or the caller is a dashboard session key, without an api_keys:elevate step-up).The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
409CONFLICT: the key is already revoked, is being rotated by another request, is a dashboard session key (details.reason is session_key), or is held by an OAuth connection (details.reason is oauth_grant).The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl -X POST https://api.honkio.ca/v1/accounts/ID/api-keys/KEY_ID/rotate \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

delete/v1/accounts/{id}/api-keys/{keyId}

Revoke an API key

Permissionapi_keys:d

Requires api_keys:d.

Parameters

Parameter	Type	Description
`id`requiredpath	string
`keyId`requiredpath	string

Responses

204Revoked.
401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403FORBIDDEN (not your account) or LIVE_KEY_REQUIRED (a test key revoking a live key).The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl -X DELETE https://api.honkio.ca/v1/accounts/ID/api-keys/KEY_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

patch/v1/accounts/{id}/api-keys/{keyId}/default-deny

Toggle default-deny mode for an API key

Permissionapi_keys:m

When default_deny is true, messages via this key are blocked unless the recipient is in an assigned ALLOW list.

Requires api_keys:m.

Parameters

Parameter	Type	Description
`id`requiredpath	string
`keyId`requiredpath	string

Request body

Field	Type	Description
`default_deny`required	boolean

Responses

200The key's new default-deny setting.
Field Type Description
api_key_idrequired string
default_denyrequired boolean
401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403FORBIDDEN (not your account), LIVE_KEY_REQUIRED (a test key changing a live key), or KEY_FENCED (a fenced key changing its own or any other key's default-deny).The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
422VALIDATION_ERROR: the request failed validation; details names the fields.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl -X PATCH https://api.honkio.ca/v1/accounts/ID/api-keys/KEY_ID/default-deny \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "default_deny": false
  }'

get/v1/accounts/{id}/api-keys/{keyId}/lists

Get allow/deny list assignments for an API key

Permissionapi_keys:r

Requires api_keys:r.

Parameters

Parameter	Type	Description
`id`requiredpath	string
`keyId`requiredpath	string

Responses

200The key's allow and deny lists, null when none is assigned.
Field Type Description
allow_listrequired object | any
deny_listrequired object | any
401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403FORBIDDEN: the id is not the calling key's account, or the key lacks the permission this operation requires.The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl https://api.honkio.ca/v1/accounts/ID/api-keys/KEY_ID/lists \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

put/v1/accounts/{id}/api-keys/{keyId}/lists/{mode}

Assign an allow or deny list to an API key

Permissionapi_keys:m

Requires api_keys:m.

Parameters

Parameter	Type	Description
`id`requiredpath	string
`keyId`requiredpath	string
`mode`requiredpath	string	One of: allow \| deny

Request body

Field	Type	Description
`list_id`required	string

Responses

200The list now assigned.
Field Type Description
api_key_idrequired string
moderequired string
One of: ALLOW | DENY
list_idrequired string
401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403FORBIDDEN (not your account), LIVE_KEY_REQUIRED (a test key changing a live key), or KEY_FENCED (a fenced key changing its own or any other key's lists).The standard error body.
404NOT_FOUND (no such key) or CONTACT_LIST_NOT_FOUND.The standard error body.
422VALIDATION_ERROR: the request failed validation; details names the fields.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl -X PUT https://api.honkio.ca/v1/accounts/ID/api-keys/KEY_ID/lists/MODE \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "list_id": "..."
  }'

delete/v1/accounts/{id}/api-keys/{keyId}/lists/{mode}

Remove an allow or deny list from an API key

Permissionapi_keys:m

Requires api_keys:m.

Parameters

Parameter	Type	Description
`id`requiredpath	string
`keyId`requiredpath	string
`mode`requiredpath	string	One of: allow \| deny

Responses

204Unassigned (also when nothing was assigned).
401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403FORBIDDEN (not your account), LIVE_KEY_REQUIRED (a test key changing a live key), or KEY_FENCED (a fenced key changing its own or any other key's lists).The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
422VALIDATION_ERROR: the request failed validation; details names the fields.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl -X DELETE https://api.honkio.ca/v1/accounts/ID/api-keys/KEY_ID/lists/MODE \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

post/v1/accounts/{id}/phone-verification

Start account owner phone verification

Permissionaccount:m

Requires account:m.

Parameters

Parameter	Type	Description
`id`requiredpath	string

Request body

Field	Type	Description
`phone`required	string	Canadian or US NANP number in E.164, e.g. +14165551234

Responses

200The code was sent by SMS.
Field Type Description
sentrequired boolean
One of: true
expires_in_secondsrequired integer
401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403FORBIDDEN (not your account) or LIVE_KEY_REQUIRED (owner verification needs a live key).The standard error body.
422VALIDATION_ERROR: the request failed validation; details names the fields.The standard error body.
429RATE_LIMITED: 3 codes per hour per account.The standard error body.
500Unexpected server error.The standard error body.
502CARRIER_ERROR: the carrier did not accept the SMS.The standard error body.
503SERVICE_UNAVAILABLE: owner verification is not configured.The standard error body.

Example

cURL

curl -X POST https://api.honkio.ca/v1/accounts/ID/phone-verification \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+1613XXXXXXX"
  }'

post/v1/accounts/{id}/phone-verification/confirm

Confirm OTP to complete phone verification

Permissionaccount:m

Requires account:m.

Parameters

Parameter	Type	Description
`id`requiredpath	string

Request body

Field	Type	Description
`code`required	string	The 6-digit code sent by SMS

Responses

200Verified: live sending is unlocked.
Field Type Description
verifiedrequired boolean
One of: true
verified_phonerequired string
verified_atrequired string
Format: date-time
401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403FORBIDDEN (not your account) or LIVE_KEY_REQUIRED (owner verification needs a live key).The standard error body.
422VALIDATION_ERROR, VERIFICATION_EXPIRED (no code pending; body statusCode 422) or VERIFICATION_INVALID_CODE.The standard error body.
429VERIFICATION_MAX_ATTEMPTS: five wrong codes; request a new one.The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl -X POST https://api.honkio.ca/v1/accounts/ID/phone-verification/confirm \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "123456"
  }'

get/v1/send-limit

Your sending limits and current usage

Permissionaccount:r

The daily cap (a rolling 24 hours), how much of it is used, the per-recipient cap, the probation status that gates "request a higher volume", any active pause, and your past requests.

Requires account:r.

Responses

200Sending limits, usage and past volume requests.

Field	Type	Description
`daily_limit`required	integer	Live sends allowed in a rolling 24 hours.
`sent_last_24h`required	integer
`remaining`required	integer
`window_hours`required	integer
`approved_daily_limit`required	integer	The standard volume a request is granted by default.
`probation_days`required	integer
`recipient_rate_per_hour`required	integer	Messages one recipient may receive from the account in an hour.
`recipient_rate_per_day`required	integer	Messages one recipient may receive from the account in a day.
`probation`required	object
`started_at`required	string	The first live send; null before it. Format: date-time Can be null
`ends_at`required	string	Format: date-time Can be null
`eligible_to_request`required	boolean
`paused_until`required	string	Set while sending is paused. Format: date-time Can be null
`pause_reason`required	string	Why sending is paused: OPT_OUT_RATE, FAILURE_RATE or MANUAL. Can be null
`requests[]`required	object[]
`id`required	string
`requested_limit`required	integer	Messages per day asked for; null asks for the standard approved volume. Can be null
`limit_at_request`required	integer
`sent_last_30d_at_request`required	integer
`reason`required	string
`status`required	string	One of: PENDING \| APPROVED \| DENIED
`granted_limit`required	integer	Can be null
`staff_note`required	string	Can be null
`decided_at`required	string	Format: date-time Can be null
`created_at`required	string	Format: date-time

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl https://api.honkio.ca/v1/send-limit \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

get/v1/send-limit/requests

List your volume requests

Permissionaccount:r

Requires account:r.

Responses

200The account's volume requests, newest first.

Field	Type	Description
`data[]`required	object[]
`id`required	string
`requested_limit`required	integer	Messages per day asked for; null asks for the standard approved volume. Can be null
`limit_at_request`required	integer
`sent_last_30d_at_request`required	integer
`reason`required	string
`status`required	string	One of: PENDING \| APPROVED \| DENIED
`granted_limit`required	integer	Can be null
`staff_note`required	string	Can be null
`decided_at`required	string	Format: date-time Can be null
`created_at`required	string	Format: date-time

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl https://api.honkio.ca/v1/send-limit/requests \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

post/v1/send-limit/requests

Request a higher daily sending volume

Permissionaccount:w

Opens once the account has completed its probation period (counted from its first live send). Omit requested_limit to ask for the standard approved volume, or name a target. One request may be pending at a time; you are emailed when it is decided.

Requires account:w.

Request body

Field	Type	Description
`requested_limit`	integer	Messages per day you want (not an increment). Omit for the standard approved volume. Minimum: 1 Maximum: 1000000
`reason`required	string	What you send and to whom. Staff decide on this. 10 to 1000 characters.

Responses

201The request, pending review.

Field	Type	Description
`id`required	string
`requested_limit`required	integer	Messages per day asked for; null asks for the standard approved volume. Can be null
`limit_at_request`required	integer
`sent_last_30d_at_request`required	integer
`reason`required	string
`status`required	string	One of: PENDING \| APPROVED \| DENIED
`granted_limit`required	integer	Can be null
`staff_note`required	string	Can be null
`decided_at`required	string	Format: date-time Can be null
`created_at`required	string	Format: date-time

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403SEND_LIMIT_REQUEST_TOO_EARLY (probation not over; details.eligible_at) or LIVE_KEY_REQUIRED.The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
409SEND_LIMIT_REQUEST_PENDING: a request is already pending.The standard error body.
422VALIDATION_ERROR: the request failed validation; details names the fields.The standard error body.
429RATE_LIMITED: 3 requests per day per account.The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl -X POST https://api.honkio.ca/v1/send-limit/requests \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "..."
  }'

Field	Type	Description
`allow_list`required	object \| any
`deny_list`required	object \| any

Field	Type	Description
`api_key_id`required	string
`mode`required	string	One of: ALLOW \| DENY
`list_id`required	string

Field	Type	Description
`sent`required	boolean	One of: true
`expires_in_seconds`required	integer

Field	Type	Description
`verified`required	boolean	One of: true
`verified_phone`required	string
`verified_at`required	string	Format: date-time