Forsta Translations API

openapi: 3.2.0
info:
  title: Decipher Rest Translations 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: Translations
paths:
  /translation:
    post:
      operationId: createTranslation
      summary: Post translations
      description: 'Add in translations for a specified survey and language. When translations

        are added any reservation for that survey and language combination are

        removed. NOTE: if sourceString no longer matches the text in XML, the

        translation will be accepted but the ID will appear in the "oudated" output

        array.'
      tags:
      - Translations
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                targetLanguages:
                  description: 'An array containing a string of the language to be translated

                    '
                  type: array
                  items:
                    type: string
                requests:
                  description: 'A list of objects containing a document id and a list of elements.

                    '
                  type: array
                  items:
                    type: object
                    properties:
                      documentId:
                        type: string
                        format: survey path
                      elements:
                        type: array
                        items:
                          type: object
                          properties:
                            elementId:
                              type: string
                            sourceString:
                              type: string
                            targetString:
                              type: string
                postbackJobId:
                  description: 'The jobId for the reservation that was created for this document.

                    '
                  type: string
                aggregateDupes:
                  description: 'Defaults to false. Set to true if dupes were aggregated

                    when pulling translations.

                    '
                  type: boolean
              required:
              - targetLanguages
              - requests
              - postbackJobId
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  changed:
                    type: integer
                  identical:
                    type: integer
                  invalid_label:
                    type: array
                    items:
                      type: string
                  outdated:
                    type: array
                    items:
                      type: string
              example:
                changed: 10
                identical: 0
                invalid_label: []
                outdated: []
    get:
      operationId: getTranslation
      summary: Get translations
      description: 'Translations are returned for the first survey found or the one

        specified by `start`. A `lastRetrievedId` argument is returned with the

        result that can be specified as the start to get translations for the

        next survey.


        This endpoint can gather translations for multiple surveys but requires the

        survey attribute `tapiDue`.'
      tags:
      - Translations
      parameters:
      - name: start
        description: 'If specified, translations for the survey provided will be returned

          otherwise it will be the first survey found

          '
        in: query
        required: false
        schema:
          type: string
      - name: paths
        description: 'An array of paths to include. If not provided all surveys with

          tapiDue set are considered. tapiDue is set as a survey attribute

          (not an API param) using the date format: `tapiDue="2023-09-13"`


          The date within the survey attribute is relatively arbitrary but may

          help prioritize what gets translated first.

          '
        in: query
        required: false
        schema:
          type: array
      - name: aggregateDupes
        description: 'Defaults to false. Set to true if duplicate translations should

          only appear once.

          '
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  expectedDueDate:
                    type: integer
                    format: unix timestamp
                  lastRetrievedId:
                    type: string
                    format: survey path
                  postbackJobId:
                    type: string
                  projectId:
                    type: string
                  requests:
                    type: array
                    items:
                      type: object
                      properties:
                        documentId:
                          type: string
                          format: survey path
                        elements:
                          type: array
                          items:
                            type: object
                            properties:
                              elementId:
                                type: string
                              sourceString:
                                type: string
                              targetString:
                                type: string
                        icuFormat:
                          type: boolean
                  schemaId:
                    type: string
                  sourceLanguage:
                    type: string
                  targetLanguages:
                    type: array
                    items:
                      type: string
              example:
                expectedDueDate: 1355270400
                lastRetrievedId: selfserve/53a/171202
                postbackJobId: abc123
                projectId: abc123
                requests:
                - documentId: selfserve/53a/171201
                  elements:
                  - elementId: samplesources,1,invalid
                    sourceString: The URL above does not include the proper information to be included in this survey. Please review your invite email for the proper URL, and contact the individual specified if problems persist.
                    targetString: The URL above does not include the proper information to be included in this survey. Please review your invite email for the proper URL, and contact the individual specified if problems persist.
                  - elementId: samplesources,1,completed
                    sourceString: Thank you for your interest but it seems you have already finished this survey.
                    targetString: Thank you for your interest but it seems you have already finished this survey.
                  - elementId: samplesources,1,inuse
                    sourceString: Our records show that you are already taking this survey. If that's not correct, please wait 15 minutes and refresh this page. Thank you.
                    targetString: Our records show that you are already taking this survey. If that's not correct, please wait 15 minutes and refresh this page. Thank you.
                  icuFormat: false
                schemaId: v1
                sourceLanguage: en-US
                targetLanguages: []
components:
  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