API reference

Contact groups

Group contacts and send group broadcasts.

get/v1/contact-groups

List contact groups

Permissioncontact_groups:r

Requires contact_groups:r.

Parameters

Parameter	Type	Description
`limit`query	integer	Minimum: 1 Maximum: 100 Default: 50
`offset`query	integer	Minimum: 0 Default: 0
`search`query	string	Filter by group name (case-insensitive, partial match)

Responses

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

Field	Type	Description
`total`required	integer	Total matching records.
`limit`required	integer
`offset`required	integer
`data[]`required	object[]
`id`required	string
`name`required	string
`description`required	string	Can be null
`member_count`required	integer
`members[]`required	object[]
`id`required	string	The contact id.
`phone_number`required	string	Can be null
`name`required	string	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.
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

Requires contact_groups:w.

Request body

Field	Type	Description
`name`required	string	At most 100 characters
`description`	string	At most 500 characters

Responses

201The group.

Field	Type	Description
`id`required	string
`name`required	string
`description`required	string	Can be null
`member_count`required	integer
`members[]`required	object[]
`id`required	string	The contact id.
`phone_number`required	string	Can be null
`name`required	string	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.
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

Parameter	Type	Description
`id`requiredpath	string

Responses

200The group with its members.

Field	Type	Description
`id`required	string
`name`required	string
`description`required	string	Can be null
`member_count`required	integer
`members[]`required	object[]
`id`required	string	The contact id.
`phone_number`required	string	Can be null
`name`required	string	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.
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

Parameter	Type	Description
`id`requiredpath	string

Request body

Field	Type	Description
`name`	string	At most 100 characters
`description`	string	At most 500 characters

Responses

200The updated group.

Field	Type	Description
`id`required	string
`name`required	string
`description`required	string	Can be null
`member_count`required	integer
`members[]`required	object[]
`id`required	string	The contact id.
`phone_number`required	string	Can be null
`name`required	string	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 when a test key tries to change something a live key's allow/deny list references. 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

Parameter	Type	Description
`id`requiredpath	string

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; 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).

Requires contact_groups:m.

Parameters

Parameter	Type	Description
`id`requiredpath	string

Request body

Field	Type	Description
`contact_id`	string
`phone_number`	string

Responses

201The member added.
Field Type Description
idrequired string
The contact id.
phone_numberrequired string
namerequired string
Can be null
added_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.
403LIVE_KEY_REQUIRED when a test key tries to change something a live key's allow/deny list references; 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

Parameter	Type	Description
`id`requiredpath	string
`contactId`requiredpath	string

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; 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

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.

Requires messages:w.

Parameters

Parameter	Type	Description
`id`requiredpath	string
`Idempotency-Key`header	string	At most 128 characters

Request body

Field	Type	Description
`from`required	string	Sending number (E.164, must be owned by account)
`body`required	string	Up to 1600 characters and 10 SMS parts. Longer bodies are rejected with 422 MESSAGE_TOO_LONG before any member is messaged. At most 1600 characters
`skip_consent_check`	boolean

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.

Field	Type	Description
`group_id`required	string
`sent_to`required	integer	Members not failed.
`failed`required	integer
`results[]`required	object[]
`to`required	string	The member's number.
`status`required	string	Lowercase: the message status (queued, sent, delivered and so on), or failed.
`message_id`	string	Absent when the member failed before a message was created.
`error`	string	An error code: why the member failed, or the message's own error_code.

401Missing, invalid, revoked or expired API key.The standard error body.
402INSUFFICIENT_BALANCE: the balance cannot cover the send. 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 or SENDING_PAUSED.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 or RECIPIENT_RATE_LIMITED, or RATE_LIMITED at 100 requests per second.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",
    "body": "Hello from HonkIO!"
  }'