honkio-ca Compliance / PIPEDA API

openapi: 3.2.0
info:
  title: HonkIO Compliance / PIPEDA 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: Compliance / PIPEDA
  description: Privacy compliance and right to erasure
paths:
  /v1/compliance/erasure:
    post:
      summary: 'Right to erasure: delete all personal data for a phone number'
      tags:
      - Compliance / PIPEDA
      description: 'Complies with PIPEDA and Quebec Law 25 right to erasure. Scrubs message bodies and event payloads for the number, and deletes its consent records, verifications, contacts, and webhook dead letters. Deletes its contact-list entries too, except on a DENY list: that entry is kept so the number stays blocked. Opt-out records are kept: CASL requires proof an opt-out was honoured, so this call never deletes one. So is a block HonkIO placed on the number by revoking the upload it came from: erasure does not make its consent recordable again.


        Requires `compliance:d`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - phone_number
              properties:
                phone_number:
                  type: string
                reason:
                  type: string
                  maxLength: 1000
                  description: Reason for erasure request (for audit log)
      parameters:
      - schema:
          type: string
        in: header
        name: x-step-up-token
        required: false
        description: A token from POST /v1/auth/step-up with the compliance:d scope. Needed when the calling key holds compliance:m but not compliance:d (e.g. the dashboard session key).
      security:
      - apiKey: []
      - apiKeyHeader: []
      x-honkio-permission: compliance:d
      responses:
        '200':
          description: Erased. Opt-out records are kept.
          content:
            application/json:
              schema:
                description: Erased. Opt-out records are kept.
                type: object
                additionalProperties: true
                required:
                - status
                - phone_number
                - erased_at
                - opt_outs_preserved
                properties:
                  status:
                    type: string
                    enum:
                    - erased
                  phone_number:
                    type: string
                  erased_at:
                    type: string
                    format: date-time
                  opt_outs_preserved:
                    type: boolean
                    enum:
                    - true
        '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: FORBIDDEN (the key lacks compliance:d and sent no compliance:d step-up token) or LIVE_KEY_REQUIRED (test keys cannot erase).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: INVALID_PHONE_NUMBER, CANNOT_ERASE_OWN_NUMBER or VALIDATION_ERROR.
          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: postV1ComplianceErasure
      x-operation-id-source: derived
components:
  schemas:
    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.'