KaiCalls Text Registration API

openapi: 3.2.0
info:
  title: KaiCalls Public Text Registration API
  version: '2026-06-05'
  description: Machine-readable surface for KaiCalls external developers and client agents.
servers:
- url: https://www.kaicalls.com/api
security:
- bearerAuth: []
tags:
- name: Text Registration
paths:
  /v1/text-registration:
    get:
      summary: Where a business stands on its own carrier registration for texting…
      description: 'Mirrors the get_text_registration tool: saved details (never the EIN, only ein_on_file), payment, filing stage, known details on file, the questions still missing, next_question, next_step and setup_url (the page where the owner finishes).'
      parameters:
      - name: business_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Registration status
        '403':
          description: Missing billing:read scope or no access to business_id
      x-required-scopes: billing:read
      tags:
      - Text Registration
      operationId: getV1TextRegistration
      x-operation-id-source: derived
    post:
      summary: Save registration details, start checkout or check reserved submission…
      description: 'action ''save'' mirrors save_text_registration_details: pass only the fields the owner gave; the rest is filled from what is on file, and while questions remain the response lists saved_steps, missing and next_question (code needs_answers). action ''start_checkout'' mirrors start_text_registration_checkout: it returns checkout_url for the owner to pay (nothing is charged here), or included_in_plan and filed when the plan includes registration. The EIN is never accepted over the API (400 ein_not_accepted); the owner types it on setup_url. save needs the key user to be the business owner or an admin (a partner preparing it for the owner); start_checkout needs the owner, and an admin gets 403 owner_required with owner_handoff_url, the page the owner opens to type the EIN, review and confirm. start_checkout requires confirm_submission true; included plans file immediately. submit is disabled with 503 submission_unavailable pending shared durable reservation and reconciliation; it performs no filing. Correcting saved details does not resubmit rejected provider objects, which need operator reconciliation. Poll GET for state: submission is not approval. No document contents, credentials or legal attestations are accepted.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - action
              - business_id
              properties:
                action:
                  type: string
                  enum:
                  - save
                  - start_checkout
                  - submit
                business_id:
                  type: string
                confirm_submission:
                  type: boolean
                  description: Required true for start_checkout or submit after explicit owner confirmation.
                expected_updated_at:
                  type: string
                  description: 'submit only: registration.updatedAt from a fresh status read.'
                legal_business_name:
                  type: string
                business_type:
                  type: string
                industry:
                  type: string
                website_url:
                  type: string
                street:
                  type: string
                city:
                  type: string
                state:
                  type: string
                postal_code:
                  type: string
                contact_first_name:
                  type: string
                contact_last_name:
                  type: string
                contact_email:
                  type: string
                contact_phone:
                  type: string
                contact_job_position:
                  type: string
                contact_title:
                  type: string
                text_types:
                  type: string
                  enum:
                  - service
                  - service_and_sales
      responses:
        '200':
          description: Saved or checkout result (not approval)
        '400':
          description: invalid_request, invalid_details or ein_not_accepted
        '403':
          description: Missing billing:write scope, no access, or owner_required
        '409':
          description: Not ready, confirmation required or saved revision changed
        '502':
          description: checkout_failed
        '503':
          description: 'submission_unavailable: external submission disabled; do not retry through another entry point'
      x-required-scopes: billing:write
      tags:
      - Text Registration
      operationId: postV1TextRegistration
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'KaiCalls API key. Per-operation scope requirements are published on each operation as `x-required-scopes` — a scope string, or a nested `{ allOf: [...] }` / `{ anyOf: [...] }` expression. An operation with no `x-required-scopes` requires a valid key but no particular scope.'
      x-scopes:
      - workspaces:read
      - workspaces:write
      - numbers:read
      - numbers:write
      - agents:read
      - agents:write
      - communication-runs:read
      - communication-runs:write
      - calls:read
      - calls:write
      - sms:read
      - sms:write
      - webhooks:read
      - webhooks:write
      - events:read
      - events:replay
      - lifecycle:write
      - leads:read
      - leads:write
      - emails:read
      - emails:write
      - sdr:read
      - sdr:write
      - evals:read
      - evals:write
      - appointments:read
      - appointments:write
      - knowledge:read
      - knowledge:write
      - products:read
      - products:write
      - integrations:write
      - approvals:write
      - concierge:write
      - billing:read
      - billing:write
      - call_evidence:read
      - call_evidence:write
      - support:write
    sessionAuth:
      type: apiKey
      in: cookie
      name: sb-access-token
      description: Authenticated dashboard session cookie. Used by first-party flows that mint or manage API keys.