IRONSCALES SAT API

openapi: 3.2.0
info:
  title: IRONSCALES Management SAT API
  description: The SAT operations of the IRONSCALES Management API, split by tag from the provider-published Swagger 2.0 document at https://appapi.ironscales.com/appapi/docs/?format=openapi. Operations, parameters, responses and definitions are carried verbatim from the source specification.
  version: v1
servers:
- url: https://appapi.ironscales.com/appapi
security:
- JWT: []
tags:
- name: SAT
paths:
  /sat/{company_id}/campaigns/:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: Get Campaigns List
      description: <b>Scopes:</b><ul><li>company.view</li><li>partner.company.view</li></ul>
      parameters:
      - name: page
        in: query
        description: 'Page number (default: 1)'
        required: false
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: page_size
        in: query
        description: 'Number of items per page (default: 25, max: 50)'
        required: false
        schema:
          type: integer
          default: 25
          maximum: 50
          minimum: 1
      - name: search
        in: query
        description: 'Case-insensitive substring filter for campaign names.

          - Example: ''training'' matches ''Security Training'''
        required: false
        schema:
          type: string
          minLength: 1
      - name: flow_types
        in: query
        description: 'Filter by campaign flow type IDs.

          - `1` = Training Only - Filter for campaigns that only include training content

          - `2` = Simulation and Training - Filter for campaigns that include both phishing simulation and training

          '
        required: false
        schema:
          type: array
          items:
            type: integer
            enum:
            - 1
            - 2
            - 3
      - name: locale_ids
        in: query
        description: 'Filter by locale IDs.

          - Use numeric identifiers from the locale catalog'
        required: false
        schema:
          type: array
          items:
            type: integer
      - name: statuses
        in: query
        description: 'Filter by campaign status codes.

          - `0` = Draft - Filter for campaigns in draft state

          - `1` = Collecting (Active) - Filter for campaigns actively collecting participant data

          - `2` = Completed - Filter for campaigns that have finished

          - `3` = Pending - Filter for campaigns approved but waiting to start

          - `4` = Active - Filter for campaigns currently running

          - `5` = Inactive - Filter for inactive campaigns'
        required: false
        schema:
          type: array
          items:
            type: integer
            enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
      - name: scheduled_date_from
        in: query
        description: 'Earliest campaign schedule date (inclusive).

          - Format: MM-DD-YYYY

          - Cannot be combined with `scheduled_time_from` / `scheduled_time_to`.'
        required: false
        schema:
          type: string
          format: date
      - name: scheduled_date_to
        in: query
        description: 'Latest campaign schedule date (inclusive).

          - Format: MM-DD-YYYY

          - Cannot be combined with `scheduled_time_from` / `scheduled_time_to`.'
        required: false
        schema:
          type: string
          format: date
      - name: scheduled_time_from
        in: query
        description: 'Earliest campaign schedule timestamp (inclusive).

          - Format: ISO 8601 datetime (e.g., `2026-03-01T00:00:00Z`)

          - Cannot be combined with `scheduled_date_from` / `scheduled_date_to`.'
        required: false
        schema:
          type: string
          format: date-time
      - name: scheduled_time_to
        in: query
        description: 'Latest campaign schedule timestamp (inclusive).

          - Format: ISO 8601 datetime (e.g., `2026-03-31T23:59:59Z`)

          - Cannot be combined with `scheduled_date_from` / `scheduled_date_to`.'
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignListResponse'
        '400':
          description: Bad Request - Invalid request parameters or validation error
          content:
            application/json:
              example:
                field_name:
                - Field related error message.
        '401':
          description: Unauthorized - Authentication credentials were not provided or are invalid
          content:
            application/json:
              example:
                detail: Authentication credentials were not provided.
        '403':
          description: Forbidden - You do not have permission to perform this action
          content:
            application/json:
              example:
                detail: You do not have permission for company 123
        '404':
          description: Not Found - The requested resource was not found
          content:
            application/json:
              example:
                detail: Not found.
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              example:
                detail: Request was throttled. Expected available in 60 seconds.
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              example:
                detail: Internal server error.
      tags:
      - SAT
    post:
      operationId: Create Draft Campaign
      summary: Create a new draft campaign.
      description: 'Creates a new campaign in DRAFT status. The campaign can be configured

        with various settings including participants, scenarios, trainings,

        notifications, and campaign-specific data based on the flow type.<b>Scopes:</b><ul><li>company.edit</li><li>partner.company.edit</li></ul>'
      responses:
        '201':
          description: Campaign successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignCreateResponse'
              example:
                id: 123
        '400':
          description: Bad Request - Invalid request parameters or validation error
          content:
            application/json:
              example:
                field_name:
                - Field related error message.
        '401':
          description: Unauthorized - Authentication credentials were not provided or are invalid
          content:
            application/json:
              example:
                detail: Authentication credentials were not provided.
        '403':
          description: Forbidden - You do not have permission to perform this action
          content:
            application/json:
              example:
                detail: You do not have permission for company 123
        '404':
          description: Not Found - The requested resource was not found
          content:
            application/json:
              example:
                detail: Not found.
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              example:
                detail: Request was throttled. Expected available in 60 seconds.
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              example:
                detail: Internal server error.
      tags:
      - SAT
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignCreateRequest'
        required: true
  /sat/{company_id}/campaigns/lookup/:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: Get Campaigns Lookup
      summary: Return a lightweight id/name list of campaigns.
      description: 'Accepts the same filters and pagination as the campaigns list

        endpoint but omits the per-campaign statistic annotations, making it

        suitable for pickers and other lookups that only need identifiers and

        names.<b>Scopes:</b><ul><li>company.view</li><li>partner.company.view</li></ul>'
      parameters:
      - name: page
        in: query
        description: 'Page number (default: 1)'
        required: false
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: page_size
        in: query
        description: 'Number of items per page (default: 25, max: 50)'
        required: false
        schema:
          type: integer
          default: 25
          maximum: 50
          minimum: 1
      - name: search
        in: query
        description: 'Case-insensitive substring filter for campaign names.

          - Example: ''training'' matches ''Security Training'''
        required: false
        schema:
          type: string
          minLength: 1
      - name: flow_types
        in: query
        description: 'Filter by campaign flow type IDs.

          - `1` = Training Only - Filter for campaigns that only include training content

          - `2` = Simulation and Training - Filter for campaigns that include both phishing simulation and training

          '
        required: false
        schema:
          type: array
          items:
            type: integer
            enum:
            - 1
            - 2
            - 3
      - name: locale_ids
        in: query
        description: 'Filter by locale IDs.

          - Use numeric identifiers from the locale catalog'
        required: false
        schema:
          type: array
          items:
            type: integer
      - name: statuses
        in: query
        description: 'Filter by campaign status codes.

          - `0` = Draft - Filter for campaigns in draft state

          - `1` = Collecting (Active) - Filter for campaigns actively collecting participant data

          - `2` = Completed - Filter for campaigns that have finished

          - `3` = Pending - Filter for campaigns approved but waiting to start

          - `4` = Active - Filter for campaigns currently running

          - `5` = Inactive - Filter for inactive campaigns'
        required: false
        schema:
          type: array
          items:
            type: integer
            enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
      - name: scheduled_date_from
        in: query
        description: 'Earliest campaign schedule date (inclusive).

          - Format: MM-DD-YYYY

          - Cannot be combined with `scheduled_time_from` / `scheduled_time_to`.'
        required: false
        schema:
          type: string
          format: date
      - name: scheduled_date_to
        in: query
        description: 'Latest campaign schedule date (inclusive).

          - Format: MM-DD-YYYY

          - Cannot be combined with `scheduled_time_from` / `scheduled_time_to`.'
        required: false
        schema:
          type: string
          format: date
      - name: scheduled_time_from
        in: query
        description: 'Earliest campaign schedule timestamp (inclusive).

          - Format: ISO 8601 datetime (e.g., `2026-03-01T00:00:00Z`)

          - Cannot be combined with `scheduled_date_from` / `scheduled_date_to`.'
        required: false
        schema:
          type: string
          format: date-time
      - name: scheduled_time_to
        in: query
        description: 'Latest campaign schedule timestamp (inclusive).

          - Format: ISO 8601 datetime (e.g., `2026-03-31T23:59:59Z`)

          - Cannot be combined with `scheduled_date_from` / `scheduled_date_to`.'
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignLookupResponse'
        '400':
          description: Bad Request - Invalid request parameters or validation error
          content:
            application/json:
              example:
                field_name:
                - Field related error message.
        '401':
          description: Unauthorized - Authentication credentials were not provided or are invalid
          content:
            application/json:
              example:
                detail: Authentication credentials were not provided.
        '403':
          description: Forbidden - You do not have permission to perform this action
          content:
            application/json:
              example:
                detail: You do not have permission for company 123
        '404':
          description: Not Found - The requested resource was not found
          content:
            application/json:
              example:
                detail: Not found.
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              example:
                detail: Request was throttled. Expected available in 60 seconds.
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              example:
                detail: Internal server error.
      tags:
      - SAT
  /sat/{company_id}/campaigns/{campaign_id}/:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    - name: campaign_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: Get Campaign Details
      description: <b>Scopes:</b><ul><li>company.view</li><li>partner.company.view</li></ul>
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDetailsResponse'
        '401':
          description: Unauthorized - Authentication credentials were not provided or are invalid
          content:
            application/json:
              example:
                detail: Authentication credentials were not provided.
        '403':
          description: Forbidden - You do not have permission to perform this action
          content:
            application/json:
              example:
                detail: You do not have permission for company 123
        '404':
          description: Not Found - The requested resource was not found
          content:
            application/json:
              example:
                detail: Not found.
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              example:
                detail: Request was throttled. Expected available in 60 seconds.
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              example:
                detail: Internal server error.
      tags:
      - SAT
    delete:
      operationId: Delete Campaign
      description: Delete a campaign.<b>Scopes:</b><ul><li>company.edit</li><li>partner.company.edit</li></ul>
      responses:
        '204':
          description: No Content - Campaign successfully deleted
        '401':
          description: Unauthorized - Authentication credentials were not provided or are invalid
          content:
            application/json:
              example:
                detail: Authentication credentials were not provided.
        '403':
          description: Forbidden - You do not have permission to perform this action
          content:
            application/json:
              example:
                detail: You do not have permission for company 123
        '404':
          description: Not Found - The requested resource was not found
          content:
            application/json:
              example:
                detail: Not found.
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              example:
                detail: Request was throttled. Expected available in 60 seconds.
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              example:
                detail: Internal server error.
      tags:
      - SAT
  /sat/{company_id}/campaigns/{campaign_id}/approve/:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    - name: campaign_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: Approve Campaign
      summary: Approve a draft campaign.
      description: 'Approves a campaign in DRAFT or PENDING status, making it ready for execution.

        The campaign must pass various validation checks including license validation,

        participant count validation, and scenario/training validation based on flow type.<b>Scopes:</b><ul><li>company.edit</li><li>partner.company.edit</li></ul>'
      responses:
        '200':
          description: OK - Campaign successfully approved
        '400':
          description: Bad Request - Invalid request parameters or validation error
          content:
            application/json:
              example:
                field_name:
                - Field related error message.
        '401':
          description: Unauthorized - Authentication credentials were not provided or are invalid
          content:
            application/json:
              example:
                detail: Authentication credentials were not provided.
        '403':
          description: Forbidden - You do not have permission to perform this action
          content:
            application/json:
              example:
                detail: You do not have permission for company 123
        '404':
          description: Not Found - The requested resource was not found
          content:
            application/json:
              example:
                detail: Not found.
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              example:
                detail: Request was throttled. Expected available in 60 seconds.
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              example:
                detail: Internal server error.
      tags:
      - SAT
  /sat/{company_id}/campaigns/{campaign_id}/stop/:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    - name: campaign_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: Stop Campaign
      summary: Stop an active campaign.
      description: Stops an active campaign by stopping email sending and event tracking.<b>Scopes:</b><ul><li>company.edit</li><li>partner.company.edit</li></ul>
      responses:
        '200':
          description: OK - Campaign successfully stopped
        '400':
          description: Bad Request - Invalid request parameters or validation error
          content:
            application/json:
              example:
                field_name:
                - Field related error message.
        '401':
          description: Unauthorized - Authentication credentials were not provided or are invalid
          content:
            application/json:
              example:
                detail: Authentication credentials were not provided.
        '403':
          description: Forbidden - You do not have permission to perform this action
          content:
            application/json:
              example:
                detail: You do not have permission for company 123
        '404':
          description: Not Found - The requested resource was not found
          content:
            application/json:
              example:
                detail: Not found.
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              example:
                detail: Request was throttled. Expected available in 60 seconds.
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              example:
                detail: Internal server error.
      tags:
      - SAT
  /sat/{company_id}/cta/:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: Get call for action pages
      description: <p>Retrieve a paginated list of call for action pages available for the specified company. The endpoint returns system pages, public pages, company-owned pages, and brand owner pages (if the company is part of a brand). Results can be filtered by search term. </p><b>Scopes:</b><ul><li>company.view</li><li>partner.company.view</li></ul>
      parameters:
      - name: page
        in: query
        description: 'Page number for pagination (default: 1)'
        required: false
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: page_size
        in: query
        description: 'Number of items per page (default: 25, max: 50)'
        required: false
        schema:
          type: integer
          default: 25
          maximum: 50
          minimum: 1
      - name: search
        in: query
        description: Search term to filter call for action pages by name
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved call for action pages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallForAction'
              example:
                page: 1
                total_pages: 2
                total_count: 35
                data:
                - id: 1
                  name: Example Call for Action
                  page_title: Example Title
                  content: <html><form>...</form></html>
                  is_system: true
                  is_public: true
                  last_updated: '2023-01-16T09:45:32.051421Z'
                  tags: System
                  company_id: null
        '400':
          description: Bad Request - Invalid request parameters or validation error
          content:
            application/json:
              example:
                field_name:
                - Field related error message.
        '404':
          description: Company was not found
          content:
            application/json:
              example:
              - message: Company not found
        '403':
          description: Permission Denied
          content:
            application/json:
              example:
              - detail: Missing JWT
              - detail: You do not have permission to perform this action.
              - message: You do not have permission for company <company_id>
        '429':
          description: Too many requests
          content:
            application/json:
              example:
              - detail: Request was throttled. Expected available in 60 seconds.
      tags:
      - SAT
  /sat/{company_id}/landing-pages/:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: Get landing pages
      summary: Get landing pages for a company.
      description: 'Returns a paginated list of landing pages that are available

        for the specified company. This includes:

        - System landing pages

        - Company-owned landing pages

        - Brand owner''s landing pages (if company is part of a brand)<b>Scopes:</b><ul><li>company.view</li><li>partner.company.view</li></ul>'
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          default: 25
          maximum: 50
          minimum: 1
      - name: locale_ids
        in: query
        description: 'Filter by locale IDs.

          - Use numeric identifiers from the locale catalog

          - If not provided, company''s selected locales will be used'
        required: false
        schema:
          type: array
          items:
            type: integer
      - name: search
        in: query
        required: false
        schema:
          type: string
      - name: created_by
        in: query
        description: 'Filter by created by codes.

          - `1` = System

          - `2` = Company

          - `3` = MSP

          - Provide one or both codes'
        required: false
        schema:
          type: array
          items:
            type: integer
            enum:
            - 1
            - 2
            - 3
      responses:
        '200':
          description: Successfully Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LandingPages'
        '400':
          description: Bad Request - Invalid request parameters or validation error
          content:
            application/json:
              example:
                field_name:
                - Field related error message.
        '404':
          description: Company was not found
          content:
            application/json:
              example:
              - message: Company not found
        '403':
          description: Permission Denied
          content:
            application/json:
              example:
              - detail: Missing JWT
              - detail: You do not have permission to perform this action.
              - message: You do not have permission for company <company_id>
        '429':
          description: Too many requests
          content:
            application/json:
              example:
              - detail: Request was throttled. Expected available in 60 seconds.
      tags:
      - SAT
  /sat/{company_id}/participants/:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: Get Participants List
      summary: Get list of campaign participants grouped by categories.
      description: 'Returns participants data organized by departments, cities, countries,

        titles, tags, featured groups, segments, and awareness levels.<b>Scopes:</b><ul><li>company.view</li><li>partner.company.view</li></ul>'
      responses:
        '200':
          description: Successful response containing participants data organized by categories (departments, cities, countries, etc.) with participant counts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantsListResponse'
              example:
                all_company: 150
                names:
                  john.doe@example.com:
                    full_name: John Doe
                    mail: john.doe@example.com
                  jane.smith@example.com:
                    full_name: Jane Smith
                    mail: jane.smith@example.com
                departments:
                  Engineering: 45
                  Sales: 30
                  Marketing: 25
                  HR: 20
                  Finance: 15
                  Operations: 15
                cities:
                  New York: 60
                  San Francisco: 40
                  London: 30
                  Tel Aviv: 20
                countries:
                  United States: 100
                  United Kingdom: 30
                  Israel: 20
                titles:
                  Software Engineer: 25
                  Sales Manager: 15
                  Marketing Director: 10
                  HR Manager: 8
                tags:
                  Executive: 5
                  Remote: 50
                  On-site: 100
                featured_groups:
                  All Executives: 5
                  All Managers: 20
                segments:
                  High Risk Users: 10
                  New Employees: 15
                awareness_levels:
                  Beginner Level: 30
                  Mid Level: 80
                  Expert Level: 40
        '400':
          description: Bad Request - Invalid request parameters or validation error
          content:
            application/json:
              example:
                field_name:
                - Field related error message.
        '401':
          description: Unauthorized - Authentication credentials were not provided or are invalid
          content:
            application/json:
              example:
                detail: Authentication credentials were not provided.
        '403':
          description: Forbidden - You do not have permission to perform this action
          content:
            application/json:
              example:
                detail: You do not have permission for company 123
        '404':
          description: Company was not found
          content:
            application/json:
              example:
              - message: Company not found
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              example:
                detail: Request was throttled. Expected available in 60 seconds.
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              example:
                detail: Internal server error.
      tags:
      - SAT
    post:
      operationId: Calculate Participants
      summary: Calculate participants based on include/exclude filters.
      description: 'Returns a list of participant candidates matching the specified

        include and exclude criteria, along with metadata including total count,

        locale IDs, and awareness levels distribution.<b>Scopes:</b><ul><li>company.edit</li><li>partner.company.edit</li></ul>'
      responses:
        '200':
          description: Successful response containing calculated participants with metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantsCalculateResponse'
              example:
                meta:
                  count: 150
                  locale_ids:
                  - 1
                  - 2
                  - 3
                  awareness_levels:
                    beginner: 30
                    mid: 80
                    expert: 40
                items:
                - id: 1
                  first_name: John
                  last_name: Doe
                  email: john.doe@example.com
                - id: 2
                  first_name: Jane
                  last_name: Smith
                  email: jane.smith@example.com
        '400':
          description: Bad Request - Invalid request parameters or validation error
          content:
            application/json:
              example:
                field_name:
                - Field related error message.
        '401':
          description: Unauthorized - Authentication credentials were not provided or are invalid
          content:
            application/json:
              example:
                detail: Authentication credentials were not provided.
        '403':
          description: Forbidden - You do not have permission to perform this action
          content:
            application/json:
              example:
                detail: You do not have permi

# --- truncated at 32 KB (106 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ironscales/refs/heads/main/openapi/ironscales-sat-api-openapi.yml