HonkIOHonkIO

API reference

Lists

Allow/deny contact lists assignable to API keys.

get/v1/lists

List all contact lists

Permissionlists:r

Requires lists:r.

Parameters

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

Responses

  • 200A page of lists, newest first, each with its entries.
    FieldTypeDescription
    totalrequiredinteger

    Total matching records.

    limitrequiredinteger
    offsetrequiredinteger
    data[]requiredobject[]
    idrequiredstring
    namerequiredstring
    descriptionrequiredstring
    • Can be null
    entry_countrequiredinteger
    entries[]requiredobject[]
    idrequiredstring
    phone_numberrequiredstring

    Set on a direct number entry.

    • Can be null
    contact_idrequiredstring

    Set on a contact entry.

    • Can be null
    contact_group_idrequiredstring

    Set on a group entry, which expands to the group's members at send time.

    • Can be null
    contact_namerequiredstring
    • Can be null
    contact_phonerequiredstring
    • Can be null
    group_namerequiredstring
    • Can be null
    added_atrequiredstring
    • Format: date-time
    created_atrequiredstring
    • Format: date-time
    updated_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.
  • 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/lists \
  -H "Authorization: Bearer mk_live_YOUR_KEY"
post/v1/lists

Create a contact list

Permissionlists:w

Requires lists:w.

Request body

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

Responses

  • 201The list.
    FieldTypeDescription
    idrequiredstring
    namerequiredstring
    descriptionrequiredstring
    • Can be null
    entry_countrequiredinteger
    entries[]requiredobject[]
    idrequiredstring
    phone_numberrequiredstring

    Set on a direct number entry.

    • Can be null
    contact_idrequiredstring

    Set on a contact entry.

    • Can be null
    contact_group_idrequiredstring

    Set on a group entry, which expands to the group's members at send time.

    • Can be null
    contact_namerequiredstring
    • Can be null
    contact_phonerequiredstring
    • Can be null
    group_namerequiredstring
    • Can be null
    added_atrequiredstring
    • Format: date-time
    created_atrequiredstring
    • Format: date-time
    updated_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.
  • 403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
  • 409CONTACT_LIST_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/lists \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "..."
  }'
get/v1/lists/{id}

Get a contact list with entries

Permissionlists:r

Requires lists:r.

Parameters

ParameterTypeDescription
idrequiredpathstring

Responses

  • 200The list with its entries.
    FieldTypeDescription
    idrequiredstring
    namerequiredstring
    descriptionrequiredstring
    • Can be null
    entry_countrequiredinteger
    entries[]requiredobject[]
    idrequiredstring
    phone_numberrequiredstring

    Set on a direct number entry.

    • Can be null
    contact_idrequiredstring

    Set on a contact entry.

    • Can be null
    contact_group_idrequiredstring

    Set on a group entry, which expands to the group's members at send time.

    • Can be null
    contact_namerequiredstring
    • Can be null
    contact_phonerequiredstring
    • Can be null
    group_namerequiredstring
    • Can be null
    added_atrequiredstring
    • Format: date-time
    created_atrequiredstring
    • Format: date-time
    updated_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.
  • 403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
  • 404CONTACT_LIST_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/lists/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"
patch/v1/lists/{id}

Update a contact list

Permissionlists:m

Requires lists:m.

Parameters

ParameterTypeDescription
idrequiredpathstring

Request body

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

Responses

  • 200The updated list.
    FieldTypeDescription
    idrequiredstring
    namerequiredstring
    descriptionrequiredstring
    • Can be null
    entry_countrequiredinteger
    entries[]requiredobject[]
    idrequiredstring
    phone_numberrequiredstring

    Set on a direct number entry.

    • Can be null
    contact_idrequiredstring

    Set on a contact entry.

    • Can be null
    contact_group_idrequiredstring

    Set on a group entry, which expands to the group's members at send time.

    • Can be null
    contact_namerequiredstring
    • Can be null
    contact_phonerequiredstring
    • Can be null
    group_namerequiredstring
    • Can be null
    added_atrequiredstring
    • Format: date-time
    created_atrequiredstring
    • Format: date-time
    updated_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. Also FORBIDDEN when the key lacks the permission.The standard error body.
  • 404CONTACT_LIST_NOT_FOUND.The standard error body.
  • 409CONTACT_LIST_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/lists/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Numbers that asked not to be texted"
  }'
delete/v1/lists/{id}

Delete a contact list

Permissionlists:d

Requires lists:d.

Parameters

ParameterTypeDescription
idrequiredpathstring

Responses

  • 204Deleted. A key it was assigned to loses that restriction.
  • 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_LIST_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/lists/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"
post/v1/lists/{id}/entries

Add an entry to a contact list

Permissionlists:m

Provide exactly one of: phone_number (direct E.164), contact_id (Contact record), or contact_group_id (ContactGroup: expands to all members at send time).

Requires lists:m.

Parameters

ParameterTypeDescription
idrequiredpathstring

Request body

FieldTypeDescription
phone_numberstring
contact_idstring
contact_group_idstring

Responses

  • 201The entry.
    FieldTypeDescription
    idrequiredstring
    phone_numberrequiredstring
    • Can be null
    contact_idrequiredstring
    • Can be null
    contact_group_idrequiredstring
    • 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; 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_LIST_NOT_FOUND, CONTACT_NOT_FOUND or CONTACT_GROUP_NOT_FOUND.The standard error body.
  • 409CONTACT_LIST_ENTRY_EXISTS.The standard error body.
  • 422CONTACT_LIST_ENTRY_INVALID (not exactly one of phone_number, contact_id and contact_group_id), INVALID_PHONE_NUMBER or CONTACT_HAS_NO_PHONE.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/lists/ID/entries \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+1613XXXXXXX"
  }'
delete/v1/lists/{id}/entries/{entryId}

Remove an entry from a contact list

Permissionlists:m

Requires lists:m.

Parameters

ParameterTypeDescription
idrequiredpathstring
entryIdrequiredpathstring

Responses

  • 204Removed.
  • 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_LIST_NOT_FOUND or CONTACT_LIST_ENTRY_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/lists/ID/entries/ENTRY_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"