HonkIOHonkIO

API reference

Contact groups

Group contacts and send group broadcasts.

get/v1/contact-groups

List contact groups

Permissioncontact_groups:r

Groups are kept per key mode: a test key lists, creates, changes and broadcasts to test groups only, a live key live ones, and a group of the other mode answers CONTACT_GROUP_NOT_FOUND. A group holds contacts of its own mode only.

Requires contact_groups:r.

Parameters

ParameterTypeDescription
limitqueryinteger
  • Minimum: 1
  • Maximum: 100
  • Default: 50
offsetqueryinteger
  • Minimum: 0
  • Default: 0
searchquerystring

Filter by group name (case-insensitive, partial match)

Responses

  • 200A page of groups, newest first, each with its members.
    FieldTypeDescription
    totalrequiredinteger

    Total matching records.

    limitrequiredinteger
    offsetrequiredinteger
    data[]requiredobject[]
    idrequiredstring
    namerequiredstring
    descriptionrequiredstring
    • Can be null
    member_countrequiredinteger
    members[]requiredobject[]
    idrequiredstring

    The contact id.

    phone_numberrequiredstring
    • Can be null
    namerequiredstring
    • Can be null
    created_atrequiredstring
    • Format: date-time
    updated_atrequiredstring
    • Format: date-time
    livemoderequiredboolean

    false for a record made or read with a test key (a test-mode record), true for a live one.

  • 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.
  • 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/contact-groups \
  -H "Authorization: Bearer mk_live_YOUR_KEY"
post/v1/contact-groups

Create a contact group

Permissioncontact_groups:w

Groups are kept per key mode: a test key lists, creates, changes and broadcasts to test groups only, a live key live ones, and a group of the other mode answers CONTACT_GROUP_NOT_FOUND. A group holds contacts of its own mode only.

Requires contact_groups:w.

Request body

FieldTypeDescription
namerequiredstring
  • At most 100 characters
descriptionstring
  • At most 500 characters

Responses

  • 201The group.
    FieldTypeDescription
    idrequiredstring
    namerequiredstring
    descriptionrequiredstring
    • Can be null
    member_countrequiredinteger
    members[]requiredobject[]
    idrequiredstring

    The contact id.

    phone_numberrequiredstring
    • Can be null
    namerequiredstring
    • Can be null
    created_atrequiredstring
    • Format: date-time
    updated_atrequiredstring
    • Format: date-time
    livemoderequiredboolean

    false for a record made or read with a test key (a test-mode record), true for a live one.

  • 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.
  • 409CONTACT_GROUP_ALREADY_EXISTS: the name is taken.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/contact-groups \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "..."
  }'
get/v1/contact-groups/{id}

Get a contact group with its members

Permissioncontact_groups:r

Requires contact_groups:r.

Parameters

ParameterTypeDescription
idrequiredpathstring

Responses

  • 200The group with its members.
    FieldTypeDescription
    idrequiredstring
    namerequiredstring
    descriptionrequiredstring
    • Can be null
    member_countrequiredinteger
    members[]requiredobject[]
    idrequiredstring

    The contact id.

    phone_numberrequiredstring
    • Can be null
    namerequiredstring
    • Can be null
    created_atrequiredstring
    • Format: date-time
    updated_atrequiredstring
    • Format: date-time
    livemoderequiredboolean

    false for a record made or read with a test key (a test-mode record), true for a live one.

  • 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.
  • 404CONTACT_GROUP_NOT_FOUND.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/contact-groups/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"
patch/v1/contact-groups/{id}

Update a contact group

Permissioncontact_groups:m

Requires contact_groups:m.

Parameters

ParameterTypeDescription
idrequiredpathstring

Request body

FieldTypeDescription
namestring
  • At most 100 characters
descriptionstring
  • At most 500 characters

Responses

  • 200The updated group.
    FieldTypeDescription
    idrequiredstring
    namerequiredstring
    descriptionrequiredstring
    • Can be null
    member_countrequiredinteger
    members[]requiredobject[]
    idrequiredstring

    The contact id.

    phone_numberrequiredstring
    • Can be null
    namerequiredstring
    • Can be null
    created_atrequiredstring
    • Format: date-time
    updated_atrequiredstring
    • Format: date-time
    livemoderequiredboolean

    false for a record made or read with a test key (a test-mode record), true for a live one.

  • 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 when a test key tries to change something a live key's allow/deny list references (contacts, groups and lists are kept per key mode, so a test key only reaches test ones, which no live key uses). Also FORBIDDEN when the key lacks the permission.The standard error body.
  • 404CONTACT_GROUP_NOT_FOUND.The standard error body.
  • 409CONTACT_GROUP_ALREADY_EXISTS: the name is taken.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/contact-groups/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Patients due for a recall visit"
  }'
delete/v1/contact-groups/{id}

Delete a contact group

Permissioncontact_groups:d

Requires contact_groups:d.

Parameters

ParameterTypeDescription
idrequiredpathstring

Responses

  • 204Deleted. Its contacts are kept.
  • 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 when a test key tries to change something a live key's allow/deny list references (contacts, groups and lists are kept per key mode, so a test key only reaches test ones, which no live key uses); KEY_FENCED when the change would loosen the calling key's own allow/deny fence. Also FORBIDDEN when the key lacks the permission.The standard error body.
  • 404CONTACT_GROUP_NOT_FOUND.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/contact-groups/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"
post/v1/contact-groups/{id}/members

Add a member to a contact group

Permissioncontact_groups:m

Provide either contact_id (existing Contact record) or phone_number (will be auto-created if not exists). The contact is of the group's mode: a contact_id of the other mode answers CONTACT_NOT_FOUND, and a phone_number finds or creates a contact of the group's mode.

Requires contact_groups:m.

Parameters

ParameterTypeDescription
idrequiredpathstring

Request body

FieldTypeDescription
contact_idstring
phone_numberstring

Responses

  • 201The member added.
    FieldTypeDescription
    idrequiredstring

    The contact id.

    phone_numberrequiredstring
    namerequiredstring
    • Can be null
    added_atrequiredstring
    • 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 when a test key tries to change something a live key's allow/deny list references (contacts, groups and lists are kept per key mode, so a test key only reaches test ones, which no live key uses); KEY_FENCED when the change would loosen the calling key's own allow/deny fence. Also FORBIDDEN when the key lacks the permission.The standard error body.
  • 404CONTACT_GROUP_NOT_FOUND or CONTACT_NOT_FOUND.The standard error body.
  • 409CONTACT_GROUP_MEMBER_EXISTS.The standard error body.
  • 422VALIDATION_ERROR (neither contact_id nor phone_number), INVALID_PHONE_NUMBER or CONTACT_HAS_NO_PHONE (the contact has no phone number).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/contact-groups/ID/members \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "CONTACT_ID"
  }'
delete/v1/contact-groups/{id}/members/{contactId}

Remove a member from a contact group

Permissioncontact_groups:m

Requires contact_groups:m.

Parameters

ParameterTypeDescription
idrequiredpathstring
contactIdrequiredpathstring

Responses

  • 204Removed from the group. The contact is kept.
  • 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 when a test key tries to change something a live key's allow/deny list references (contacts, groups and lists are kept per key mode, so a test key only reaches test ones, which no live key uses); KEY_FENCED when the change would loosen the calling key's own allow/deny fence. Also FORBIDDEN when the key lacks the permission.The standard error body.
  • 404CONTACT_GROUP_NOT_FOUND or CONTACT_GROUP_MEMBER_NOT_FOUND.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/contact-groups/ID/members/CONTACT_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"
post/v1/contact-groups/{id}/messages

Send an SMS to all members of a contact group

Permissionmessages:w

A test key broadcasts to its own (test) groups and a live key to live ones; a group of the other mode answers CONTACT_GROUP_NOT_FOUND. Always answers 207, whether every member sent or every member failed: check each entry in results rather than the HTTP status. Each result names the member to number. A live broadcast repeated with the same Idempotency-Key within 24 hours answers with the first attempt's stored 207, without running the whole-group checks again or using another daily broadcast slot. A later retry with that key runs the checks again (and can use a slot) but never re-messages a member the first attempt already reached. With scheduled_at (1 minute to 30 days ahead) each member gets a scheduled message, as POST /v1/messages with scheduled_at makes one: status scheduled in results, charged now, every check run again when it is due, and each one can be moved or cancelled on its own (PATCH or DELETE /v1/messages/{id}). The broadcast takes its daily slot now; the sending limits are judged per member when it is due. In place of body, template (a template's id or alias), variables and language (en or fr) send that template's SMS part, rendered once with the same values for every member, as POST /v1/messages does.

Requires messages:w.

Parameters

ParameterTypeDescription
idrequiredpathstring
Idempotency-Keyheaderstring
  • At most 128 characters

Request body

FieldTypeDescription
fromrequiredstring

Sending number (E.164, must be owned by account)

bodystring

Up to 1600 characters and 10 SMS segments. Longer bodies are rejected with 422 MESSAGE_TOO_LONG before any member is messaged. Required unless you send a template; not with one.

  • At most 1600 characters
templatestring

A template's id or alias (/v1/templates). Its part for this channel is rendered and sent in place of your own text. A live key sends the published version, a test key the draft. With an Idempotency-Key, a retry is matched on the request exactly as sent: the template's id and its alias, 1 and "1" as a variable value, and a language left out and the default language named all count as different requests (409 IDEMPOTENCY_KEY_REUSED).

  • At least 1 characters
  • At most 200 characters
variablesobject

Values for the template's variables. A variable with neither a value nor a fallback refuses the send (422 EMAIL_TEMPLATE_VARIABLE_MISSING, details.keys). Only with template.

languagestring

en or fr: the language version to render. A part that language lacks comes from the template's default language. Leave it out for the default language. Only with template.

  • One of: en | fr
skip_consent_checkboolean
scheduled_atstring

Send later: an ISO 8601 date-time with an offset, 1 minute to 30 days ahead.

  • Can be null
expires_atstring

The latest the scheduled send may go out: 1 minute to 24 hours after scheduled_at, and only with it. Without it, scheduled_at plus 24 hours. A send that cannot go out by then fails with SCHEDULED_SEND_EXPIRED and is refunded. The same for every member.

  • Can be null

Responses

  • 207Always 207: check each result, not the status. A live broadcast repeated with the same Idempotency-Key within 24 hours answers with the first attempt's stored result.
    FieldTypeDescription
    group_idrequiredstring
    sent_torequiredinteger

    Members not failed.

    failedrequiredinteger
    results[]requiredobject[]
    torequiredstring

    The member's number.

    statusrequiredstring

    Lowercase: the message status (queued, sent, delivered and so on), or failed.

    message_idstring

    Absent when the member failed before a message was created.

    errorstring

    An error code: why the member failed, or the message's own error_code.

    estimated_completion_atstring

    An estimate of when the carrier will have sent the last member, from the sending number's queue. Null in test mode. Absent from a stored replay of a broadcast sent before it existed.

    • Format: date-time
    • Can be null
  • 401Missing, invalid, revoked or expired API key.The standard error body.
  • 402INSUFFICIENT_BALANCE: the balance cannot cover the send. RENT_OWED: rent is owed on a number released while suspended; top up to pay it first. Also PAYMENT_REQUIRED when a LIVE key is used before the first top-up.The standard error body.
  • 403FORBIDDEN (skip_consent_check on a live key, or the key lacks messages:w), ACCOUNT_NOT_VERIFIED, SENDING_PAUSED, or TOLL_FREE_NOT_VERIFIED (a toll-free from number without an approved toll-free verification; test keys too). A live member without a confirmed double opt-in fails alone in the results with DOUBLE_OPT_IN_REQUIRED.The standard error body.
  • 404CONTACT_GROUP_NOT_FOUND.The standard error body.
  • 422VALIDATION_ERROR, BROADCAST_TOO_LARGE, MESSAGE_TOO_LONG or LINK_SHORTENER_BLOCKED.The standard error body.
  • 429BROADCAST_LIMIT_REACHED, DAILY_LIMIT_REACHED, FANOUT_LIMIT_REACHED, NUMBER_QUEUE_FULL (the broadcast's message segments would overfill the sending number's carrier queue; Retry-After is set when waiting would make room) or RECIPIENT_RATE_LIMITED, or RATE_LIMITED at 100 requests per second. SCHEDULED_LIMIT_REACHED (with scheduled_at): one scheduled message per member would take the account past 10,000 scheduled live messages, or 1,000 scheduled test messages; the broadcast is refused whole, before any member is scheduled or charged (details carry mode, limit, scheduled and requested).The standard error body.
  • 500Unexpected server error.The standard error body.

Example

cURL
curl -X POST https://api.honkio.ca/v1/contact-groups/ID/messages \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+1416XXXXXXX"
  }'