IRONSCALES Campaigns API

openapi: 3.2.0
info:
  title: IRONSCALES Management Campaigns API
  description: The Campaigns 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: Campaigns
paths:
  /campaigns/{company_id}/details:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: Get campaigns details
      description: "Get campaigns details <br/>\nEach page contains 25 campaigns results<br/>\n<br/><b>Scopes:</b>\n<ul>\n    <li>partner.all</li>\n    <li>partner.company.view</li>\n    <li>company.view</li>\n</ul>\n\nStatuses mapping to UI values:\n<ul>\n    <li>Draft (0) -> Draft</li>\n    <li>Collecting (1) -> Active</li>\n    <li>Closed (2) -> Completed</li>\n    <li>Approved by User (3) -> Pending</li>\n    <li>Sending (4) -> Active</li>\n    <li>Inactive (5) -> Inactive</li>\n</ul>"
      parameters:
      - name: company_id
        in: path
        description: Company ID
        required: true
        schema:
          type: integer
      - name: period
        in: query
        description: "<p>Applied over campaign creation date</p>\n                                <ul>\n                                <li>0 - Last 24 hours</li>\n                                <li>1 - Last 7 days</li>\n                                <li>2 - Last 90 days</li>\n                                <li>3 - Last 180 days</li>\n                                <li>4 - Last 360 days</li>\n                                <li>5 - Current year to date</li>\n                                <li>6 - All time</li>\n                                </ul>\n"
        required: true
        schema:
          type: integer
      - name: status
        in: query
        description: "<ul>\n                                <li>0 - Draft</li>\n                                <li>1 - Collecting</li>\n                                <li>2 - Closed</li>\n                                <li>3 - Approved</li>\n                                <li>4 - Sending</li>\n                                </ul>\n                                <p>Can be multiple statuses: status=0&status=2&status=3...</p>\n"
        required: false
        schema:
          type: array
          items:
            type: integer
          default:
          - 2
      - name: page
        in: query
        description: Page number
        required: false
        schema:
          type: integer
          default: 1
      - name: name
        in: query
        description: Optional, search by partial campaign name
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successfully Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDetailsPage'
        '400':
          description: Missing or wrong period
          content:
            application/json:
              example:
                error_message: explanation
        '404':
          description: Company or campaign does not exist
        '403':
          description: No permissions
      tags:
      - Campaigns
  /campaigns/{company_id}/participants-actions/:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    put:
      operationId: Perform participants action
      description: Perform action on campaign participants.<br/><b>Scopes:</b><ul><li>partner.company.edit</li><li>company.edit</li></ul>
      parameters:
      - name: campaign_id
        in: query
        description: Campaign ID
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    description: Indicates if the action was successful
                    type: boolean
        '400':
          description: Invalid request
          content:
            application/json:
              example:
                message: explanation
        '403':
          description: No permissions
        '413':
          description: Too many emails
          content:
            application/json:
              example:
                message: The emails list exceeds the maximum allowed limit of 300.
      tags:
      - Campaigns
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipantsActionsRequest'
        required: true
  /campaigns/{company_id}/participants-details:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: Get campaign participants details
      description: "Get campaign participants details <br/>\nEach page contains 100 participants<br/>\n<br/><b>Scopes:</b>\n<ul>\n    <li>partner.all</li>\n    <li>partner.company.view</li>\n    <li>company.view</li>\n</ul>"
      parameters:
      - name: company_id
        in: path
        description: Company ID
        required: true
        schema:
          type: integer
      - name: campaign_id
        in: query
        description: Campaign ID
        required: true
        schema:
          type: integer
      - name: page
        in: query
        description: Page number
        required: false
        schema:
          type: integer
          default: 1
      responses:
        '200':
          description: Successfully Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignParticipantsDetailsPage'
        '400':
          description: Missing or a wrong Campaign
          content:
            application/json:
              example:
                error_message: explanation
        '404':
          description: Company or page not found
        '403':
          description: No permissions
      tags:
      - Campaigns
components:
  schemas:
    CampaignParticipantsDetails:
      type: object
      properties:
        internalID:
          title: Internalid
          type: string
          minLength: 1
        name:
          title: Name
          type: string
          minLength: 1
        displayName:
          title: Displayname
          type: string
          minLength: 1
        lastUpdate:
          title: Last Update
          description: date-time format %b %d, %Y %H:%M
          type:
          - string
          - 'null'
          format: date-time
        title:
          title: Title
          type: string
          minLength: 1
        department:
          title: Department
          type: string
          minLength: 1
        company:
          title: Company
          type: string
          minLength: 1
        manager:
          title: Manager
          type: string
          minLength: 1
        office:
          title: Office
          type: string
          minLength: 1
        country:
          title: Country
          type:
          - string
          - 'null'
        city:
          title: City
          type:
          - string
          - 'null'
        sentAt:
          title: Sent At
          description: date-time format %b %d, %Y %H:%M
          type:
          - string
          - 'null'
          format: date-time
        opened:
          title: Opened
          type: string
          enum:
          - 'Yes'
          - 'No'
        openedAt:
          title: Opened At
          description: date-time format %b %d, %Y %H:%M
          type:
          - string
          - 'null'
          format: date-time
        enteredDetails:
          title: Entereddetails
          type: string
          enum:
          - 'Yes'
          - 'No'
        trainingModule:
          title: Trainingmodule
          type: string
          minLength: 1
        trainingVideoStarted:
          title: Trainingvideostarted
          type: string
          enum:
          - 'Yes'
          - 'No'
        awarenessLevel:
          title: Awarenesslevel
          type:
          - string
          - 'null'
          enum:
          - Beginner Level
          - Mid Level
          - Expert Level
          readOnly: true
        customTags:
          title: Customtags
          type: string
          readOnly: true
          minLength: 1
        reported:
          title: Reported
          type:
          - string
          - 'null'
          enum:
          - 'Yes'
          - 'No'
        reportedTime:
          title: Reported Time
          description: date-time format %b %d, %Y %H:%M
          type:
          - string
          - 'null'
          format: date-time
        read:
          title: Read
          type: string
          enum:
          - 'Yes'
          - 'No'
        clicked:
          title: Clicked
          type:
          - string
          - 'null'
          enum:
          - 'Yes'
          - 'No'
        clickedTime:
          title: Clicked Time
          description: date-time format %b %d, %Y %H:%M
          type:
          - string
          - 'null'
          format: date-time
        resendTrainingDates:
          description: date-time format %b %d, %Y %H:%M
          type: array
          items:
            type: string
            format: date-time
        deleted:
          title: Deleted
          type:
          - string
          - 'null'
          enum:
          - 'Yes'
          - 'No'
        trained:
          title: Trained
          type:
          - string
          - 'null'
          enum:
          - Postponed
          - Manually trained
          - 'Yes'
          - 'No'
          - Started, not completed
          - Not started
          - N/A
          - Scheduled to send
          readOnly: true
        trainingCompletionDate:
          title: Training Completion Date
          description: date-time format %b %d, %Y %H:%M
          type:
          - string
          - 'null'
          format: date-time
        trainingScore:
          title: Trainingscore
          type:
          - integer
          - 'null'
          readOnly: true
        trainingDuration:
          title: Trainingduration
          type: integer
        trainingStartedOn:
          title: Training Started On
          description: date-time format %b %d, %Y %H:%M
          type:
          - string
          - 'null'
          format: date-time
        email:
          title: Email
          type: string
          minLength: 1
        template:
          title: Template
          type: string
          readOnly: true
          minLength: 1
        userIp:
          title: Userip
          type: string
          minLength: 1
    ParticipantsActionsFilters:
      type: object
      properties:
        emails:
          description: A list of recipient emails to filter by. Limited to 300 items.
          type: array
          items:
            type: string
            format: email
            minLength: 1
          maxItems: 300
    ParticipantsActionsRequest:
      required:
      - filters
      - action
      type: object
      properties:
        filters:
          $ref: '#/components/schemas/ParticipantsActionsFilters'
        action:
          title: Action
          description: 'The action to perform on participants:<br/>1 - Reported: Mark as reported<br/>2 - Manually Trained: Set training status to manually trained<br/>3 - Postponed: Set training status to postponed (requires expiration_date)<br/>4 - Revert Training: Revert Postponed and Manually Trained statuses only<br/>5 - Revert Reported: Revert Reported status set via appapi only'
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          - 5
        expiration_date:
          title: Expiration date
          description: The expiration date of the Postponed Training status (ISO 8601 format, e.g. '2024-01-15'). Only valid when action is 3 (Postponed).
          type:
          - string
          - 'null'
          format: date
    CampaignParticipantsDetailsPage:
      required:
      - page
      - total_pages
      - campaign_id
      - participants
      type: object
      properties:
        page:
          title: Page
          type: integer
        total_pages:
          title: Total pages
          type: integer
        campaign_id:
          title: Campaign id
          type: integer
        participants:
          type: array
          items:
            $ref: '#/components/schemas/CampaignParticipantsDetails'
    CampaignDetails:
      required:
      - campaignID
      - campaignName
      - language
      - companyId
      type: object
      properties:
        campaignID:
          title: Campaignid
          type: integer
        campaignName:
          title: Campaignname
          type: string
          minLength: 1
        campaignStatus:
          title: Campaignstatus
          type: string
          readOnly: true
          minLength: 1
        flowType:
          title: Flowtype
          type: string
          readOnly: true
          minLength: 1
        language:
          title: Language
          type: string
          minLength: 1
        maxEmailPerDay:
          title: Maxemailperday
          description: 0 - Unlimited
          type: integer
          readOnly: true
        endDate:
          title: Enddate
          type: string
          format: date-time
          readOnly: true
        launchDate:
          title: Launchdate
          type: string
          format: date-time
          readOnly: true
        emailsSent:
          title: Emailssent
          type: integer
          readOnly: true
        participants:
          title: Participants
          type: integer
          readOnly: true
        emailsBounced:
          title: Emailsbounced
          type: integer
          readOnly: true
        numberOfClickedParticipants:
          title: Numberofclickedparticipants
          type: integer
          readOnly: true
        numberOfTrainedParticipants:
          title: Numberoftrainedparticipants
          type: integer
          readOnly: true
        numberOfTrainedParticipatns:
          title: Numberoftrainedparticipatns
          type: integer
          readOnly: true
        numberOfReportedParticipants:
          title: Numberofreportedparticipants
          type: integer
          readOnly: true
        numberOfReadParticipants:
          title: Numberofreadparticipants
          type: integer
          readOnly: true
        numberOfDeleted:
          title: Numberofdeleted
          type: integer
          readOnly: true
        attackReadinessFirstReport:
          title: Attackreadinessfirstreport
          type: string
          readOnly: true
          minLength: 1
        attackReadinessMitigationTime:
          title: Attackreadinessmitigationtime
          type: string
          readOnly: true
          minLength: 1
        attackReadinessLuredBeforeMitigation:
          title: Attackreadinessluredbeforemitigation
          type: string
          readOnly: true
          minLength: 1
        attackReadinessReportsToMitigate:
          title: Attackreadinessreportstomitigate
          type: string
          readOnly: true
          minLength: 1
        companyId:
          title: Companyid
          type: integer
        randomized:
          title: Randomized
          type: boolean
          readOnly: true
    CampaignDetailsPage:
      required:
      - page
      - total_pages
      - campaigns
      type: object
      properties:
        page:
          title: Page
          type: integer
        total_pages:
          title: Total pages
          type: integer
        campaigns:
          type: array
          items:
            $ref: '#/components/schemas/CampaignDetails'
  securitySchemes:
    JWT:
      type: apiKey
      name: Authorization
      in: header