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()

Consents and opt-outs are kept per key mode: a test key records, reads and changes its own (test) records, which only test sends are checked against, and a live key the live ones.

Requires compliance:r.

Parameters

Parameter	Type	Description
`phone_number`query	string
`email_address`query	string	Filter to the email consents for this address. Email consent is available when the email product launches.
`status`query	string	One of: ACTIVE \| EXPIRED \| REVOKED
`consent_batch_id`query	string	Only the consents recorded by this bulk upload. At most 64 characters
`page`query	integer	Minimum: 1 Default: 1
`limit`query	integer	Minimum: 1 Maximum: 100 Default: 20

Responses

200A page of consent records, newest first. No total is returned.

Field	Type	Description
`data[]`required	object[]
`id`required	string
`accountId`required	string
`channel`required	string	One of: SMS \| EMAIL
`phoneNumber`required	string	Can be null
`emailAddress`required	string	Can be null
`consentType`required	string	One of: EXPRESS \| IMPLIED
`status`required	string	One of: ACTIVE \| EXPIRED \| REVOKED
`sourceDescription`required	string	Can be null
`sourceIp`required	string	Can be null
`sourceUrl`required	string	Can be null
`relationshipType`required	string	Can be null
`expiresAt`required	string	Format: date-time Can be null
`grantedAt`required	string	Format: date-time
`revokedAt`required	string	Format: date-time Can be null
`revokedReason`required	string	Can be null
`doubleOptInConfirmedAt`required	string	When the subscriber last confirmed double opt-in by replying YES to an opt-in confirmation from one of your toll-free numbers. A toll-free send needs a confirmation from its own sending number: see GET /v1/compliance/opt-in-confirmations. Format: date-time Can be null
`doubleOptInConfirmationId`required	string	The opt-in confirmation (oic_…) they answered. Can be null
`consentBatchId`required	string	The bulk upload (cb_…) that recorded this consent; null for one recorded on its own. Can be null
`mode`required	string	The mode of the key that recorded it. A test key sees TEST records only, a live key LIVE ones. One of: LIVE \| TEST
`livemode`required	boolean	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.
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)

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

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. Every SMS needs consent on file for its recipient, transactional or commercial (a verification code through the Verify API needs none); email needs it only for commercial sends. Refused with 409 CONSENT_REVOKED_BY_REVIEW when HonkIO revoked this recipient's consent on review of a bulk upload: such consent cannot be recorded again unless HonkIO lifts the block. Consents and opt-outs are kept per key mode: a test key records, reads and changes its own (test) records, which only test sends are checked against, and a live key the live ones.

Requires compliance:w.

Request body

Field	Type	Description
`phone_number`	string	E.164 phone number of subscriber
`email_address`	string	Email address of the subscriber (email channel). Email consent is available when the email product launches. At most 254 characters
`consent_type`required	string	One of: express \| implied
`source_description`	string	How/where consent was obtained (required for express) At most 1000 characters
`source_ip`	string	IP address of subscriber at time of consent At most 45 characters
`source_url`	string	URL where consent was obtained At most 2048 characters
`relationship_type`	string	Business relationship type (required for implied; e.g. "purchase", "inquiry", "member"). It sets how long implied consent lasts (CASL s. 10(10), 10(13)): 2 years for a purchase, lease, contract, business opportunity, donation, volunteer work or membership; 6 months for an inquiry or application, and for any type that names neither. At most 100 characters
`last_transaction_date`	string	Date of last transaction (implied consent: the 2-year or 6-month expiry runs from this; today when absent) Format: date
`expires_at`	string	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

Field	Type	Description
`status`	string
`phone_number`	string
`email_address`	string
`expires_at`	string	When this consent lapses (implied only); null for express consent. Can be null
`livemode`	boolean	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.
409CONSENT_REVOKED_BY_REVIEW: HonkIO revoked this recipient's consent on review of a bulk upload, so it cannot be recorded again unless HonkIO lifts the block.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)

curl -X POST https://api.honkio.ca/v1/compliance/consents \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+1613XXXXXXX",
    "consent_type": "express",
    "source_description": "Website opt-in form"
  }'

post/v1/compliance/consents/batch

Record CASL consent for up to 5,000 phone numbers

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

Each row is defaults with the row's own fields on top. Every row gets its own outcome: recorded, invalid, duplicate_in_file (the number appeared on an earlier row), opted_out (the number has opted out; never re-consented by an upload), revoked_by_review (HonkIO revoked the number's consent on review of an earlier upload; it cannot be recorded again unless HonkIO lifts the block) or already_recorded (an active consent at least as strong exists, so re-sending a file records nothing twice). The upload is kept as a consent batch (GET /v1/compliance/consent-batches). SMS only. A test key's upload records test consents, judged against its own (test) opt-outs and consents.

Requires compliance:w.

Request body

Field	Type	Description
`defaults`required	object	The fields every row starts from.
`consent_type`required	string	One of: express \| implied
`source_description`	string	At most 1000 characters
`source_ip`	string	At most 45 characters
`source_url`	string	At most 2048 characters
`relationship_type`	string	At most 100 characters
`last_transaction_date`	string	At most 40 characters
`expires_at`	string	At most 40 characters Can be null
`rows[]`required	object[]	1 to 5,000 rows; each row's fields override the defaults.
`phone_number`required	string	At most 64 characters
`consent_type`	string	express or implied; any other value makes that row invalid. At most 20 characters
`source_description`	string	At most 1000 characters
`source_ip`	string	At most 45 characters
`source_url`	string	At most 2048 characters
`relationship_type`	string	At most 100 characters
`last_transaction_date`	string	At most 40 characters
`expires_at`	string	At most 40 characters Can be null
`file_name`	string	The uploaded file's name, kept on the batch. At most 255 characters
`attested`	boolean	The uploader confirms these people gave this consent or have this relationship. Recorded on the batch.

Responses

200Every row's outcome, in the order sent, and the counts. Partial success is normal: only a request that is wrong as a whole is refused.

Field	Type	Description
`batch_id`required	string	cb_…
`livemode`required	boolean	false for a record made or read with a test key (a test-mode record), true for a live one.
`counts`required	object
`rows`required	integer
`recorded`required	integer
`express`required	integer
`implied`required	integer
`already_recorded`required	integer
`opted_out`required	integer
`revoked_by_review`required	integer
`duplicate_in_file`required	integer
`invalid`required	integer
`results[]`required	object[]
`row`required	integer	Index into rows.
`phone_number`required	string	E.164, or the input as sent when it did not parse.
`status`required	string	One of: recorded \| invalid \| duplicate_in_file \| opted_out \| revoked_by_review \| already_recorded
`reason`	string	Present on invalid rows (the field and what is wrong with it) and on revoked_by_review rows.
`consent_type`	string	Present on recorded rows. One of: express \| implied
`expires_at`	string	Present on recorded rows; null for express. 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: rows empty or over 5,000, or defaults wrong in themselves (unknown consent_type, an unparseable date, expires_at with express).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.consents.recordBatch({
  defaults: { consentType: 'implied', relationshipType: 'volunteer', lastTransactionDate: '2026-05-01' },
  rows: [{ phoneNumber: '+1613XXXXXXX' }],
  fileName: 'volunteers.csv',
})
if (error) throw new Error(error.message)
console.log(data.counts)

curl -X POST https://api.honkio.ca/v1/compliance/consents/batch \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaults": {
      "consent_type": "express"
    },
    "rows": [
      {
        "phone_number": "+1613XXXXXXX"
      }
    ]
  }'

get/v1/compliance/consent-batches

List bulk consent uploads

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

Requires compliance:r.

Parameters

Parameter	Type	Description
`page`query	integer	Minimum: 1 Default: 1
`limit`query	integer	Minimum: 1 Maximum: 100 Default: 20

Responses

200A page of bulk uploads, newest first. No total is returned.

Field	Type	Description
`data[]`required	object[]
`id`required	string	cb_…
`livemode`required	boolean	false for a record made or read with a test key (a test-mode record), true for a live one.
`source`required	string	Sent through the API, or uploaded on the dashboard. One of: api \| dashboard
`file_name`required	string	The file name the uploader gave, if any. Can be null
`attested`required	boolean	Whether the uploader confirmed these people gave this consent or have this relationship.
`counts`required	object
`rows`required	integer
`recorded`required	integer
`express`required	integer
`implied`required	integer
`already_recorded`required	integer
`opted_out`required	integer
`revoked_by_review`required	integer
`duplicate_in_file`required	integer
`invalid`required	integer
`revoked_at`required	string	Format: date-time Can be null
`created_at`required	string	Format: date-time
`defaults`	object	The defaults the upload was sent with, as sent. Only on GET /v1/compliance/consent-batches/{id}.
`consent_type`required	string	One of: express \| implied
`source_description`	string
`source_ip`	string
`source_url`	string
`relationship_type`	string
`last_transaction_date`	string
`expires_at`	string	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

const { data, error } = await honkio.consentBatches.list()
if (error) throw new Error(error.message)
console.log(data.data.length)

curl https://api.honkio.ca/v1/compliance/consent-batches \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

get/v1/compliance/consent-batches/{id}

Get a bulk consent upload

Permissioncompliance:rNode.js SDKhonkio.consentBatches.get()

Requires compliance:r.

Parameters

Parameter	Type	Description
`id`requiredpath	string	At most 64 characters

Responses

200The upload, with the defaults it was sent with.

Field	Type	Description
`id`required	string	cb_…
`livemode`required	boolean	false for a record made or read with a test key (a test-mode record), true for a live one.
`source`required	string	Sent through the API, or uploaded on the dashboard. One of: api \| dashboard
`file_name`required	string	The file name the uploader gave, if any. Can be null
`attested`required	boolean	Whether the uploader confirmed these people gave this consent or have this relationship.
`counts`required	object
`rows`required	integer
`recorded`required	integer
`express`required	integer
`implied`required	integer
`already_recorded`required	integer
`opted_out`required	integer
`revoked_by_review`required	integer
`duplicate_in_file`required	integer
`invalid`required	integer
`revoked_at`required	string	Format: date-time Can be null
`created_at`required	string	Format: date-time
`defaults`	object	The defaults the upload was sent with, as sent. Only on GET /v1/compliance/consent-batches/{id}.
`consent_type`required	string	One of: express \| implied
`source_description`	string
`source_ip`	string
`source_url`	string
`relationship_type`	string
`last_transaction_date`	string
`expires_at`	string	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.
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.consentBatches.get('BATCH_ID')
if (error) throw new Error(error.message)
console.log(data.counts)

curl https://api.honkio.ca/v1/compliance/consent-batches/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

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. It answers for the calling key's mode: a test key checks the test records a test send would be checked against, a live key the live ones.

Requires compliance:r.

Parameters

Parameter	Type	Description
`phone_number`query	string
`email_address`query	string	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.

Field	Type	Description
`phone_number`	string
`email_address`	string
`allowed`required	boolean
`consentType`	string	Present when allowed. One of: EXPRESS \| IMPLIED
`reason`	string	Present when not allowed. One of: OPT_OUT \| NO_CONSENT \| CONSENT_EXPIRED
`livemode`	boolean	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.
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)

curl https://api.honkio.ca/v1/compliance/consents/check \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

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. Every SMS to it is then refused with NO_CONSENT until consent is recorded again. Opt-outs are separate: an opt-out (POST /opt-outs) blocks sends even when consent is on file, and only the recipient can lift it. A test key revokes test consents only, and a live key live ones.

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

Parameters

Parameter	Type	Description
`phone`requiredpath	string

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)

curl -X DELETE https://api.honkio.ca/v1/compliance/consents/PHONE \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

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. Commercial email to it is then refused with EMAIL_NO_CONSENT until consent is recorded again; transactional email is unaffected. Opt-outs and suppressions are separate.

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

Parameters

Parameter	Type	Description
`address`requiredpath	string

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)

curl -X DELETE https://api.honkio.ca/v1/compliance/consents/email/ADDRESS \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

get/v1/compliance/opt-outs

List opt-out records

Permissioncompliance:r

Consents and opt-outs are kept per key mode: a test key records, reads and changes its own (test) records, which only test sends are checked against, and a live key the live ones.

Requires compliance:r.

Parameters

Parameter	Type	Description
`phone_number`query	string
`from_number`query	string
`page`query	integer	Minimum: 1 Default: 1
`limit`query	integer	Minimum: 1 Maximum: 100 Default: 20

Responses

200A page of opt-out records, newest first. No total is returned.

Field	Type	Description
`data[]`required	object[]
`id`required	string
`accountId`required	string
`channel`required	string	One of: SMS \| EMAIL
`phoneNumber`required	string	Can be null
`fromNumber`required	string	The sending number the subscriber opted out from (SMS). Can be null
`fromAddress`required	string	Can be null
`emailAddress`required	string	Can be null
`keywordUsed`required	string	STOP, UNSUBSCRIBE and so on; null for an opt-out recorded through the API. Can be null
`optedOutAt`required	string	Format: date-time
`reinstatedAt`required	string	Format: date-time Can be null
`reinstateKeyword`required	string	Can be null
`mode`required	string	LIVE for a STOP to one of your numbers, an unsubscribe from a live email, or one a live key recorded; TEST for one a test key recorded or a test email produced. A test key sees TEST records only, a live key LIVE ones. One of: LIVE \| TEST
`livemode`required	boolean	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/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

Consents and opt-outs are kept per key mode: a test key records, reads and changes its own (test) records, which only test sends are checked against, and a live key the live ones.

Requires compliance:w.

Request body

Field	Type	Description
`phone_number`required	string	Number that is opting out (subscriber)
`from_number`required	string	Your sending number they are opting out from

Responses

201Opted out.
Field Type Description
statusrequired string
One of: opted_out
livemoderequired boolean
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.
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.

Field	Type	Description
`status`required	string	One of: opted_out
`livemode`required	boolean	false for a record made or read with a test key (a test-mode record), true for a live one.

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"
  }'

get/v1/compliance/opt-in-confirmations

List double opt-in confirmations

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

Newest first. A pending confirmation past its 7 days is reported EXPIRED. Confirmations are live only, so a test key lists none.

Requires compliance:r.

Parameters

Parameter	Type	Description
`to`query	string	Only confirmations sent to this recipient (E.164).
`status`query	string	One of: PENDING \| CONFIRMED \| EXPIRED \| DECLINED
`page`query	integer	Minimum: 1 Default: 1
`limit`query	integer	Minimum: 1 Maximum: 100 Default: 20

Responses

200A page of confirmations, newest first. No total is returned. Empty for a test key.

Field	Type	Description
`data[]`required	object[]
`id`required	string	oic_…
`status`required	string	PENDING until the recipient replies YES (CONFIRMED), it lapses after 7 days or is replaced by a newer one (EXPIRED), or the recipient texts STOP (DECLINED). One of: PENDING \| CONFIRMED \| EXPIRED \| DECLINED
`from`required	string	The toll-free number it was sent from. Can be null
`to`required	string	The recipient.
`brand_name`required	string
`language`required	string	One of: en \| fr
`message_id`required	string	The confirmation text, as a message (GET /v1/messages/{id}). Can be null
`expires_at`required	string	Format: date-time
`confirmed_at`required	string	Format: date-time Can be null
`reply_message_id`required	string	The recipient's YES, as an inbound message. 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.
422INVALID_PHONE_NUMBER (the to filter) 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

const { data, error } = await honkio.optInConfirmations.list({ to: '+1613XXXXXXX' })
if (error) throw new Error(error.message)
for (const c of data.data) console.log(c.id, c.status)

curl https://api.honkio.ca/v1/compliance/opt-in-confirmations \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

post/v1/compliance/opt-in-confirmations

Send a double opt-in confirmation from a toll-free number

Permissioncompliance:wNode.js SDKhonkio.optInConfirmations.send()

Texts the recipient a fixed confirmation from your verified toll-free number: "{brand_name}: reply YES to confirm you want text messages from us. Msg & data rates may apply. Reply STOP to opt out." (with language: "fr": "{brand_name} : répondez OUI pour confirmer que vous voulez recevoir nos textos. Des frais de messagerie et de données peuvent s’appliquer. Répondez ARRET pour vous désabonner.").

Canadian toll-free messaging needs double opt-in, per sending number: until the recipient replies YES, Y, OUI or O to this number, sends to them from it are refused with 451 DOUBLE_OPT_IN_REQUIRED (each of your toll-free numbers asks for its own). The reply confirms the confirmation, records the double opt-in for this number, and fires consent.double_opt_in_confirmed. A STOP to this number withdraws it. Verification codes (POST /v1/verify) are exempt.

The recipient must already have an active consent (the first opt-in). The confirmation is billed as a normal message and expires after 7 days. Sending another from the same number replaces the pending one; at most 3 can be sent to one recipient in 24 hours, from any of your numbers. Live keys only.

Requires compliance:w.

Request body

Field	Type	Description
`from`required	string	Your toll-free number (E.164) with an approved toll-free verification.
`to`required	string	The recipient (E.164, Canadian), who must already have an active consent.
`brand_name`required	string	The name the recipient knows you by, shown at the start of the text. Plain text: letters, numbers, spaces and . , ' & ! -, not a link. At least 1 characters At most 64 characters
`language`	string	The language of the confirmation text. One of: en \| fr Default: en

Responses

201Sent: the confirmation, PENDING until the recipient replies YES.

Field	Type	Description
`id`required	string	oic_…
`status`required	string	PENDING until the recipient replies YES (CONFIRMED), it lapses after 7 days or is replaced by a newer one (EXPIRED), or the recipient texts STOP (DECLINED). One of: PENDING \| CONFIRMED \| EXPIRED \| DECLINED
`from`required	string	The toll-free number it was sent from. Can be null
`to`required	string	The recipient.
`brand_name`required	string
`language`required	string	One of: en \| fr
`message_id`required	string	The confirmation text, as a message (GET /v1/messages/{id}). Can be null
`expires_at`required	string	Format: date-time
`confirmed_at`required	string	Format: date-time Can be null
`reply_message_id`required	string	The recipient's YES, as an inbound message. Can be null
`created_at`required	string	Format: date-time

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.
403TOLL_FREE_NOT_VERIFIED (from has no approved toll-free verification), ACCOUNT_NOT_VERIFIED, LIVE_KEY_REQUIRED (test keys cannot send one), ALLOW_LIST_BLOCKED, DENY_LIST_BLOCKED or SENDING_PAUSED. Also FORBIDDEN when the key lacks compliance:w.The standard error body.
409PHONE_NUMBER_SUSPENDED: the from number is suspended for unpaid rent.The standard error body.
422INVALID_PHONE_NUMBER, NOT_A_TOLL_FREE_NUMBER (from is not one of your toll-free numbers), VALIDATION_ERROR (brand_name must be plain text, not a link), NON_CANADIAN_NUMBER, RESERVED_DESTINATION, UNDELIVERABLE_NUMBER or NOT_A_MOBILE_NUMBER. A refused send costs nothing.The standard error body.
429OPT_IN_CONFIRMATION_LIMIT (3 to one recipient in 24 hours), DAILY_LIMIT_REACHED, FANOUT_LIMIT_REACHED, NUMBER_RATE_LIMITED or RECIPIENT_RATE_LIMITED (Retry-After set on the two rate limits), or RATE_LIMITED at 100 requests per second.The standard error body.
451The recipient has no first opt-in: NO_CONSENT, CONSENT_EXPIRED or OPT_OUT_BLOCKED.The standard error body.
500Unexpected server error.The standard error body.
502CARRIER_ERROR: the carrier refused the send. Any charge is refunded and no confirmation is kept.The standard error body.
503CARRIER_UNAVAILABLE, CARRIER_THROTTLED or CARRIER_TIMEOUT: see POST /v1/messages. No confirmation is kept; send again.The standard error body.

Example

const { data: confirmation, error } = await honkio.optInConfirmations.send({
  from: '+1833XXXXXXX', // your verified toll-free number
  to: '+1613XXXXXXX',
  brandName: 'Acme Clinics',
})
if (error) throw new Error(`${error.name}: ${error.message}`)
console.log(confirmation.id, confirmation.status) // 'PENDING' until they reply YES

curl -X POST https://api.honkio.ca/v1/compliance/opt-in-confirmations \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+1416XXXXXXX",
    "to": "+1613XXXXXXX",
    "brand_name": "..."
  }'