iZap.ai Transmissions API

openapi: 3.2.0
info:
  contact:
    email: support@izap.ai
    name: iZap API Support
  description: Public REST API for the iZap WhatsApp business messaging platform.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  title: iZap Transmissions API
  version: v1
servers:
- description: Production
  url: https://api.izap.ai
- description: Staging
  url: https://api-staging.izap.ai
tags:
- description: Bulk template sends. A transmission is previewed into a draft, then confirmed or cancelled — confirming dispatches to real recipients.
  name: transmissions
paths:
  /api/v1/transmissions:
    get:
      description: Returns the business's bulk sends, newest first. Archived rows are omitted unless `status=archived` is passed. Optionally filter by any other status.
      operationId: listTransmissions
      parameters:
      - in: query
        name: status
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
      - in: query
        name: limit
        required: false
        schema:
          default: 50
          maximum: 200
          minimum: 1
          title: Limit
          type: integer
      - description: Case-insensitive substring of the name.
        in: query
        name: q
        required: false
        schema:
          anyOf:
          - maxLength: 255
            type: string
          - type: 'null'
          description: Case-insensitive substring of the name.
          title: Q
      - description: Only transmissions going out from this WhatsApp number of the business.
        in: query
        name: sender_phone_number
        required: false
        schema:
          anyOf:
          - maxLength: 32
            type: string
          - type: 'null'
          description: Only transmissions going out from this WhatsApp number of the business.
          title: Sender Phone Number
      - in: header
        name: business-id
        required: true
        schema:
          format: uuid
          title: Business-Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTransmissionsOut'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Missing or invalid credentials.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The credential is valid but not authorized for this action.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource, or the business named in the request, does not exist.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unexpected error.
      security:
      - bearerAuth: []
      summary: List transmissions
      tags:
      - transmissions
  /api/v1/transmissions/preview:
    post:
      description: Validates the recipient list and template and stores the result as a draft, without sending anything. Review the draft, then confirm it to dispatch.
      operationId: previewTransmission
      parameters:
      - in: header
        name: business-id
        required: true
        schema:
          format: uuid
          title: Business-Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTransmissionPreviewIn'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransmissionPreviewOut'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Missing or invalid credentials.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The credential is valid but not authorized for this action.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource, or the business named in the request, does not exist.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unexpected error.
      security:
      - bearerAuth: []
      summary: Preview a transmission
      tags:
      - transmissions
  /api/v1/transmissions/{transmission_id}:
    get:
      description: Returns one transmission with its current status and per-recipient counts.
      operationId: getTransmission
      parameters:
      - in: path
        name: transmission_id
        required: true
        schema:
          format: uuid
          title: Transmission Id
          type: string
      - in: header
        name: business-id
        required: true
        schema:
          format: uuid
          title: Business-Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransmissionStatusOut'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Missing or invalid credentials.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The credential is valid but not authorized for this action.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource, or the business named in the request, does not exist.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unexpected error.
      security:
      - bearerAuth: []
      summary: Retrieve a transmission
      tags:
      - transmissions
  /api/v1/transmissions/{transmission_id}/archive:
    post:
      description: Hides a draft or cancelled transmission from the default list without deleting it. Idempotent for already-archived rows. Does not send or confirm; confirming an archived transmission is rejected.
      operationId: archiveTransmission
      parameters:
      - in: path
        name: transmission_id
        required: true
        schema:
          format: uuid
          title: Transmission Id
          type: string
      - in: header
        name: business-id
        required: true
        schema:
          format: uuid
          title: Business-Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransmissionStatusOut'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Missing or invalid credentials.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The credential is valid but not authorized for this action.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource, or the business named in the request, does not exist.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unexpected error.
      security:
      - bearerAuth: []
      summary: Archive a transmission
      tags:
      - transmissions
  /api/v1/transmissions/{transmission_id}/cancel:
    post:
      description: Cancels a transmission that has not finished. Cancelling one that already completed, failed or was cancelled is a no-op that returns its current status. A send in progress stops cooperatively, so messages already dispatched are still delivered.
      operationId: cancelTransmission
      parameters:
      - in: path
        name: transmission_id
        required: true
        schema:
          format: uuid
          title: Transmission Id
          type: string
      - in: header
        name: business-id
        required: true
        schema:
          format: uuid
          title: Business-Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransmissionStatusOut'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Missing or invalid credentials.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The credential is valid but not authorized for this action.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource, or the business named in the request, does not exist.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unexpected error.
      security:
      - bearerAuth: []
      summary: Cancel a transmission
      tags:
      - transmissions
  /api/v1/transmissions/{transmission_id}/confirm:
    post:
      description: Releases a draft transmission for delivery. **This sends real messages to real recipients and cannot be undone.**
      operationId: confirmTransmission
      parameters:
      - in: path
        name: transmission_id
        required: true
        schema:
          format: uuid
          title: Transmission Id
          type: string
      - in: header
        name: business-id
        required: true
        schema:
          format: uuid
          title: Business-Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransmissionStatusOut'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Missing or invalid credentials.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The credential is valid but not authorized for this action.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource, or the business named in the request, does not exist.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unexpected error.
      security:
      - bearerAuth: []
      summary: Confirm and dispatch a transmission
      tags:
      - transmissions
  /api/v1/transmissions/{transmission_id}/release:
    post:
      description: A marketing transmission with more than 100 recipients sends its first 100 and pauses. Releasing it sends every remaining recipient and it never pauses again. **This sends real messages to real recipients.** Only a paused transmission can be released; any other status, or a second release, returns 409.
      operationId: releaseTransmission
      parameters:
      - in: path
        name: transmission_id
        required: true
        schema:
          format: uuid
          title: Transmission Id
          type: string
      - in: header
        name: business-id
        required: true
        schema:
          format: uuid
          title: Business-Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransmissionStatusOut'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Missing or invalid credentials.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The credential is valid but not authorized for this action.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource, or the business named in the request, does not exist.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unexpected error.
      security:
      - bearerAuth: []
      summary: Release a paused transmission
      tags:
      - transmissions
components:
  schemas:
    ApiError:
      description: 'The response body of a handled API error.


        ``detail`` is either a plain string (FastAPI''s default for an

        ``HTTPException`` raised with a string, and for the ``default`` fastapi-users

        messages like ``"Not authenticated"``) or the structured

        :class:`ApiErrorDetail` object described above. ``code`` is present only on

        the top-level shape ``aizap.core.exceptions.AppException`` produces for its

        own 5xx responses (``"INTERNAL_ERROR"`` / ``"DB_ERROR"``); it does not

        duplicate the ``code`` nested inside a structured ``detail``.'
      properties:
        code:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Code
        detail:
          anyOf:
          - type: string
          - $ref: '#/components/schemas/ApiErrorDetail'
          title: Detail
      required:
      - detail
      title: ApiError
      type: object
    TransmissionPreviewOut:
      properties:
        business_id:
          format: uuid
          title: Business Id
          type: string
        column_mapping:
          additionalProperties:
            type: string
          title: Column Mapping
          type: object
        duplicate_count:
          title: Duplicate Count
          type: integer
        estimated_duration_seconds:
          title: Estimated Duration Seconds
          type: integer
        invalid_count:
          title: Invalid Count
          type: integer
        name:
          title: Name
          type: string
        not_on_whatsapp_count:
          default: 0
          title: Not On Whatsapp Count
          type: integer
        outside_window_count:
          default: 0
          title: Outside Window Count
          type: integer
        phone_column:
          title: Phone Column
          type: string
        recipient_count:
          title: Recipient Count
          type: integer
        sample_errors:
          items:
            $ref: '#/components/schemas/PreviewRowErrorOut'
          title: Sample Errors
          type: array
        scheduled_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Scheduled At
        sender_phone_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Sender Phone Number
        status:
          title: Status
          type: string
        template_language:
          title: Template Language
          type: string
        template_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Template Name
        transmission_id:
          format: uuid
          title: Transmission Id
          type: string
        transmission_type:
          title: Transmission Type
          type: string
        uses_named_variables:
          title: Uses Named Variables
          type: boolean
        valid_count:
          title: Valid Count
          type: integer
        warning_details:
          default: []
          items:
            $ref: '#/components/schemas/TransmissionWarningOut'
          title: Warning Details
          type: array
        warnings:
          items:
            type: string
          title: Warnings
          type: array
      required:
      - transmission_id
      - name
      - status
      - transmission_type
      - template_name
      - template_language
      - uses_named_variables
      - recipient_count
      - valid_count
      - invalid_count
      - duplicate_count
      - column_mapping
      - phone_column
      - sample_errors
      - estimated_duration_seconds
      - scheduled_at
      - warnings
      - business_id
      title: TransmissionPreviewOut
      type: object
    CreateTransmissionPreviewIn:
      description: 'Validate CSV recipients against a template and create a DRAFT transmission.


        No messages are sent. ``recipients`` are parsed CSV rows (header -> value); each

        row must contain ``phone_column`` and the columns that fill the template''s

        variables. Confirm the returned draft id with ``confirm_transmission`` to send.'
      properties:
        business_id:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
          title: Business Id
        header_media_document_id:
          anyOf:
          - type: string
          - type: 'null'
          description: UUID or filename of a document or video in the business's media library to use as the template's DOCUMENT or VIDEO header. Mutually exclusive with the other header media sources.
          title: Header Media Document Id
        header_media_filename:
          anyOf:
          - maxLength: 240
            type: string
          - type: 'null'
          description: Name recipients see for a DOCUMENT header. Ignored for image and video headers.
          title: Header Media Filename
        header_media_image_id:
          anyOf:
          - type: string
          - type: 'null'
          description: UUID or filename of an image in the business's media library to use as the template's IMAGE header. Mutually exclusive with the other header media sources.
          title: Header Media Image Id
        header_media_url:
          anyOf:
          - maxLength: 2048
            type: string
          - type: 'null'
          description: Public https:// URL of the file for the template's media header (an image for an IMAGE header, a PDF for a DOCUMENT header, an MP4 for a VIDEO header). Required when the template was approved with a media header; the same file goes to every recipient. Mutually exclusive with the library header fields.
          title: Header Media Url
        max_messages_per_minute:
          default: 60
          description: Sending pace cap. Must be between 1 and 200 messages per minute.
          maximum: 200.0
          minimum: 1.0
          title: Max Messages Per Minute
          type: integer
        message_text:
          anyOf:
          - maxLength: 4096
            type: string
          - type: 'null'
          description: Text to send. Required for 'whatsapp_freeform', which only reaches contacts inside the WhatsApp customer-service window; others are skipped.
          title: Message Text
        name:
          description: Human label for the transmission.
          maxLength: 255
          minLength: 1
          title: Name
          type: string
        phone_column:
          default: phone
          description: Name of the CSV column holding the recipient phone number (E.164 or local).
          maxLength: 255
          minLength: 1
          title: Phone Column
          type: string
        recipients:
          description: Parsed CSV rows; each row maps a string column header to its string cell value. Must include the phone column and the columns that supply the template's variables.
          items:
            additionalProperties:
              type: string
            type: object
          maxItems: 5000
          minItems: 1
          title: Recipients
          type: array
        scheduled_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: When to send. Omit or null to send immediately on confirm. If the value has no timezone offset it is interpreted in 'timezone'.
          title: Scheduled At
        sender_phone_number:
          anyOf:
          - maxLength: 32
            type: string
          - type: 'null'
          description: Which of the business's connected WhatsApp numbers sends the transmission, e.g. '+5562999998888' (any formatting). Omit to send from the business's oldest connected number.
          title: Sender Phone Number
        template_language:
          default: pt_BR
          description: Template language/locale code as registered with Meta, e.g. 'pt_BR'.
          maxLength: 15
          minLength: 2
          title: Template Language
          type: string
        template_name:
          default: freeform
          description: Name of the pre-approved WhatsApp Cloud API template to send. Required for 'whatsapp_template'; not accepted for 'whatsapp_freeform', which stores a fixed default.
          maxLength: 512
          minLength: 1
          title: Template Name
          type: string
        timezone:
          anyOf:
          - type: string
          - type: 'null'
          description: IANA timezone used to interpret a naive 'scheduled_at'. Defaults to the business's configured timezone (America/Sao_Paulo when none is set).
          title: Timezone
        transmission_type:
          $ref: '#/components/schemas/TransmissionType'
          default: whatsapp_template
          description: 'Transmission kind: ''whatsapp_template'' or ''whatsapp_freeform''.'
        variable_columns:
          anyOf:
          - items:
              type: string
            maxItems: 50
            type: array
          - type: 'null'
          description: 'For positional templates ({{1}}, {{2}}, ...): the ordered CSV header names mapping to {{1}}, {{2}}, ... If omitted, the first non-phone columns are used in order. Ignored for templates with named placeholders.'
          title: Variable Columns
      required:
      - name
      - recipients
      title: CreateTransmissionPreviewIn
      type: object
    ListTransmissionsOut:
      properties:
        business_id:
          format: uuid
          title: Business Id
          type: string
        total:
          title: Total
          type: integer
        transmissions:
          items:
            $ref: '#/components/schemas/TransmissionStatusOut'
          title: Transmissions
          type: array
      required:
      - transmissions
      - total
      - business_id
      title: ListTransmissionsOut
      type: object
    ApiErrorDetail:
      additionalProperties: true
      description: 'The structured ``detail`` object some error responses carry.


        Several handlers (the REST API plan gate, the free-tier limits, the

        webhooks entitlement gate, the closed customer-service window) raise

        ``HTTPException(detail={"code": ..., "message": ..., ...})`` — a fixed

        ``code``/``message`` pair plus extra fields specific to that error.

        ``extra="allow"`` keeps those fields in the documented shape instead of

        dropping them.'
      properties:
        code:
          title: Code
          type: string
        message:
          title: Message
          type: string
      required:
      - code
      - message
      title: ApiErrorDetail
      type: object
    TransmissionWarningOut:
      properties:
        code:
          enum:
          - marketing_template
          - template_not_synced
          - variable_unmatched
          title: Code
          type: string
        message:
          title: Message
          type: string
        variable:
          anyOf:
          - type: string
          - type: 'null'
          title: Variable
      required:
      - code
      - message
      title: TransmissionWarningOut
      type: object
    PreviewRowErrorOut:
      properties:
        error:
          title: Error
          type: string
        phone:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone
        row_index:
          title: Row Index
          type: integer
      required:
      - row_index
      - phone
      - error
      title: PreviewRowErrorOut
      type: object
    TransmissionStatusOut:
      properties:
        blocked_failed_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Blocked Failed Count
        business_id:
          format: uuid
          title: Business Id
          type: string
        completed_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Completed At
        created:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Created
        failed_count:
          title: Failed Count
          type: integer
        name:
          title: Name
          type: string
        pending_count:
          title: Pending Count
          type: integer
        progress_pct:
          title: Progress Pct
          type: number
        scheduled_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Scheduled At
        sender_phone_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Sender Phone Number
        sender_quality_rating:
          anyOf:
          - type: string
          - type: 'null'
          title: Sender Quality Rating
        sent_count:
          title: Sent Count
          type: integer
        started_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Started At
        status:
          title: Status
          type: string
        template_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Template Name
        total_recipients:
          title: Total Recipients
          type: integer
        transmission_id:
          format: uuid
          title: Transmission Id
          type: string
        transmission_type:
          title: Transmission Type
          type: string
        wave_released_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Wave Released At
      required:
      - transmission_id
      - name
      - status
      - transmission_type
      - template_name
      - total_recipients
      - sent_count
      - failed_count
      - pending_count
      - progress_pct
      - scheduled_at
      - started_at
      - completed_at
      - business_id
      title: TransmissionStatusOut
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    TransmissionType:
      description: 'The kind of bulk message a transmission sends.


        ``WHATSAPP_TEMPLATE`` sends an approved template to a phone list. ``WHATSAPP_FREEFORM``

        sends a fixed text and only reaches contacts inside Meta''s 24h customer-service window.

        Modelled as an enum so further channels can be added without a schema change to the

        stored value.'
      enum:
      - whatsapp_template
      - whatsapp_freeform
      title: TransmissionType
      type: string
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
  securitySchemes:
    bearerAuth:
      description: 'Personal access token (izap_pat_…) sent as Authorization: Bearer <token>; dashboard session JWTs are also accepted.'
      scheme: bearer
      type: http