openapi: 3.2.0
info:
  title: Decipher Rest Participant Sources 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: Participant Sources
paths:
  /surveys/{survey}/sample/{listId}/links:
    get:
      operationId: getSurveySampleLinks
      summary: Get participant sources
      description: Retrieves a list of links for all uploaded external sample.
      tags:
      - Participant Sources
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: listId
        description: the `list` value of the participant source.
        example: '299'
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  links:
                    type: object
                    description: an object mapping participant souce identifier to link url
              examples:
                response:
                  value:
                    links:
                      respondent.1415833683.1: http://yourserver.decipherinc.com/survey/selfserve/84d/141100?id=respondent.1415833683.1&list=299
                      respondent.1415833683.2: http://yourserver.decipherinc.com/survey/selfserve/84d/141100?id=respondent.1415833683.2&list=299
                      respondent.1415833683.3: http://yourserver.decipherinc.com/survey/selfserve/84d/141100?id=respondent.1415833683.3&list=299
                      respondent.1415833683.4: http://yourserver.decipherinc.com/survey/selfserve/84d/141100?id=respondent.1415833683.4&list=299
                      respondent.1415833683.5: http://yourserver.decipherinc.com/survey/selfserve/84d/141100?id=respondent.1415833683.5&list=299
                      respondent1: http://yourserver.decipherinc.com/survey/selfserve/84d/141100?id=respondent1&list=299
                      respondent2: http://yourserver.decipherinc.com/survey/selfserve/84d/141100?id=respondent2&list=299
                      respondent3: http://yourserver.decipherinc.com/survey/selfserve/84d/141100?id=respondent3&list=299
                      respondent4: http://yourserver.decipherinc.com/survey/selfserve/84d/141100?id=respondent4&list=299
                      respondent5: http://yourserver.decipherinc.com/survey/selfserve/84d/141100?id=respondent5&list=299
  /surveys/{survey}/samplesources/{listId}/sign:
    post:
      operationId: createSurveySamplesourceSign
      summary: Create signed links
      description: Add signatures to survey links for a samplesource with a keyring.
      tags:
      - Participant Sources
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: listId
        description: The `list` value of the participant source. A keyring must be attached to it.
        example: '299'
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                urls:
                  description: Array of URLs to sign.
                  type: array
                  items:
                    type: string
                    example: http://yourserver.decipherinc.com/survey/selfserve/123/140001?list=299
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                description: Array of signed URLs.
                items:
                  description: Signed URL
                  type: string
                  example: http://yourserver.decipherinc.com/survey/selfserve/123/140001?list=299&_k=1000&_s=589eeddfc25911255f69c5a5ddef58ece72dcd8b
        '400':
          description: Samplesource not found or no keyring for samplesource
          content:
            application/json:
              schema:
                type: object
                properties:
                  $error:
                    description: A description of the error.
                    type: string
                    example: no keyring for samplesource
                  $code:
                    description: The HTTP error code.
                    type: integer
                    example: 400
                  extra:
                    description: Extra information about the error.
                    type: string
                    example: null
        '404':
          description: Survey not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  $error:
                    description: A description of the error.
                    type: string
                    example: 'Cannot load survey ''selfserve/123/140001'' specified as survey: does not exist'
                  $code:
                    description: The HTTP error code.
                    type: integer
                    example: 404
                  extra:
                    description: Extra information about the error.
                    type: string
                    example: null
  /surveys/{survey}/samplesources/{listId}/verify:
    post:
      operationId: createSurveySamplesourceVerify
      summary: Verify signed links
      description: Verify signatures for survey links for a samplesource with a keyring.
      tags:
      - Participant Sources
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: listId
        description: The `list` value of the participant source. A keyring must be attached to it.
        example: '299'
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                urls:
                  description: Array of URLs to verify.
                  type: array
                  items:
                    type: string
                    example: http://yourserver.decipherinc.com/survey/selfserve/123/140001?list=299&_k=1000&_s=589eeddfc25911255f69c5a5ddef58ece72dcd8b
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                description: An array of objects, one for the incoming array containing the results.
                items:
                  type: object
                  example:
                    valid: true
                    error: null
                  properties:
                    valid:
                      type: boolean
                      description: true/false
                      example: true
                    error:
                      type: string
                      description: textual error description
                      example: null
        '400':
          description: Samplesource not found or no keyring for samplesource
          content:
            application/json:
              schema:
                type: object
                properties:
                  $error:
                    description: A description of the error.
                    type: string
                    example: no keyring for samplesource
                  $code:
                    description: The HTTP error code.
                    type: integer
                    example: 400
                  extra:
                    description: Extra information about the error.
                    type: string
                    example: null
        '404':
          description: Survey not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  $error:
                    description: A description of the error.
                    type: string
                    example: 'Cannot load survey ''selfserve/123/140001'' specified as survey: does not exist'
                  $code:
                    description: The HTTP error code.
                    type: integer
                    example: 404
                  extra:
                    description: Extra information about the error.
                    type: string
                    example: 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