Forsta Campaigns API

openapi: 3.2.0
info:
  title: Decipher Rest Campaigns API
  version: '1.0'
  description: The Decipher REST API allows comprehensive automation of your private or shared Decipher instance.
servers:
- url: https://{server}/api/v1
  description: Replace server with your instance domain.
  variables:
    server:
      default: selfserve.decipherinc.com
      description: Server domain
security:
- APIKey: []
tags:
- name: Campaigns
paths:
  /surveys/{survey}/campaigns:
    get:
      operationId: getSurveyCampaigns
      summary: Get campaigns
      description: 'Returns a list of basic information about the Campaign Manager campaigns

        associated with this survey.'
      tags:
      - Campaigns
      parameters:
      - $ref: '#/components/parameters/survey'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      description: Name of campaign
                      type: string
                    replyTo:
                      description: 'Reply-To email address used when sending emails

                        '
                      type: string
                    fromName:
                      description: Sender name used when sending emails
                      type: string
                    fromAddress:
                      description: 'Sender email address used when sending emails

                        '
                      type: string
                    link:
                      description: Survey link
                      type: string
                    subject:
                      description: Subject used when sending emails
                      type: string
                    requireSeed:
                      description: 'Whether or not the campaign is required to use seed sends. When `false`,

                        the campaign cannot be edited or launched via Campaign Manager.

                        '
                      default: true
                      type: boolean
                    oneClickOptOutUrl:
                      description: 'One-Click Opt-Out URL, used in email headers with One-Click Unsubscribe

                        '
                      type: string
    post:
      operationId: createSurveyCampaign
      summary: Create campaign
      description: 'Creates a new campaign for the given survey.


        A campaign created through this endpoint allows sends to be scheduled while

        other sends are already scheduled.'
      tags:
      - Campaigns
      parameters:
      - $ref: '#/components/parameters/survey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Name of campaign
                  type: string
                replyTo:
                  description: 'Reply-To email address to use when sending emails, must be a

                    valid email address

                    '
                  type: string
                fromName:
                  description: Sender name to use when sending emails
                  type: string
                fromAddress:
                  description: 'Sender email address to use when sending emails, must be an email

                    address that the user and project has permission to send emails

                    from

                    '
                  type: string
                link:
                  description: Survey link, must be a link to the appropriate survey
                  type: string
                subject:
                  description: Subject to use when sending emails
                  type: string
                requireSeed:
                  description: 'Requires the campaign to use seed sends. When `false`, the

                    campaign cannot be edited or launched via Campaign Manager.

                    '
                  default: true
                  type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
  /surveys/{survey}/campaigns/{campaign}:
    get:
      operationId: getSurveyCampaign
      summary: Get campaign
      description: Returns basic information about an individual campaign.
      tags:
      - Campaigns
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: campaign
        description: ID of the campaign
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    description: Name of campaign
                    type: string
                  replyTo:
                    description: 'Reply-To email address used when sending emails

                      '
                    type: string
                  fromName:
                    description: Sender name used when sending emails
                    type: string
                  fromAddress:
                    description: 'Sender email address used when sending emails

                      '
                    type: string
                  link:
                    description: Survey link
                    type: string
                  subject:
                    description: Subject used when sending emails
                    type: string
                  requireSeed:
                    description: 'Whether or not the campaign is required to use seed sends. When `false`,

                      the campaign cannot be edited or launched via Campaign Manager.

                      '
                    default: true
                    type: boolean
                  oneClickOptOutUrl:
                    description: 'One-Click Opt-Out URL, used in email headers with One-Click Unsubscribe

                      '
                    type: string
    put:
      operationId: updateSurveyCampaign
      summary: Edit campaign
      description: 'Modifies `name`, `replyTo`, `fromName`, `fromAddress`, `link`,

        `subject`, and/or `requireSeed` of an individual campaign.'
      tags:
      - Campaigns
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: campaign
        description: ID of the campaign
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Name of campaign
                  type: string
                replyTo:
                  description: 'Reply-To email address to use when sending emails, must be a

                    valid email address

                    '
                  type: string
                fromName:
                  description: Sender name to use when sending emails
                  type: string
                fromAddress:
                  description: 'Sender email address to use when sending emails, must be an email

                    address that the user and project has permission to send emails

                    from

                    '
                  type: string
                link:
                  description: Survey link, must be a link to the appropriate survey
                  type: string
                subject:
                  description: Subject to use when sending emails
                  type: string
                requireSeed:
                  description: 'Requires the campaign to use seed sends. Cannot be changed once a

                    soft send is done.

                    '
                  type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
    delete:
      operationId: deleteSurveyCampaign
      summary: Delete campaign
      description: Deletes and individual campaign as well as its seed and list files.
      tags:
      - Campaigns
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: campaign
        description: ID of the campaign.
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                force:
                  description: Flag to force campaign deletion on surveys with ADB.
                  default: false
                  type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  $error:
                    type: string
                    description: error description
                  $code:
                    type: integer
                    description: http error code (400)
                  extra:
                    type:
                    - string
                    - 'null'
              example:
                $error: Cannot delete campaign for a survey with ADB enabled. Use 'force' to override.
                $code: 400
                extra: null
components:
  parameters:
    survey:
      name: survey
      in: path
      required: true
      description: The survey path.
      example: selfserve/1a/123456
      schema:
        type: string
        format: uri
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: x-apikey
      description: 'In order to access the api, you''ll need to generate an API key. Refer to the

        instructions [here](/docs/decipher/api#section/API-Keys) to generate and

        configure an API key with the appropriate permission sets. You can generate

        as many keys as required.


        Configure each request to include your API key in the request header. For example:


        ```

        x-apikey: dp48ss3mgsaucyjtybxw728h7s4cgnwzhejtszdwhf4xpe8yhmtdwpk2ntdhtwbs

        ```

        '
x-tagGroups:
- name: Autoclose
  tags:
  - Autoclose
- name: Data Input and Output
  tags:
  - Data
  - Data Feed
  - Response Summary
  - Modifying Data
  - Datasources
  - Datasources Data
  - Umerge
- name: Survey Metadata
  tags:
  - Simulated Data
  - Survey State
  - Survey Evaluate
  - Survey Quotas
  - Survey Files
  - Survey Warnings
  - Survey Terms
  - Survey Subscribers
  - Survey Users
  - Survey Tasks
- name: Panels
  tags:
  - Panel Data
  - Panel Datapoints
  - Survey Panels
- name: Research Hub
  tags:
  - Users
  - Companies
  - Categories
  - Surveys
  - Panels
  - Crosstabs
  - Archives
  - Archival Reports
  - API Keys
  - Usage
  - Warnings Summary
- name: Crosstabs
  tags:
  - Crosstabs Configuration
  - Crosstabs Execution
  - Crosstabs Nets
  - Saved Crosstabs
  - Crosstabs Table Settings
  - Crosstabs Validation
  - Crosstabs Rim Weighting
- name: Dashboards
  tags:
  - Dashboards
- name: DQ APIs
  tags:
  - DQ-Specific API Calls
  - MaxDiff API Calls
  - Discrete Choice Model API Calls
  - Media Testimonial API Calls
- name: Response Summary
  tags:
  - Share Link
- name: Sample Management
  tags:
  - Bounced Emails
  - Participant Sources
- name: Distribution
  tags:
  - Email Distribution
  - SFTP Distribution
  - Slack Distribution
- name: Campaign Manager
  tags:
  - Campaigns
  - Campaign Email Invites
  - Campaign Exports
  - Campaign Lists
  - Shared Campaign Lists
  - Campaign Sends
  - Campaign Status Lists
  - Supression Lists
- name: Question Library
  tags:
  - Company Element
  - Company Elements
  - Survey Elements
  - Survey Element Report Settings
- name: Language Manager
  tags:
  - LM Application Data
  - LM Application Translations
  - Translation Resources
  - Translations
  - Translation Deltas
  - Translation Reservations
  - Primary Survey Language
  - Other Survey Languages
  - Unused Survey Languages
- name: Project Parameters
  tags:
  - Available Project Parameters
  - Saved Project Parameters
  - Project Parameters Configuration
- name: Multi-User Editing
  tags:
  - Available Sections
  - Check Out Section
  - Check In Section
  - Sync Section
  - Section Editor
  - Abandon Section
  - Validate Section
- name: Video Management
  tags:
  - Videos
  - Watermarked Videos
- name: Miscellaneous
  tags:
  - System Information
  - Logic Nodes
  - Logic Events
  - CATI
  - Global Search
  - Miscellaneous