BotNotice Consent API

openapi: 3.2.0
info:
  title: BotNotice Consent API
  version: 1.0.0
  summary: AI disclosure notices, consent records and call receipts for websites and AI phone agents, plus an open dataset of AI disclosure laws.
  description: 'BotNotice shows a "you''re talking to AI" notice beside a website''s chat, keeps a tamper-evident record of every notice, checks consent before AI phone calls and keeps a receipt per call. Plans: Chatbot Disclosure $12.99/month per website; Disclosure + Records $29.99/month per website; Managed Compliance $199/month per website; 14-day free trial on plans with records; no sales call, sign up at https://botnotice.app. The scan and the law dataset need no key. The consent, voice and content endpoints take a per-site token from the dashboard (Voice page for the voice token, Content page for the content-register token). Nothing here is legal advice.'
  termsOfService: https://botnotice.app/legal/terms
  contact:
    name: BotNotice support
    email: support@botnotice.app
    url: https://botnotice.app/support
  license:
    name: 'Law dataset: CC BY 4.0'
    url: https://creativecommons.org/licenses/by/4.0/
servers:
- url: https://botnotice.app
tags:
- name: Consent
  description: 'Consent to AI phone calls: record, check before dialing, revoke. Token: the site''s voice token (bni_…).'
paths:
  /api/consent:
    post:
      tags:
      - Consent
      operationId: recordConsent
      security:
      - voiceToken: []
      summary: Record that a person agreed to AI calls
      description: Send it the moment consent is given (form submit, CRM field). The number is stored only as a fingerprint plus its last four digits; the wording is kept so the record shows what the person agreed to.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                phone:
                  type: string
                  description: E.164 or a plain U.S. number
                scope:
                  type: string
                  enum:
                  - marketing
                  - informational
                  default: marketing
                method:
                  type: string
                  description: web_form, verbal, sms…
                wording:
                  type: string
                  description: The exact consent text shown
                source:
                  type: string
                  description: Form name or page address
                external_id:
                  type: string
                  description: Your lead or contact id
                consented_at:
                  type: string
                  description: ISO time; defaults to now
              required:
              - phone
              - wording
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  consent_id:
                    type: string
                  last4:
                    type: string
                  scope:
                    type: string
                  method:
                    type: string
                  consented_at:
                    type: string
        '400':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '401':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
  /api/consent/check:
    post:
      tags:
      - Consent
      operationId: checkConsent
      security:
      - voiceToken: []
      summary: 'The pre-dial check: may an AI call be placed to this number?'
      description: Call it right before dialing and dial only when allowed is true. The answer is written to the record, so it shows the check happened before the call, and the response carries the opening line the call must start with. POST only, so no phone number lands in a URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                phone:
                  type: string
                scope:
                  type: string
                  enum:
                  - marketing
                  - informational
                  default: marketing
                call_ref:
                  type: string
                  description: Your call id, written to the record
              required:
              - phone
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentCheck'
        '401':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
  /api/consent/revoke:
    post:
      tags:
      - Consent
      operationId: revokeConsent
      security:
      - voiceToken: []
      summary: 'Someone said stop: revoke consent for a number'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                phone:
                  type: string
                consent_id:
                  type: string
                  description: 'Instead of phone: one consent by id'
                method:
                  type: string
                  description: How they said stop, e.g. texted STOP
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  revoked:
                    type: integer
        '400':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '401':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
components:
  schemas:
    ConsentCheck:
      type: object
      properties:
        allowed:
          type: boolean
          description: Dial only when true
        reason:
          type: string
          enum:
          - consent_on_file
          - no_consent
          - revoked
          - wrong_scope
          - invalid_number
        message:
          type: string
        consent:
          type:
          - object
          - 'null'
          properties:
            id:
              type: string
            scope:
              type: string
            method:
              type: string
            consented_at:
              type: string
        disclosure:
          type: string
          description: The line the call must open with
        policyVersion:
          type:
          - integer
          - 'null'
  securitySchemes:
    voiceToken:
      type: http
      scheme: bearer
      description: The site's voice token (starts with bni_), from the dashboard's Voice page. Also accepted as ?token= on voice endpoints, and as x-vapi-secret on /api/voice/event.
    registerToken:
      type: http
      scheme: bearer
      description: The site's content-register token, from the dashboard's Content page.
externalDocs:
  description: Human documentation
  url: https://botnotice.app/docs/api