honkio-ca Contacts API
Manage contact phone numbers and metadata
Manage contact phone numbers and metadata
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/honkio-ca:honkio-ca-contacts-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: HonkIO Contacts API
description: 'Canadian-focused SMS gateway API.
## Canadian Compliance
- **CASL**: All commercial messages require consent. Use `/v1/compliance/consents` to record.
- **DNCL**: CRTC Do Not Call List checking is coming soon (not yet enforced).
- **PIPEDA / Quebec Law 25**: Data is stored in Canada (ca-central-1). Requests are processed in the United States in transit. Right-to-erasure available.
## Authentication
Provide your API key via `Authorization: Bearer mk_live_...` or `X-API-Key: mk_live_...`.
Test keys never send, never charge and can''t change live data; they work before your first top-up.
## Rate limits
100 requests per second per account. Every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.
## Pagination
Shape follows the route family, not one convention across the API: documented here rather than changed. Messages listings return `{ data, meta: { page, limit, total, pages } }`. Contacts, Contact Groups, Lists and Verify listings return `{ data, total, limit, offset }`. Compliance consent and opt-out listings accept `page`/`limit` and return `{ data }`, with no total. Account transactions use a cursor: pass `before`, get back `has_more`.'
version: 1.0.0
contact:
name: HonkIO Support
email: support@honkio.ca
servers:
- url: https://api.honkio.ca
description: Production
- url: http://localhost:3000
description: Local development
security:
- apiKey: []
- apiKeyHeader: []
tags:
- name: Contacts
description: Manage contact phone numbers and metadata
paths:
/v1/contacts:
get:
summary: List all contacts
tags:
- Contacts
description: Requires `contacts:r`.
parameters:
- schema:
type: integer
minimum: 1
maximum: 100
default: 50
in: query
name: limit
required: false
- schema:
type: integer
minimum: 0
default: 0
in: query
name: offset
required: false
- schema:
type: string
in: query
name: search
required: false
description: Filter by name, phone number or email (case-insensitive, partial match)
security:
- apiKey: []
- apiKeyHeader: []
x-honkio-permission: contacts:r
responses:
'200':
description: A page of contacts, newest first.
content:
application/json:
schema:
description: A page of contacts, newest first.
allOf:
- $ref: '#/components/schemas/PaginationOffset'
- type: object
additionalProperties: true
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/Contact'
'401':
description: Missing, invalid, revoked or expired API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: The account has no balance, or a LIVE key was used before the first top-up.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: The API key lacks the permission this operation requires, or the account is suspended or closed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: 'VALIDATION_ERROR: the request failed validation; details names the fields.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: 'Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Unexpected server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: getV1Contacts
x-operation-id-source: derived
post:
summary: Create a contact
tags:
- Contacts
description: Requires `contacts:w`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required: []
properties:
phone_number:
type: string
description: E.164 phone number. Provide phone_number, email, or both.
email:
type: string
format: email
maxLength: 254
description: Stored lower-cased. Provide phone_number, email, or both.
name:
type: string
maxLength: 200
notes:
type: string
maxLength: 1000
security:
- apiKey: []
- apiKeyHeader: []
x-honkio-permission: contacts:w
responses:
'201':
description: The contact.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'401':
description: Missing, invalid, revoked or expired API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: The account has no balance, or a LIVE key was used before the first top-up.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: The API key lacks the permission this operation requires, or the account is suspended or closed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: 'CONTACT_ALREADY_EXISTS: the phone number or the email is already a contact.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: VALIDATION_ERROR (neither phone_number nor email, or a malformed email) or INVALID_PHONE_NUMBER.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: 'Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Unexpected server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: postV1Contacts
x-operation-id-source: derived
/v1/contacts/{id}:
get:
summary: Get a contact
tags:
- Contacts
description: Requires `contacts:r`.
parameters:
- schema:
type: string
in: path
name: id
required: true
security:
- apiKey: []
- apiKeyHeader: []
x-honkio-permission: contacts:r
responses:
'200':
description: The contact.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'401':
description: Missing, invalid, revoked or expired API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: The account has no balance, or a LIVE key was used before the first top-up.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: The API key lacks the permission this operation requires, or the account is suspended or closed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: CONTACT_NOT_FOUND.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: 'Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Unexpected server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: getV1ContactsById
x-operation-id-source: derived
patch:
summary: Update a contact
tags:
- Contacts
description: Requires `contacts:m`.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
phone_number:
type:
- string
- 'null'
description: E.164, or null to clear (refused with 409 CONTACT_IN_USE while the contact is in a group or list, and with 422 when the contact would be left with neither identifier).
email:
type:
- string
- 'null'
format: email
maxLength: 254
name:
type:
- string
- 'null'
maxLength: 200
notes:
type:
- string
- 'null'
maxLength: 1000
parameters:
- schema:
type: string
in: path
name: id
required: true
security:
- apiKey: []
- apiKeyHeader: []
x-honkio-permission: contacts:m
responses:
'200':
description: The updated contact.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'401':
description: Missing, invalid, revoked or expired API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: The account has no balance, or a LIVE key was used before the first top-up.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: LIVE_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.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: CONTACT_NOT_FOUND.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: CONTACT_ALREADY_EXISTS (the new phone number or email is another contact's) or CONTACT_IN_USE (clearing the phone of a contact that is in a group or a list).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: VALIDATION_ERROR (the contact would be left with neither phone_number nor email) or INVALID_PHONE_NUMBER.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: 'Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Unexpected server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: patchV1ContactsById
x-operation-id-source: derived
delete:
summary: Delete a contact
tags:
- Contacts
description: Requires `contacts:d`.
parameters:
- schema:
type: string
in: path
name: id
required: true
security:
- apiKey: []
- apiKeyHeader: []
x-honkio-permission: contacts:d
responses:
'204':
description: Deleted, with its group memberships and list entries.
'401':
description: Missing, invalid, revoked or expired API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: The account has no balance, or a LIVE key was used before the first top-up.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: LIVE_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.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: CONTACT_NOT_FOUND.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: 'Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Unexpected server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: deleteV1ContactsById
x-operation-id-source: derived
components:
schemas:
PaginationOffset:
type: object
additionalProperties: true
required:
- total
- limit
- offset
properties:
total:
type: integer
description: Total matching records.
limit:
type: integer
offset:
type: integer
description: Offset pagination, returned alongside `data` by the verify, contacts, contact groups and lists listings.
Contact:
type: object
additionalProperties: true
required:
- id
- phone_number
- email
- name
- notes
- created_at
- updated_at
properties:
id:
type: string
phone_number:
type:
- string
- 'null'
description: E.164; null for an email-only contact. Only contacts with a phone can join groups and lists.
email:
type:
- string
- 'null'
description: Lower-cased; null for a phone-only contact. At least one of phone_number and email is set.
name:
type:
- string
- 'null'
notes:
type:
- string
- 'null'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
description: 'A contact: a phone number, an email, or both.'
Error:
type: object
description: Standard error body. The one visible exception is the OAuth 2.1 surface (/oauth/token, /oauth/register, /oauth/revoke), which follows RFC 6749/7591/7009 and answers { error, error_description } instead.
required:
- code
- message
- statusCode
properties:
code:
type: string
description: Machine-readable error code, e.g. VALIDATION_ERROR.
message:
type: string
description: Human-readable message in the request's locale (Accept-Language).
messageEn:
type: string
description: English message, always present alongside message.
messageFr:
type: string
description: French message, always present alongside message.
statusCode:
type: integer
description: The HTTP status, repeated in the body.
details:
description: 'Present on some errors: an AJV validation array, or error-specific structured detail.'
securitySchemes:
apiKey:
type: http
scheme: bearer
bearerFormat: API Key
description: Use `mk_live_...` for production or `mk_test_...` for testing.
apiKeyHeader:
type: apiKey
in: header
name: X-API-Key
description: 'Alternative to the Authorization header: send `mk_live_...` or `mk_test_...` as X-API-Key directly.'