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. Always false while the account is comped.
`rent_owed_cents`required	integer	Rent owed (CAD cents) on a number that was released while suspended, 0 when nothing is owed. While it is above 0, paid sends and number purchases are refused with RENT_OWED; a top-up pays it first. Not enforced while the account is comped.
`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_email_daily_mb_cap`	integer	Billable MB of received email (each message's started MB above the first, the part priced per MB) this account may accept per rolling 24 h; a message that would go past it is stored rejected (daily_mb_cap) and uncharged (0 = unlimited). The account's own override, or the platform default. Present only while email is available.
`inbound_email_mb_received_24h`	integer	Billable MB counted against the MB cap above, in the current rolling 24 h window. Present only while email is available.
`inbound_sms_daily_cap`required	integer	Received SMS segments (the billed unit: a long text counts as several) 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 SMS segments 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.
`push`	boolean	Present, and true, when the push notification product is live.
`notify`	boolean	Present, and true, when Notify (/v1/notify, /v1/recipients) is live.
`honkio_auth`	boolean	Present, and true, when HonkIO Auth is available to this account.
`comped`required	object	Set while HonkIO provides this account free of charge (comped): nothing is charged to the balance, which is kept as it was. Null otherwise. Can be null
`since`required	string	When the account was comped. Format: date-time
`month_cost_cents`required	integer	What this account's usage has cost HonkIO this calendar month (Eastern time), in CAD cents.
`threshold_cents`required	integer	The monthly usage, in CAD cents, past which the owner is emailed, at most once a month. Sending continues past it.

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, plus caller: the calling key's mode and, for an OAuth connection, the client it was granted to.

Requires account:r.

Responses

200The account the API key belongs to, and who is calling.

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. Always false while the account is comped.
`rent_owed_cents`required	integer	Rent owed (CAD cents) on a number that was released while suspended, 0 when nothing is owed. While it is above 0, paid sends and number purchases are refused with RENT_OWED; a top-up pays it first. Not enforced while the account is comped.
`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_email_daily_mb_cap`	integer	Billable MB of received email (each message's started MB above the first, the part priced per MB) this account may accept per rolling 24 h; a message that would go past it is stored rejected (daily_mb_cap) and uncharged (0 = unlimited). The account's own override, or the platform default. Present only while email is available.
`inbound_email_mb_received_24h`	integer	Billable MB counted against the MB cap above, in the current rolling 24 h window. Present only while email is available.
`inbound_sms_daily_cap`required	integer	Received SMS segments (the billed unit: a long text counts as several) 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 SMS segments 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.
`push`	boolean	Present, and true, when the push notification product is live.
`notify`	boolean	Present, and true, when Notify (/v1/notify, /v1/recipients) is live.
`honkio_auth`	boolean	Present, and true, when HonkIO Auth is available to this account.
`comped`required	object	Set while HonkIO provides this account free of charge (comped): nothing is charged to the balance, which is kept as it was. Null otherwise. Can be null
`since`required	string	When the account was comped. Format: date-time
`month_cost_cents`required	integer	What this account's usage has cost HonkIO this calendar month (Eastern time), in CAD cents.
`threshold_cents`required	integer	The monthly usage, in CAD cents, past which the owner is emailed, at most once a month. Sending continues past it.
`caller`required	object	Who is calling: the key's mode and, for an OAuth connection, its client.
`mode`required	string	The mode of the key that made this request. A TEST key is a sandbox: nothing it sends reaches a carrier or is charged. One of: LIVE \| TEST
`oauth_client`required	object	The OAuth client this request's access token was granted to; null when the request used an API key. Can be null
`id`required	string	The client id: its metadata document URL, or a dcr_ id for a client that registered itself.
`name`required	string	The client name shown on the consent page when the connection was approved.

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 (all, live and test), billed cost and segments for the period (defaults to the current calendar month), the period's live email counts and their price in CAD millicents (emailCostMillicents) while email is available, 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
`liveOutboundMessages`required	integer	The LIVE share of outboundMessages.
`liveInboundMessages`required	integer	The LIVE share of inboundMessages.
`totalCostCents`required	integer	What LIVE messages cost, in CAD cents. Emails, phone numbers and HonkIO Auth plans are not included.
`segmentCount`required	integer	LIVE SMS segments billed.
`emailsSent`	integer	LIVE emails handed to the provider in the period (sent, delivered, bounced or complained). Present only while email is available.
`emailsReceived`	integer	LIVE emails received and delivered to the account in the period (not those refused over the inbound cap). Present only while email is available.
`emailCostMillicents`	integer	What emailsSent and emailsReceived were priced at, in CAD millicents (thousandths of a cent). Present only while email is available.
`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), PERMISSION_ESCALATION (broader permissions or email domains than the calling key, or a dashboard session key, without an api_keys:elevate step-up), or ACCOUNT_EMAIL_NOT_VERIFIED (the account has not verified its email address yet; no key, live or test, is created until it has).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. The key's scheduled and queued emails are kept: they go out as planned, under the replacement. To stop them as well, as when a key has leaked, revoke the key (DELETE) 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), 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), or ACCOUNT_EMAIL_NOT_VERIFIED (the account has not verified its email address yet).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

Revokes the key at once. Emails it scheduled or queued that have not gone out are not sent: each is failed with failure_code API_KEY_REVOKED and refunded when it comes due. This is how to contain a leaked key; rotating keeps them.

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.

Field	Type	Description
`api_key_id`required	string
`default_deny`required	boolean

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.

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

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

The list must be of the key's mode (contacts, groups and lists are kept per key mode): a test key takes a test list and a live key a live one, and a list of the other mode answers CONTACT_LIST_NOT_FOUND.

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 (no such list, or the list is of the other mode: a key takes lists of its own mode only).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.

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

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. CARRIER_THROTTLED: the carrier asked us to slow down and did not take the SMS; ask again after Retry-After.The standard error body.

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

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.

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

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

Your auto top-up settings

Permissionaccount:rNode.js SDKhonkio.autoTopup.get()

Whether auto top-up is on, the balance that triggers it and the amount it adds, a summary of the saved card, whether it is paused and why, and the 10 most recent attempts. available is false when auto top-up cannot be used on this platform right now. It is turned on with a top-up on the dashboard, which saves the card; it cannot be changed with an API key.

Requires account:r.

Responses

200Auto top-up settings, saved card summary, pause state and recent attempts.

Field	Type	Description
`available`required	boolean	False when auto top-up cannot be used on this platform right now. The other fields still describe your settings.
`enabled`required	boolean	Whether auto top-up is on. It can be on and paused (paused_at).
`threshold_cents`required	integer	When your balance falls below this, in CAD cents, your card is charged. Null before auto top-up was first turned on. Can be null
`amount_cents`required	integer	The credit each auto top-up adds, in CAD cents, before tax. Always at least threshold_cents, so one top-up brings the balance back up to it. Null before auto top-up was first turned on. Can be null
`card`required	object \| any	The saved card auto top-up charges. Null when none is saved.
`paused_at`required	string	When auto top-up was paused. Nothing is charged while it is paused. You resume it with "Top up to resume" in the Auto top-up section of the dashboard's Billing page, which is a new top-up that saves your card again. A pause for ACCOUNT_REVIEW cannot be resumed that way (see paused_reason). Format: date-time Can be null
`paused_reason`required	string	Why it was paused: the card was declined, needed authentication, expired or was removed; the billing address could not be used for tax; a payment was refunded and taken off the balance (REFUND); it reached its limit of 3 charges in 24 hours (CHARGE_LIMIT); the account is under review; or HonkIO staff paused it. You resume from every reason except ACCOUNT_REVIEW with "Top up to resume" on the dashboard. You cannot resume from ACCOUNT_REVIEW yourself. The account.auto_topup_paused webhook event carries the same value as reason. One of: DECLINED \| AUTHENTICATION_REQUIRED \| EXPIRED_CARD \| CARD_REMOVED \| BILLING_ADDRESS \| ACCOUNT_REVIEW \| ADMIN \| REFUND \| CHARGE_LIMIT Can be null
`cap_blocked`required	boolean	True while auto top-up is skipping charges because one would go over your balance or 30-day top-up limit.
`setup_pending`required	boolean	True when a setup was started and not finished: settings were chosen on the dashboard and the top-up that saves the card has not completed. They take effect only when it does. False once it completes, and after the settings are edited or auto top-up is turned off.
`monthly_rent_cents`required	integer	Monthly rent of the numbers you hold, in CAD cents. Auto top-up also tops up ahead of rent due within a day.
`attempts[]`required	object[]	The 10 most recent attempts, newest first.
`id`required	string	ata_…
`trigger`required	string	threshold: the balance fell below threshold_cents. rent: the balance was below the number rent due within 24 hours. One of: threshold \| rent
`status`required	string	skipped_cap: not charged, because the top-up would have gone over your balance or 30-day top-up limit. One of: pending \| succeeded \| failed \| skipped_cap
`amount_cents`required	integer	The credit added to your balance, in CAD cents.
`tax_cents`required	integer	Sales tax charged on top of amount_cents, in CAD cents. Null when no tax was calculated. Can be null
`total_cents`required	integer	What the card was charged, in CAD cents: amount_cents plus tax_cents. Null before the charge is made. Can be null
`failure_code`required	string	Why a failed attempt failed: a card code such as card_declined or expired_card, or platform_error when the failure was on HonkIO's side (auto top-up is not paused and tries again). Attempts that charged nothing and paused nothing (abandoned, not_needed) are never shown. Can be null
`created_at`required	string	Format: date-time
`settled_at`required	string	Format: date-time Can be null

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

const { data, error } = await honkio.autoTopup.get()
if (error) throw new Error(error.message)
console.log(data.enabled, data.paused_at)

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

get/v1/send-limit

Your sending limits and current usage

Permissionaccount:rNode.js SDKhonkio.sendLimit.get()

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. The top-level cap and usage are for sends from local numbers; toll_free holds the separate allowance for sends from toll-free numbers, which has no probation. number_queues shows each of your numbers' carrier queue: the segments a minute it sends, the segments waiting now, and when they should have gone out (an estimate).

Requires account:r.

Responses

200Sending limits, usage and past volume requests.

Field	Type	Description
`daily_limit`required	integer	Live sends from local numbers allowed in a rolling 24 hours. null when the account has no daily limit. Can be null
`sent_last_24h`required	integer
`remaining`required	integer	null when the account has no daily limit. Can be null
`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
`verify_pause`required	any \| object	Live verification codes paused by SMS-pumping detection (POST /v1/verify answers 403 SENDING_PAUSED with details.channel "verify"); messages are not affected. null when nothing is paused. DELETE /v1/verify/pause lifts it.
`toll_free`required	object	The separate allowance for sends from toll-free numbers. Sends from local numbers count toward the top-level figures only.
`daily_limit`required	integer	Live sends from toll-free numbers allowed in a rolling 24 hours. There is no probation. null when the account has no daily limit. Can be null
`sent_last_24h`required	integer	Live sends from toll-free numbers in the last 24 hours.
`remaining`required	integer	null when the account has no daily limit. Can be null
`fanout_max_recipients`required	integer	Distinct recipients one identical body may reach from toll-free numbers in 24 hours.
`broadcast_max_recipients`required	integer	Members a contact-group broadcast from a toll-free number may reach.
`broadcasts_per_day`required	integer	Contact-group broadcasts from toll-free numbers per rolling 24 hours.
`number_queues[]`required	object[]	Each of your active numbers' carrier queue: the carrier sends a number's message segments at a fixed pace, so a list takes time. An estimate, from the segments already handed over.
`phone_number`required	string
`parts_per_minute`required	integer	Message segments the carrier sends from this number a minute (10 for a local number).
`queued_parts`required	integer	Parts waiting now. A single send is refused with NUMBER_RATE_LIMITED while a minute's worth are waiting.
`clears_at`required	string	When the segments waiting now should all have gone out; null when none are waiting. Format: date-time 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

const { data, error } = await honkio.sendLimit.get()
if (error) throw new Error(error.message)
// daily_limit and remaining are null when the account has no daily limit.
if (data.daily_limit === null) console.log('no daily limit')
else console.log(data.remaining, 'of', data.daily_limit, 'left')
for (const q of data.number_queues) console.log(q.phone_number, q.queued_parts, q.clears_at)

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

Needs a verified business (BUSINESS_VERIFICATION_REQUIRED until then; see /v1/business-verification), and 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.
403BUSINESS_VERIFICATION_REQUIRED (verify your business first), SEND_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": "..."
  }'

get/v1/business-verification

Get your business verification

Permissionaccount:rNode.js SDKhonkio.businessVerification.get()

Your business profile and where its review stands, or null before one is saved. A verified business can request more phone numbers, a higher sending volume, higher top-up limits and toll-free verification.

Requires account:r.

Responses

200Your business verification profile, or null before one is saved.
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

const { data: profile, error } = await honkio.businessVerification.get()
if (error) throw new Error(error.message)
console.log(profile?.status ?? 'not started')

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

put/v1/business-verification

Save your business verification profile

Permissionaccount:mNode.js SDKhonkio.businessVerification.save()

Creates the profile, or replaces it while it is DRAFT, VERIFIED, CHANGES_REQUESTED or DECLINED (BUSINESS_VERIFICATION_NOT_EDITABLE otherwise). Every field is checked. The status does not change, except that a VERIFIED profile goes back to DRAFT: submit it when it is ready. Changes to a verified business go back to HonkIO for review, and the account stays verified (verified is true) in the meantime, as it was verified: verified_details, not the changed fields, is what counts until HonkIO verifies the changes. A test key can save a profile that was never verified, but changing a verified business needs a live key (LIVE_KEY_REQUIRED).

Requires account:m.

Request body

Your business and a contact person.

Field	Type	Description
`business_name`required	string	The legal name: as registered with the CRA or your province, or your own name for a sole proprietorship. At least 1 characters At most 255 characters
`doing_business_as`	string	The name the business trades under, when it differs from the legal name. At most 255 characters Can be null
`entity_type`required	string	The kind of organization. GET /v1/toll-free-verifications/options lists the values with labels. One of: SOLE_PROPRIETOR \| PRIVATE_PROFIT \| PUBLIC_PROFIT \| NON_PROFIT \| GOVERNMENT
`business_registration_number`	string	The CRA business number: 9 digits, optionally followed by a program account such as RC0001. Spaces and hyphens are ignored. Required unless entity_type is SOLE_PROPRIETOR. At most 40 characters Can be null
`business_address`required	object	Where the business is registered or operates, in Canada. line2 (suite, unit or floor) is optional.
`line1`required	string	At least 1 characters At most 255 characters
`city`required	string	At least 1 characters At most 100 characters
`province`required	string	Two-letter province or territory code. One of: AB \| BC \| MB \| NB \| NL \| NS \| NT \| NU \| ON \| PE \| QC \| SK \| YT
`postal_code`required	string	Canadian postal code, e.g. K1A 0B1. At most 10 characters
`line2`	string	At most 255 characters Can be null
`website`required	string	An https link that shows the business: its website or, for a sole proprietor, a public profile such as LinkedIn or an app store listing. At most 2048 characters
`business_description`required	string	What the business does and who it serves, 20 to 500 characters. At least 20 characters At most 500 characters
`contact`required	object	The person HonkIO staff can contact about the review.
`first_name`required	string	At least 1 characters At most 100 characters
`last_name`required	string	At least 1 characters At most 100 characters
`email`required	string	Format: email At most 254 characters
`phone`required	string	A North American phone number, e.g. +14165550100. At most 32 characters

Responses

200The saved profile.

Field	Type	Description
`id`required	string
`status`required	string	DRAFT, then IN_REVIEW (HonkIO staff), then VERIFIED. CHANGES_REQUESTED and DECLINED can be edited and submitted again; REVOKED can only be restored by HonkIO staff. Editing a VERIFIED profile moves it back to DRAFT for another review. One of: DRAFT \| IN_REVIEW \| VERIFIED \| CHANGES_REQUESTED \| DECLINED \| REVOKED
`verified`required	boolean	Whether the business counts as verified. It stays true while the changed details of a verified business are reviewed again (status DRAFT, IN_REVIEW or CHANGES_REQUESTED), and turns false when HonkIO staff decline the changes or revoke the verification.
`verified_at`required	string	When HonkIO staff last verified the business; null when it is not verified. Format: date-time Can be null
`verified_details`required	object \| any	The business as HonkIO staff last verified it. While changed details are reviewed again, the fields below show the changes and this keeps what was verified: toll-free verification reads its business number. Null when the business is not verified.
`business_name`required	string
`doing_business_as`required	string	Can be null
`entity_type`required	string	One of: SOLE_PROPRIETOR \| PRIVATE_PROFIT \| PUBLIC_PROFIT \| NON_PROFIT \| GOVERNMENT
`business_registration_number`required	string	Can be null
`business_address`required	object \| any
`website`required	string	Can be null
`business_description`required	string	Can be null
`contact`required	object
`first_name`required	string	Can be null
`last_name`required	string	Can be null
`email`required	string	Can be null
`phone`required	string	Can be null
`reviewer_note`required	string	What HonkIO staff asked to change, or why they declined the profile. Can be null
`revoked_reason`required	string	Why HonkIO staff revoked the verification. Can be null
`submitted_at`required	string	Format: date-time Can be null
`reviewed_at`required	string	Format: date-time Can be null
`revoked_at`required	string	Format: date-time Can be null
`created_at`required	string	Format: date-time
`updated_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.
403LIVE_KEY_REQUIRED: a test key cannot change the profile of a verified business, including one whose changed details are in review. It can save a profile that was never verified. Also FORBIDDEN when the key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
409BUSINESS_VERIFICATION_NOT_EDITABLE: the profile is in review or revoked.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

const { error } = await honkio.businessVerification.save({
  businessName: 'Acme Clinics Inc.',
  entityType: 'PRIVATE_PROFIT',
  businessRegistrationNumber: '123456789RC0001', // optional for a sole proprietor
  businessAddress: { line1: '100 King St W', city: 'Toronto', province: 'ON', postalCode: 'M5X 1A9' },
  website: 'https://acme.ca',
  businessDescription: 'Three clinics in Toronto that text patients appointment reminders.',
  contact: { firstName: 'Ada', lastName: 'Lovelace', email: 'ada@acme.ca', phone: '+1416XXXXXXX' },
})
if (error) throw new Error(`${error.name}: ${error.message}`)

curl -X PUT https://api.honkio.ca/v1/business-verification \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "...",
    "entity_type": "SOLE_PROPRIETOR",
    "business_address": {
      "line1": "...",
      "city": "...",
      "province": "AB",
      "postal_code": "..."
    },
    "website": "...",
    "business_description": "...",
    "contact": {
      "first_name": "...",
      "last_name": "...",
      "email": "sam@example.com",
      "phone": "+1613XXXXXXX"
    }
  }'

post/v1/business-verification/submit

Submit your business for verification

Permissionaccount:wNode.js SDKhonkio.businessVerification.submit()

Sends the saved profile to HonkIO staff for review (IN_REVIEW). They check it against public registries and your website, then verify it, ask for changes or decline it; you are emailed either way. A verified business that changed its details stays verified during the review; declining the changes removes the verification. Live keys only (LIVE_KEY_REQUIRED).

Requires account:w.

Responses

200The profile, now IN_REVIEW.

Field	Type	Description
`id`required	string
`status`required	string	DRAFT, then IN_REVIEW (HonkIO staff), then VERIFIED. CHANGES_REQUESTED and DECLINED can be edited and submitted again; REVOKED can only be restored by HonkIO staff. Editing a VERIFIED profile moves it back to DRAFT for another review. One of: DRAFT \| IN_REVIEW \| VERIFIED \| CHANGES_REQUESTED \| DECLINED \| REVOKED
`verified`required	boolean	Whether the business counts as verified. It stays true while the changed details of a verified business are reviewed again (status DRAFT, IN_REVIEW or CHANGES_REQUESTED), and turns false when HonkIO staff decline the changes or revoke the verification.
`verified_at`required	string	When HonkIO staff last verified the business; null when it is not verified. Format: date-time Can be null
`verified_details`required	object \| any	The business as HonkIO staff last verified it. While changed details are reviewed again, the fields below show the changes and this keeps what was verified: toll-free verification reads its business number. Null when the business is not verified.
`business_name`required	string
`doing_business_as`required	string	Can be null
`entity_type`required	string	One of: SOLE_PROPRIETOR \| PRIVATE_PROFIT \| PUBLIC_PROFIT \| NON_PROFIT \| GOVERNMENT
`business_registration_number`required	string	Can be null
`business_address`required	object \| any
`website`required	string	Can be null
`business_description`required	string	Can be null
`contact`required	object
`first_name`required	string	Can be null
`last_name`required	string	Can be null
`email`required	string	Can be null
`phone`required	string	Can be null
`reviewer_note`required	string	What HonkIO staff asked to change, or why they declined the profile. Can be null
`revoked_reason`required	string	Why HonkIO staff revoked the verification. Can be null
`submitted_at`required	string	Format: date-time Can be null
`reviewed_at`required	string	Format: date-time Can be null
`revoked_at`required	string	Format: date-time Can be null
`created_at`required	string	Format: date-time
`updated_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.
403LIVE_KEY_REQUIRED: test keys cannot reach live resources here. Also FORBIDDEN when the key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
404NOT_FOUND: no profile has been saved yet.The standard error body.
409BUSINESS_VERIFICATION_NOT_EDITABLE: only a DRAFT, CHANGES_REQUESTED or DECLINED profile can be submitted.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

const { data, error } = await honkio.businessVerification.submit()
if (error) throw new Error(error.message)
console.log(data.status) // 'IN_REVIEW'

curl -X POST https://api.honkio.ca/v1/business-verification/submit \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

get/v1/account/topup-cap-requests

List your top-up limit requests

Permissionaccount:rNode.js SDKhonkio.topupCapRequests.list()

Requires account:r.

Responses

200The account's top-up limit requests, newest first.

Field	Type	Description
`data[]`required	object[]
`id`required	string
`requested_max_balance_cents`required	integer	The balance cap asked for, in CAD cents; null when not asked for. Can be null
`requested_max_30d_cents`required	integer	The rolling 30-day cap asked for, in CAD cents; null when not asked for. Can be null
`reason`required	string
`status`required	string	One of: PENDING \| APPROVED \| DECLINED
`granted_max_balance_cents`required	integer	Can be null
`granted_max_30d_cents`required	integer	Can be null
`decision_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

const { data, error } = await honkio.topupCapRequests.list()
if (error) throw new Error(error.message)
for (const r of data.data) console.log(r.status, r.decision_note)

curl https://api.honkio.ca/v1/account/topup-cap-requests \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

post/v1/account/topup-cap-requests

Request higher top-up limits

Permissionaccount:wNode.js SDKhonkio.topupCapRequests.create()

Asks HonkIO staff to raise the most your balance may hold (requested_max_balance_cents), the most you may add in any 30 days (requested_max_30d_cents), or both. Each figure you name must be above your current one (GET /v1/accounts/{id}/topup-allowance). Needs a verified business (BUSINESS_VERIFICATION_REQUIRED). One request may be pending at a time; you are emailed when it is decided. Live keys only.

Requires account:w.

Request body

The limits you want and why.

Field	Type	Description
`requested_max_balance_cents`	integer	The balance cap you want, in CAD cents (100 to 99999999). Must be above your current one. Minimum: 100 Maximum: 99999999
`requested_max_30d_cents`	integer	The rolling 30-day top-up cap you want, in CAD cents (100 to 99999999). Must be above your current one. Minimum: 100 Maximum: 99999999
`reason`required	string	What the higher limits are for. Staff decide on this. 10 to 1000 characters. At least 10 characters At most 1000 characters

Responses

201The request, pending review.

Field	Type	Description
`id`required	string
`requested_max_balance_cents`required	integer	The balance cap asked for, in CAD cents; null when not asked for. Can be null
`requested_max_30d_cents`required	integer	The rolling 30-day cap asked for, in CAD cents; null when not asked for. Can be null
`reason`required	string
`status`required	string	One of: PENDING \| APPROVED \| DECLINED
`granted_max_balance_cents`required	integer	Can be null
`granted_max_30d_cents`required	integer	Can be null
`decision_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.
403BUSINESS_VERIFICATION_REQUIRED: verify your business first (PUT /v1/business-verification, then submit it). Also LIVE_KEY_REQUIRED for a test key, or FORBIDDEN when the key lacks the permission this operation requires.The standard error body.
409TOPUP_CAP_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

const { data: request, error } = await honkio.topupCapRequests.create({
  requestedMaxBalanceCents: 100_000, // $1,000.00
  reason: 'Appointment reminders for our three clinics.',
})
if (error) throw new Error(`${error.name}: ${error.message}`)
console.log(request.status) // 'PENDING'

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