openapi: 3.0.3
info:
  title: ActiveCampaign SMS Broadcast Accounts Broadcasts API
  description: API for managing SMS broadcasts, lists, metrics, and AI-powered content generation in ActiveCampaign
  version: 3.0.0
  contact:
    name: ActiveCampaign Support
    url: https://www.activecampaign.com
  x-generated-from: documentation
servers:
- url: https://{yourAccountName}.api-us1.com/api/3
  description: US-based Users
  variables:
    yourAccountName:
      default: yourAccountName
security:
- ApiToken: []
tags:
- name: Broadcasts
paths:
  /sms/broadcasts:
    get:
      tags:
      - Broadcasts
      summary: ActiveCampaign Get All Broadcast Messages
      description: Gets a paged list of all of a customer's broadcast messages with optional filtering
      operationId: listBroadcasts
      parameters:
      - name: offset
        in: query
        description: Offset for pagination
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        description: Number of items to return
        schema:
          type: integer
          default: 20
      - name: filters[name]
        in: query
        description: Filter by broadcast name
        schema:
          type: string
      - name: filters[status]
        in: query
        description: Filter by broadcast status
        schema:
          type: string
          enum:
          - draft
          - scheduled
          - sent
          - pending_review
          - sending
      - name: filters[type]
        in: query
        description: Filter by broadcast type (future feature)
        schema:
          type: string
      - name: orders[field]
        in: query
        description: Order results by field (ASC or DESC)
        schema:
          type: string
          enum:
          - ASC
          - DESC
      - name: start_date
        in: query
        description: Filter by start date (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: Filter by end date (YYYY-MM-DD)
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BroadcastListResponse'
        '403':
          description: Insufficient permissions
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Broadcasts
      summary: ActiveCampaign Create a New Broadcast Message
      description: Creates a new SMS broadcast message
      operationId: createBroadcast
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BroadcastCreateRequest'
      responses:
        '201':
          description: Broadcast created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BroadcastMessage'
        '400':
          description: Invalid request data
        '403':
          description: Insufficient permissions
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sms/broadcasts/{id}:
    get:
      tags:
      - Broadcasts
      summary: ActiveCampaign Get Broadcast Message
      description: Retrieves the full details for one broadcast message
      operationId: getBroadcast
      parameters:
      - name: id
        in: path
        required: true
        description: Broadcast ID
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BroadcastMessage'
        '403':
          description: Insufficient permissions
        '404':
          description: Broadcast not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags:
      - Broadcasts
      summary: ActiveCampaign Update Broadcast Message
      description: Updates an existing broadcast message
      operationId: updateBroadcast
      parameters:
      - name: id
        in: path
        required: true
        description: Broadcast ID
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BroadcastUpdateRequest'
      responses:
        '200':
          description: Broadcast updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BroadcastMessage'
        '403':
          description: Insufficient permissions
        '404':
          description: Broadcast not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      tags:
      - Broadcasts
      summary: ActiveCampaign Delete Broadcast Message
      description: Performs a soft-delete on the requested message
      operationId: deleteBroadcast
      parameters:
      - name: id
        in: path
        required: true
        description: Broadcast ID
        schema:
          type: integer
      responses:
        '200':
          description: Broadcast deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BroadcastMessage'
        '403':
          description: Insufficient permissions
        '404':
          description: Broadcast not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sms/lists:
    get:
      tags:
      - Broadcasts
      summary: ActiveCampaign Get All Broadcast Lists
      description: Gets a paged list of all broadcast lists (SMS channel)
      operationId: listBroadcastLists
      parameters:
      - name: offset
        in: query
        description: Offset for pagination
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        description: Number of items to return
        schema:
          type: integer
          default: 20
      - name: filters[name]
        in: query
        description: Filter by list name
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BroadcastListsResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sms/broadcasts/ai:
    post:
      tags:
      - Broadcasts
      summary: ActiveCampaign Create AI-generated Broadcast
      description: Creates a broadcast using AI based on prompt and tone
      operationId: createAIBroadcast
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AIBroadcastRequest'
      responses:
        '200':
          description: AI broadcast request initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIBroadcastResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      summary: ActiveCampaign Update Broadcast with AI
      description: Updates an existing broadcast using AI
      operationId: updateAIBroadcast
      tags:
      - Broadcasts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AIBroadcastUpdateRequest'
      responses:
        '200':
          description: AI broadcast update request initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIBroadcastResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sms/broadcasts/ai/{Id}:
    get:
      tags:
      - Broadcasts
      summary: ActiveCampaign Get AI Broadcast Request Status
      description: Returns the current status of the AI process execution
      operationId: getAIBroadcastStatus
      parameters:
      - name: Id
        in: path
        required: true
        description: Request ID from AI broadcast creation
        schema:
          type: string
      responses:
        '200':
          description: Status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIBroadcastStatus'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sms/broadcasts/metrics:
    post:
      tags:
      - Broadcasts
      summary: ActiveCampaign Get All Broadcast Metrics
      description: Returns metrics for specified broadcast IDs
      operationId: getBroadcastMetrics
      parameters:
      - name: start_date
        in: query
        description: Start date for metrics (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: End date for metrics (YYYY-MM-DD)
        schema:
          type: string
          format: date
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: integer
      responses:
        '200':
          description: Metrics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BroadcastMetricsResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sms/broadcasts/metrics/snapshot:
    get:
      tags:
      - Broadcasts
      summary: ActiveCampaign Get Broadcast Snapshot
      description: Returns snapshot data for all broadcasts
      operationId: getBroadcastSnapshot
      parameters:
      - name: start_date
        in: query
        description: Start date for snapshot (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: End date for snapshot (YYYY-MM-DD)
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Snapshot retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Broadcasts
      summary: ActiveCampaign Get Broadcast Snapshot
      description: Returns snapshot for specified broadcast IDs
      operationId: getBroadcastSnapshotByIds
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: integer
      responses:
        '200':
          description: Snapshot retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sms/broadcasts/metrics/{broadcastId}/failures:
    get:
      tags:
      - Broadcasts
      summary: ActiveCampaign Get Broadcast Failure Details
      description: Returns grouping and counts of failures for the broadcast
      operationId: getBroadcastFailures
      parameters:
      - name: broadcastId
        in: path
        required: true
        description: Broadcast ID
        schema:
          type: integer
      - name: start_date
        in: query
        description: Start date (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: End date (YYYY-MM-DD)
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Failure details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailureDetailsResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sms/broadcasts/{broadcastId}/recipients:
    get:
      tags:
      - Broadcasts
      summary: ActiveCampaign Get Broadcast Recipients
      description: Fetch all contacts who were sent a specific broadcast
      operationId: getBroadcastRecipients
      parameters:
      - name: broadcastId
        in: path
        required: true
        description: Broadcast ID
        schema:
          type: integer
      - name: start_date
        in: query
        description: Start date (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: End date (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - name: filters[deliverability][]
        in: query
        description: Filter by deliverability status
        schema:
          type: array
          items:
            type: string
            enum:
            - deliveries
            - failures
      - name: filters[engagement][]
        in: query
        description: Filter by engagement type
        schema:
          type: array
          items:
            type: string
            enum:
            - clicks
            - replies
            - optOuts
      - name: search
        in: query
        description: Search contacts by name or phone
        schema:
          type: string
      - name: order[field]
        in: query
        description: Order by field
        schema:
          type: string
          enum:
          - name
          - phone
          - sentDate
          - clicks
          - deliverability
          - optOut
          - replies
      - name: offset
        in: query
        description: Offset for pagination
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        description: Number of items to return
        schema:
          type: integer
          default: 20
      responses:
        '200':
          description: Recipients retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientsResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sms/broadcasts/export:
    post:
      tags:
      - Broadcasts
      summary: ActiveCampaign Export Broadcast Metrics
      description: Export broadcast performance metrics as CSV
      operationId: exportBroadcastMetrics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: integer
      responses:
        '200':
          description: Export generated successfully
          content:
            text/csv:
              schema:
                type: string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sms/broadcasts/{broadcastId}/recipients/export:
    post:
      tags:
      - Broadcasts
      summary: ActiveCampaign Export Broadcast Recipients
      description: Export recipient data as CSV including full contact records
      operationId: exportBroadcastRecipients
      parameters:
      - name: broadcastId
        in: path
        required: true
        description: Broadcast ID
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                start_date:
                  type: string
                  format: date
                end_date:
                  type: string
                  format: date
                engagement:
                  type: array
                  items:
                    type: string
                deliverability:
                  type: array
                  items:
                    type: string
                search:
                  type: string
                order:
                  type: object
      responses:
        '200':
          description: Export generated successfully
          content:
            text/csv:
              schema:
                type: string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    FailureDetail:
      type: object
      properties:
        errorCode:
          type: string
        errorSource:
          type: string
          enum:
          - ac
          - twilio
        count:
          type: integer
    BroadcastMessage:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the broadcast
        name:
          type: string
          description: Name of the broadcast
        address_id:
          type: integer
          nullable: true
          description: ID used to get sender name
        body:
          type: string
          description: SMS message content
        media_urls:
          type: array
          items:
            type: string
            format: uri
          description: Media URLs for MMS messages
        preview_url:
          type: string
          format: uri
          description: URL for message preview
        shorten_track_links_enabled:
          type: boolean
          description: Whether link shortening is enabled
        status:
          type: string
          enum:
          - draft
          - scheduled
          - sent
          - pending_review
          - sending
          description: Current status of the broadcast
        sent_date:
          type: string
          format: date-time
          nullable: true
          description: Date when broadcast was sent
        scheduled_date:
          type: string
          format: date-time
          nullable: true
          description: Scheduled send date (UTC)
        custom_run_id:
          type: string
          format: uuid
          nullable: true
          description: custom run id generated from segmentMatchSome endpoint
        custom_segment_id:
          type: string
          format: uuid
          nullable: true
          description: custom segment id generated from segmentsV2 endpoint and passing in a valid audience
        scheduled_by:
          type: integer
          nullable: true
          description: User ID who scheduled the broadcast
        sent_to_count:
          type: integer
          nullable: true
          description: Number of recipients
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        created_by:
          type: integer
          description: User ID who created the broadcast
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        updated_by:
          type: integer
          description: User ID who last updated
        deleted_at:
          type: string
          format: date-time
          nullable: true
          description: Deletion timestamp (for soft deletes)
        sift_approved:
          type: integer
          description: Sift approval status
        arc_approved:
          type: integer
          description: ARC approval status
        quiet_hours_enabled:
          type: integer
          nullable: true
          description: Whether quiet hours are enabled
        list_ids:
          type: array
          items:
            type: integer
          description: Associated list IDs
        segment_id:
          type: string
          nullable: true
          description: Segment ID (can be UUID or integer string)
        label_ids:
          type: array
          items:
            type: integer
          nullable: true
          description: Associated label IDs
    BroadcastUpdateRequest:
      type: object
      properties:
        name:
          type: string
        address_id:
          type: integer
          nullable: true
        body:
          type: string
        media_urls:
          type: array
          items:
            type: string
            format: uri
        preview_url:
          type: string
          format: uri
        shorten_track_links_enabled:
          type: boolean
        status:
          type: string
          description: Status of the broadcast. pending_review starts kicks off the broadcast to be sent
          enum:
          - draft
          - pending_review
        scheduled_date:
          type: string
          format: date-time
        sent_to_count:
          type: integer
        list_ids:
          type: array
          items:
            type: integer
        segment_id:
          type: string
        custom_run_id:
          type: string
          description: custom run id generated from segmentMatchSome endpoint and passing a valid segment id
          format: uuid
          nullable: true
        custom_segment_id:
          type: string
          description: custom segment id generated from segmentsV2 endpoint and passing in a valid audience
          format: uuid
          nullable: true
        label_ids:
          type: array
          items:
            type: integer
    AIBroadcastRequest:
      type: object
      required:
      - source
      - prompt
      - tone
      properties:
        source:
          type: string
          enum:
          - ai_index
          - sms_index
          - ai_builder
        prompt:
          type: string
          description: User prompt for AI generation
        tone:
          type: string
          description: Desired tone for the message
    AIBroadcastUpdateRequest:
      type: object
      required:
      - source
      - prompt
      - tone
      - broadcastId
      properties:
        source:
          type: string
          enum:
          - ai_index
          - sms_index
          - ai_builder
        prompt:
          type: string
        tone:
          type: string
        broadcastId:
          type: integer
    RecipientsResponse:
      type: object
      properties:
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/Recipient'
        meta:
          type: object
          properties:
            total:
              type: integer
            limit:
              type: integer
            offset:
              type: integer
    BroadcastCreateRequest:
      type: object
      required:
      - name
      - body
      properties:
        name:
          type: string
          description: Name of the broadcast
        address_id:
          type: integer
          nullable: true
          description: ID for sender name
        body:
          type: string
          description: SMS message content
        media_urls:
          type: array
          items:
            type: string
            format: uri
          description: Media URLs for MMS
        preview_url:
          type: string
          format: uri
        shorten_track_links_enabled:
          type: boolean
        status:
          type: string
          enum:
          - draft
        scheduled_date:
          type: string
          format: date-time
        sent_to_count:
          type: integer
        list_ids:
          type: array
          items:
            type: integer
        segment_id:
          type: string
        custom_segment_id:
          type: string
          description: custom segment id generated from segmentsV2 endpoint and passing in a valid audience
          format: uuid
          nullable: true
        label_ids:
          type: array
          items:
            type: integer
    BroadcastMetricsResponse:
      type: object
      properties:
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/BroadcastMetrics'
    AIBroadcastStatus:
      type: object
      properties:
        source:
          type: string
          enum:
          - ai_index
          - sms_index
          - ai_builder
        status:
          type: string
          enum:
          - in_progress
          - error
          - success
        broadcastId:
          type: integer
          nullable: true
    AIBroadcastResponse:
      type: object
      properties:
        requestId:
          type: string
          description: External identifier to track the request
    BroadcastListsResponse:
      type: object
      properties:
        lists:
          type: array
          items:
            $ref: '#/components/schemas/BroadcastList'
        meta:
          type: object
          properties:
            total:
              type: integer
    BroadcastList:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        subscriber_count:
          type: integer
    BroadcastListResponse:
      type: object
      properties:
        broadcasts:
          type: array
          items:
            $ref: '#/components/schemas/BroadcastMessage'
        meta:
          type: object
          properties:
            total:
              type: integer
              description: Total number of broadcasts
    FailureDetailsResponse:
      type: object
      properties:
        failures:
          type: array
          items:
            $ref: '#/components/schemas/FailureDetail'
    SnapshotResponse:
      type: object
      properties:
        snapshot:
          type: object
          properties:
            campaigns:
              type: integer
            sends:
              type: integer
            deliveries:
              type: integer
            clicks:
              type: integer
            replies:
              type: integer
            failures:
              type: integer
            optOuts:
              type: integer
    BroadcastMetrics:
      type: object
      properties:
        id:
          type: integer
        sends:
          type: integer
        deliveries:
          type: integer
        replies:
          type: integer
        failures:
          type: integer
        optOuts:
          type: integer
        clicks:
          type: integer
    Recipient:
      type: object
      properties:
        id:
          type: integer
          description: Contact ID
        name:
          type: string
        phoneNumber:
          type: string
        sentDate:
          type: string
          format: date-time
          description: Timestamp in CST
        clicks:
          type: integer
        deliverability:
          type: string
          enum:
          - delivered
          - failed
        replies:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
              date:
                type: string
                format: date-time
                description: Timestamp in CST
        optOut:
          type: string
          enum:
          - 'yes'
          - 'no'
        details:
          type: object
          properties:
            errorCode:
              type: string
            errorSource:
              type: string
              enum:
              - ac
              - twilio
  securitySchemes:
    ApiToken:
      type: apiKey
      name: Api-Token
      in: header
      description: Your ActiveCampaign API token