HonkIOHonkIO

API reference

Compliance / CASL

CASL consent and opt-out management.

get/v1/compliance/consents

List consent records for account's subscribers

Permissioncompliance:rNode.js SDKhonkio.consents.list()

Requires compliance:r.

Parameters

ParameterTypeDescription
phone_numberquerystring
email_addressquerystring

Filter to the email consents for this address. Email consent is available when the email product launches.

statusquerystring
  • One of: ACTIVE | EXPIRED | REVOKED
pagequeryinteger
  • Minimum: 1
  • Default: 1
limitqueryinteger
  • Minimum: 1
  • Maximum: 100
  • Default: 20

Responses

  • 200A page of consent records, newest first. No total is returned.
    FieldTypeDescription
    data[]requiredobject[]
    idrequiredstring
    accountIdrequiredstring
    channelrequiredstring
    • One of: SMS | EMAIL
    phoneNumberrequiredstring
    • Can be null
    emailAddressrequiredstring
    • Can be null
    consentTyperequiredstring
    • One of: EXPRESS | IMPLIED
    statusrequiredstring
    • One of: ACTIVE | EXPIRED | REVOKED
    sourceDescriptionrequiredstring
    • Can be null
    sourceIprequiredstring
    • Can be null
    sourceUrlrequiredstring
    • Can be null
    relationshipTyperequiredstring
    • Can be null
    expiresAtrequiredstring
    • Format: date-time
    • Can be null
    grantedAtrequiredstring
    • Format: date-time
    revokedAtrequiredstring
    • Format: date-time
    • Can be null
    revokedReasonrequiredstring
    • 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.
  • 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.
  • 501EMAIL_COMING_SOON: email consent is available when the email product launches (sent only for an email_address request).The standard error body.

Example

const { data, error } = await honkio.consents.list({ status: 'ACTIVE', limit: 50 })
if (error) throw new Error(error.message)
console.log(data.data.length)
post/v1/compliance/consents

Record CASL consent for a phone number or email address

Permissioncompliance:wNode.js SDKhonkio.consents.create()

Records express or implied consent per CASL §6-10. Required before sending commercial messages.

Requires compliance:w.

Request body

FieldTypeDescription
phone_numberstring

E.164 phone number of subscriber

email_addressstring

Email address of the subscriber (email channel). Email consent is available when the email product launches.

  • At most 254 characters
consent_typerequiredstring
  • One of: express | implied
source_descriptionstring

How/where consent was obtained (required for express)

  • At most 1000 characters
source_ipstring

IP address of subscriber at time of consent

  • At most 45 characters
source_urlstring

URL where consent was obtained

  • At most 2048 characters
relationship_typestring

Business relationship type (required for implied; e.g. "purchase")

  • At most 100 characters
last_transaction_datestring

Date of last transaction (implied consent: expiry calculated from this)

  • Format: date
expires_atstring

Explicit expiry (ISO 8601 date or date-time) for implied consent. Overrides the expiry derived from last_transaction_date. Not accepted for express consent, which never expires (CASL §10).

Responses

  • 201Default Response
    FieldTypeDescription
    statusstring
    phone_numberstring
    email_addressstring
    expires_atstring

    When this consent lapses (implied only); null for express consent.

    • 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.
  • 422INVALID_PHONE_NUMBER, EMAIL_INVALID_ADDRESS, or VALIDATION_ERROR (provide exactly one of phone_number or email_address; express consent needs source_description and takes no expires_at; implied consent needs relationship_type).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.
  • 501EMAIL_COMING_SOON: email consent is available when the email product launches (sent only for an email_address request).The standard error body.

Example

const { error } = await honkio.consents.create({
  phoneNumber: '+1613XXXXXXX',
  consentType: 'express',
  sourceDescription: 'Website opt-in form',
})
if (error) throw new Error(error.message)
get/v1/compliance/consents/check

Check if a phone number or email address has valid CASL consent

Permissioncompliance:rNode.js SDKhonkio.consents.check()

A consent this check finds past its expiry is marked EXPIRED as a side effect of the check itself, not only by a background job: this call can write, not just read.

Requires compliance:r.

Parameters

ParameterTypeDescription
phone_numberquerystring
email_addressquerystring

Check an email address instead of a phone number. Email consent is available when the email product launches.

Responses

  • 200Whether a send to the phone number or email address would pass the CASL gate. Exactly one of phone_number/email_address is present, matching the subject queried. consentType and reason are camelCase and mutually exclusive.
    FieldTypeDescription
    phone_numberstring
    email_addressstring
    allowedrequiredboolean
    consentTypestring

    Present when allowed.

    • One of: EXPRESS | IMPLIED
    reasonstring

    Present when not allowed.

    • One of: OPT_OUT | NO_CONSENT | CONSENT_EXPIRED
  • 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.
  • 422INVALID_PHONE_NUMBER, EMAIL_INVALID_ADDRESS, or VALIDATION_ERROR (provide exactly one of phone_number or email_address).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.
  • 501EMAIL_COMING_SOON: email consent is available when the email product launches (sent only for an email_address request).The standard error body.

Example

const { data, error } = await honkio.consents.check({ phoneNumber: '+1613XXXXXXX' })
if (error) throw new Error(error.message)
console.log(data.allowed, data.reason)
delete/v1/compliance/consents/{phone}

Revoke CASL consent for a phone number

Permissioncompliance:mdNode.js SDKhonkio.consents.revoke()

Revokes consent records for the given number. Note: opt-outs are separate. Use POST /opt-outs to also block future sends.

Requires compliance:m or compliance:d (any of).

Parameters

ParameterTypeDescription
phonerequiredpathstring

Responses

  • 204Every active consent for the number is revoked.
  • 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 active consent for the number.The standard error body.
  • 422INVALID_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

const { error } = await honkio.consents.revoke({ phoneNumber: '+1613XXXXXXX' })
if (error) throw new Error(error.message)
delete/v1/compliance/consents/email/{address}

Revoke CASL consent for an email address

Permissioncompliance:mdNode.js SDKhonkio.consents.revoke()

Revokes the ACTIVE email consents for the address. Opt-outs and suppressions are separate.

Requires compliance:m or compliance:d (any of).

Parameters

ParameterTypeDescription
addressrequiredpathstring

Responses

  • 204Every active consent for the email address is revoked.
  • 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 active consent for the email address.The standard error body.
  • 422EMAIL_INVALID_ADDRESS.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.
  • 501EMAIL_COMING_SOON: email consent is available when the email product launches.The standard error body.

Example

const { error } = await honkio.consents.revoke({ emailAddress: 'sam@example.com' })
if (error) throw new Error(error.message)
get/v1/compliance/opt-outs

List opt-out records

Permissioncompliance:r

Requires compliance:r.

Parameters

ParameterTypeDescription
phone_numberquerystring
from_numberquerystring
pagequeryinteger
  • Minimum: 1
  • Default: 1
limitqueryinteger
  • Minimum: 1
  • Maximum: 100
  • Default: 20

Responses

  • 200A page of opt-out records, newest first. No total is returned.
    FieldTypeDescription
    data[]requiredobject[]
    idrequiredstring
    accountIdrequiredstring
    channelrequiredstring
    • One of: SMS | EMAIL
    phoneNumberrequiredstring
    • Can be null
    fromNumberrequiredstring

    The sending number the subscriber opted out from (SMS).

    • Can be null
    fromAddressrequiredstring
    • Can be null
    emailAddressrequiredstring
    • Can be null
    keywordUsedrequiredstring

    STOP, UNSUBSCRIBE and so on; null for an opt-out recorded through the API.

    • Can be null
    optedOutAtrequiredstring
    • Format: date-time
    reinstatedAtrequiredstring
    • Format: date-time
    • Can be null
    reinstateKeywordrequiredstring
    • 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.
  • 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/compliance/opt-outs \
  -H "Authorization: Bearer mk_live_YOUR_KEY"
post/v1/compliance/opt-outs

Manually record an opt-out for a phone number

Permissioncompliance:w

Requires compliance:w.

Request body

FieldTypeDescription
phone_numberrequiredstring

Number that is opting out (subscriber)

from_numberrequiredstring

Your sending number they are opting out from

Responses

  • 201Opted out.
    FieldTypeDescription
    statusrequiredstring
    • One of: opted_out
  • 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.
  • 403PHONE_NUMBER_NOT_OWNED: a live key recorded an opt-out from a number the account does not hold.The standard error body.
  • 422INVALID_PHONE_NUMBER or VALIDATION_ERROR.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/compliance/opt-outs \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+1613XXXXXXX",
    "from_number": "+1416XXXXXXX"
  }'