honkio-ca Lists API

openapi: 3.2.0
info:
  title: HonkIO Lists 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: Lists
  description: Allow/deny contact lists assignable to API keys
paths:
  /v1/lists:
    get:
      summary: List all contact lists
      tags:
      - Lists
      description: Requires `lists: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
      security:
      - apiKey: []
      - apiKeyHeader: []
      x-honkio-permission: lists:r
      responses:
        '200':
          description: A page of lists, newest first, each with its entries.
          content:
            application/json:
              schema:
                description: A page of lists, newest first, each with its entries.
                allOf:
                - $ref: '#/components/schemas/PaginationOffset'
                - type: object
                  additionalProperties: true
                  required:
                  - data
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/ContactList'
        '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: getV1Lists
      x-operation-id-source: derived
    post:
      summary: Create a contact list
      tags:
      - Lists
      description: Requires `lists:w`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  maxLength: 100
                description:
                  type: string
                  maxLength: 500
      security:
      - apiKey: []
      - apiKeyHeader: []
      x-honkio-permission: lists:w
      responses:
        '201':
          description: The list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
        '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_LIST_ALREADY_EXISTS: the name is taken.'
          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: postV1Lists
      x-operation-id-source: derived
  /v1/lists/{id}:
    get:
      summary: Get a contact list with entries
      tags:
      - Lists
      description: Requires `lists:r`.
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
      security:
      - apiKey: []
      - apiKeyHeader: []
      x-honkio-permission: lists:r
      responses:
        '200':
          description: The list with its entries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
        '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_LIST_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: getV1ListsById
      x-operation-id-source: derived
    patch:
      summary: Update a contact list
      tags:
      - Lists
      description: Requires `lists:m`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 100
                description:
                  type: string
                  maxLength: 500
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
      security:
      - apiKey: []
      - apiKeyHeader: []
      x-honkio-permission: lists:m
      responses:
        '200':
          description: The updated list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
        '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_LIST_NOT_FOUND.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'CONTACT_LIST_ALREADY_EXISTS: the name is taken.'
          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: patchV1ListsById
      x-operation-id-source: derived
    delete:
      summary: Delete a contact list
      tags:
      - Lists
      description: Requires `lists:d`.
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
      security:
      - apiKey: []
      - apiKeyHeader: []
      x-honkio-permission: lists:d
      responses:
        '204':
          description: Deleted. A key it was assigned to loses that restriction.
        '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_LIST_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: deleteV1ListsById
      x-operation-id-source: derived
  /v1/lists/{id}/entries:
    post:
      summary: Add an entry to a contact list
      tags:
      - Lists
      description: '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`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                phone_number:
                  type: string
                contact_id:
                  type: string
                contact_group_id:
                  type: string
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
      security:
      - apiKey: []
      - apiKeyHeader: []
      x-honkio-permission: lists:m
      responses:
        '201':
          description: The entry.
          content:
            application/json:
              schema:
                description: The entry.
                type: object
                additionalProperties: true
                required:
                - id
                - phone_number
                - contact_id
                - contact_group_id
                - added_at
                properties:
                  id:
                    type: string
                  phone_number:
                    type:
                    - string
                    - 'null'
                  contact_id:
                    type:
                    - string
                    - 'null'
                  contact_group_id:
                    type:
                    - string
                    - 'null'
                  added_at:
                    type: string
                    format: date-time
        '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_LIST_NOT_FOUND, CONTACT_NOT_FOUND or CONTACT_GROUP_NOT_FOUND.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: CONTACT_LIST_ENTRY_EXISTS.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: CONTACT_LIST_ENTRY_INVALID (not exactly one of phone_number, contact_id and contact_group_id), INVALID_PHONE_NUMBER or CONTACT_HAS_NO_PHONE.
          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: postV1ListsByIdEntries
      x-operation-id-source: derived
  /v1/lists/{id}/entries/{entryId}:
    delete:
      summary: Remove an entry from a contact list
      tags:
      - Lists
      description: Requires `lists:m`.
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
      - schema:
          type: string
        in: path
        name: entryId
        required: true
      security:
      - apiKey: []
      - apiKeyHeader: []
      x-honkio-permission: lists:m
      responses:
        '204':
          description: Removed.
        '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_LIST_NOT_FOUND or CONTACT_LIST_ENTRY_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: deleteV1ListsByIdEntriesByEntryId
      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.
    ContactList:
      type: object
      additionalProperties: true
      required:
      - id
      - name
      - description
      - entry_count
      - entries
      - created_at
      - updated_at
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type:
          - string
          - 'null'
        entry_count:
          type: integer
        entries:
          type: array
          items:
            type: object
            additionalProperties: true
            required:
            - id
            - phone_number
            - contact_id
            - contact_group_id
            - contact_name
            - contact_phone
            - group_name
            - added_at
            properties:
              id:
                type: string
              phone_number:
                type:
                - string
                - 'null'
                description: Set on a direct number entry.
              contact_id:
                type:
                - string
                - 'null'
                description: Set on a contact entry.
              contact_group_id:
                type:
                - string
                - 'null'
                description: Set on a group entry, which expands to the group's members at send time.
              contact_name:
                type:
                - string
                - 'null'
              contact_phone:
                type:
                - string
                - 'null'
              group_name:
                type:
                - string
                - 'null'
              added_at:
                type: string
                format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      description: An allow/deny contact list with every entry embedded. Assign it to an API key to restrict who that key may message.
    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.'