Voxco Questions API

openapi: 3.2.0
info:
  title: Ascribe Coder AICoder Questions API
  description: <br/>      To import this API to Postman, copy the URL from the top of this page.<br/>      Open Postman, and select Import.<br/>      In the dialog select 'Import From Link'.<br/>      Paste the URL and click Import.<br/><br/>      To use this API interactively from this page, open the POST Sessions operation below.<br/>      Click the Example Value in the Parameters section to move it to the request.<br/>      Modify the request with your credentials, then click "Try it out!"<br/>      Copy the value of the bearerToken returned in the response to the api_key text box at the top of this page.<br/>      You can now interact with the other resources on this page.<br/>      You can save the bearer token for future use without needing to POST to the Sessions resource again.
  contact:
    email: support@goascribe.com
  version: v2
servers:
- url: https://api.goascribe.us/coder/v2
  description: US Servers
- url: https://api.goascribe.eu/coder/v2
  description: EU Servers
- url: https://api-ca.goascribe.com/coder/v2
  description: CA Servers
security:
- Bearer: []
tags:
- name: Questions
paths:
  /Questions/{studyKey}:
    get:
      tags:
      - Questions
      summary: Get the Questions in a Study
      description: 'Retrieves by default all of the Questions in the Study.


        You can optionally retrieve only a sub-set of the questions, filtering by the question type or the tasks assigned to the question.'
      parameters:
      - name: studyKey
        in: path
        description: The key of the Study, which must be an integer value.
        required: true
        schema:
          type: integer
          format: int32
      - name: types
        in: query
        description: "Optional filter by Question type.\n\n            If omitted, Questions of all types are returned.\n\n            If present, a string containing these characters, the presence of which specifies the type of Question desired:\n<ul><li>c: Closed\n</li><li>d: Data\n</li><li>o: Open\n</li><li>s: Other/Specify\n</li><li>v: Value\n</li></ul>\n            For example, the value 'so' (or 'os') returns Open and Other/Specify Questions."
        schema:
          type: string
      - name: tasks
        in: query
        description: 'Optional filter by task.


          If omitted, Questions are not filtered by task.


          If present, a string containing these characters, the presence of which specified the task assigned to a Question:

          <ul><li>c: Code this Question

          </li><li>x: Crosstab this Question

          </li><li>b: Transcribe this Question

          </li><li>t: Translate this Question

          </li></ul>

          For example, the value (''ct'' or ''tc'') returns Questions with the Code or Translate tasks set.'
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/GetQuestionsResponse'
              example:
                questions:
                - key: 8753
                  codebookKey: 2357
                  id: Q1
                  countResponses: 5896
                  countResponsesCoded: 1002
                  countTranscriptions: 50
                  countTranslations: 97
                  countQualityReviewed: 0
                  tasks: cbt
                  type: o
                  label: Likes
                  text: What did you like about the product?
                  help: null
                  sortOrder: null
                  codingSource: v
                  alternativeCodingSource: b
                  externalQuestionId: null
                - key: 8754
                  codebookKey: 458
                  id: G
                  countResponses: 6336
                  countResponsesCoded: 6336
                  countTranscriptions: 0
                  countTranslations: 0
                  countQualityReviewed: 0
                  tasks: c
                  type: c
                  label: Gender
                  text: What is your gender?
                  help: null
                  sortOrder: null
                  codingSource: v
                  alternativeCodingSource: b
                  externalQuestionId: null
                errorMessage: null
            application/json:
              schema:
                $ref: '#/components/schemas/GetQuestionsResponse'
              example:
                questions:
                - key: 8753
                  codebookKey: 2357
                  id: Q1
                  countResponses: 5896
                  countResponsesCoded: 1002
                  countTranscriptions: 50
                  countTranslations: 97
                  countQualityReviewed: 0
                  tasks: cbt
                  type: o
                  label: Likes
                  text: What did you like about the product?
                  help: null
                  sortOrder: null
                  codingSource: v
                  alternativeCodingSource: b
                  externalQuestionId: null
                - key: 8754
                  codebookKey: 458
                  id: G
                  countResponses: 6336
                  countResponsesCoded: 6336
                  countTranscriptions: 0
                  countTranslations: 0
                  countQualityReviewed: 0
                  tasks: c
                  type: c
                  label: Gender
                  text: What is your gender?
                  help: null
                  sortOrder: null
                  codingSource: v
                  alternativeCodingSource: b
                  externalQuestionId: null
                errorMessage: null
            text/json:
              schema:
                $ref: '#/components/schemas/GetQuestionsResponse'
              example:
                questions:
                - key: 8753
                  codebookKey: 2357
                  id: Q1
                  countResponses: 5896
                  countResponsesCoded: 1002
                  countTranscriptions: 50
                  countTranslations: 97
                  countQualityReviewed: 0
                  tasks: cbt
                  type: o
                  label: Likes
                  text: What did you like about the product?
                  help: null
                  sortOrder: null
                  codingSource: v
                  alternativeCodingSource: b
                  externalQuestionId: null
                - key: 8754
                  codebookKey: 458
                  id: G
                  countResponses: 6336
                  countResponsesCoded: 6336
                  countTranscriptions: 0
                  countTranslations: 0
                  countQualityReviewed: 0
                  tasks: c
                  type: c
                  label: Gender
                  text: What is your gender?
                  help: null
                  sortOrder: null
                  codingSource: v
                  alternativeCodingSource: b
                  externalQuestionId: null
                errorMessage: null
    post:
      tags:
      - Questions
      summary: Create a new Question in the specified Study
      description: If the codebook key is not specified in the request a new empty codebook is created for the question and its key is returned in the response.
      parameters:
      - name: studyKey
        in: path
        description: The key of the Study, which must be an integer value.
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        description: Information about the Question to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateQuestionRequest'
            example:
              codebookKey: null
              id: Q1
              tasks: cb
              type: o
              label: Likes
              text: What did you like about the product?
              help: Any help string for the product
              sortOrder: 10
              codingSource: v
              alternativeCodingSource: b
              externalQuestionId: null
          text/json:
            schema:
              $ref: '#/components/schemas/CreateQuestionRequest'
            example:
              codebookKey: null
              id: Q1
              tasks: cb
              type: o
              label: Likes
              text: What did you like about the product?
              help: Any help string for the product
              sortOrder: 10
              codingSource: v
              alternativeCodingSource: b
              externalQuestionId: null
          application/*+json:
            schema:
              $ref: '#/components/schemas/CreateQuestionRequest'
            example:
              codebookKey: null
              id: Q1
              tasks: cb
              type: o
              label: Likes
              text: What did you like about the product?
              help: Any help string for the product
              sortOrder: 10
              codingSource: v
              alternativeCodingSource: b
              externalQuestionId: null
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/CreateQuestionResponse'
              example:
                key: 348
                codebookKey: 4589
                id: Q1
                tasks: ct
                type: o
                label: Likes
                text: What did you like about the product?
                help: Any help string for the product
                sortOrder: 10
                codingSource: v
                alternativeCodingSource: b
                externalQuestionId: external_question_id_12345
                errorMessage: null
            application/json:
              schema:
                $ref: '#/components/schemas/CreateQuestionResponse'
              example:
                key: 348
                codebookKey: 4589
                id: Q1
                tasks: ct
                type: o
                label: Likes
                text: What did you like about the product?
                help: Any help string for the product
                sortOrder: 10
                codingSource: v
                alternativeCodingSource: b
                externalQuestionId: external_question_id_12345
                errorMessage: null
            text/json:
              schema:
                $ref: '#/components/schemas/CreateQuestionResponse'
              example:
                key: 348
                codebookKey: 4589
                id: Q1
                tasks: ct
                type: o
                label: Likes
                text: What did you like about the product?
                help: Any help string for the product
                sortOrder: 10
                codingSource: v
                alternativeCodingSource: b
                externalQuestionId: external_question_id_12345
                errorMessage: null
  /Questions/AutoCode/{questionKey}/{loadKey}:
    post:
      tags:
      - Questions
      summary: Initiate autocoding of responses in the specified question
      description: There are three types of AutoCoding available, and will be executed in a certain order.  See the documentation for the body of the POST.
      parameters:
      - name: questionKey
        in: path
        description: The key of the question, which must be an integer value
        required: true
        schema:
          type: integer
          format: int32
      - name: loadKey
        in: path
        description: Key of load
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        description: Auto coding options
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoCodeQuestionRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/AutoCodeQuestionRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/AutoCodeQuestionRequest'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/AutoCodeQuestionResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/AutoCodeQuestionResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/AutoCodeQuestionResponse'
  /Questions/{questionKey}/{entityType}:
    delete:
      tags:
      - Questions
      summary: Delete an existing question or its linked entities
      description: Method deletes the question or its linked entities such as Codes, QualityCodes, Responses.
      parameters:
      - name: questionKey
        in: path
        description: Key of question which should be removed by itself or should be removed its linked entities
        required: true
        schema:
          type: integer
          format: int32
      - name: entityType
        in: path
        description: 'One of following values: "Codes", "QualityCodes", "Responses", "Question"'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DeleteQuestionResponse'
              example:
                entityType: Codes
                entityItemsDeleted: 456
                errorMessage: null
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteQuestionResponse'
              example:
                entityType: Codes
                entityItemsDeleted: 456
                errorMessage: null
            text/json:
              schema:
                $ref: '#/components/schemas/DeleteQuestionResponse'
              example:
                entityType: Codes
                entityItemsDeleted: 456
                errorMessage: null
  /Questions/Translate:
    post:
      tags:
      - Questions
      summary: Translate responses in the specified question
      description: 'Method scans all untranslated yet responses in the specified question and translates them to target language.


        Method returns some useful statistics about translating operation.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranslateQuestionRequest'
            example:
              questionKey: 10000
              targetLanguageCode: uk
          text/json:
            schema:
              $ref: '#/components/schemas/TranslateQuestionRequest'
            example:
              questionKey: 10000
              targetLanguageCode: uk
          application/*+json:
            schema:
              $ref: '#/components/schemas/TranslateQuestionRequest'
            example:
              questionKey: 10000
              targetLanguageCode: uk
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/TranslateQuestionResponse'
              example:
                questionKey: 10000
                responsesCount: 0
                translationsCount: 5000
                nonTranslatedResponsesCount: 0
                transactionsCount: 15000
                errorMessage: null
            application/json:
              schema:
                $ref: '#/components/schemas/TranslateQuestionResponse'
              example:
                questionKey: 10000
                responsesCount: 0
                translationsCount: 5000
                nonTranslatedResponsesCount: 0
                transactionsCount: 15000
                errorMessage: null
            text/json:
              schema:
                $ref: '#/components/schemas/TranslateQuestionResponse'
              example:
                questionKey: 10000
                responsesCount: 0
                translationsCount: 5000
                nonTranslatedResponsesCount: 0
                transactionsCount: 15000
                errorMessage: null
  /Questions/Codebook/{questionKey}/{codebookKey}:
    post:
      tags:
      - Questions
      summary: Set a codebook for some specified question
      description: Method sets the specified codebook to the specified question.
      parameters:
      - name: questionKey
        in: path
        description: Key of a question
        required: true
        schema:
          type: integer
          format: int32
      - name: codebookKey
        in: path
        description: Key of a codebook to set
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/SetQuestionCodebookResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SetQuestionCodebookResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/SetQuestionCodebookResponse'
  /Questions/{studyKey}/Batch:
    post:
      tags:
      - Questions
      summary: Creates new questions in the specified study by using one call to API
      description: "This method expects an array of questions to create in specified study.\n\n\n  \nquestion.type property uses following coding schema: \n<ul><li>c: Closed\n</li><li>d: Data\n</li><li>o: Open\n</li><li>s: Other/Specify\n</li><li>v: Value\n</li></ul>\nFor example, the value 'so' (or 'os') returns Open and Other/Specify Questions.\n\n\n \nquestion.tasks property uses following coding schema: \n<ul><li>c: Code this Question\n</li><li>x: Crosstab this Question\n</li><li>b: Transcribe this Question\n</li><li>t: Translate this Question\n</li></ul>\nFor example, the value ('ct' or 'tc') adjust Question with the Code or Translate tasks set.\n\n\n\nquestion.codingSource and question.alternativeCodingSource properties use following codes: \n<ul><li>v: Verbatim\n</li><li>b: Transcription\n</li><li>t: Translation\n</li><li>empty string: None\n</li></ul>"
      parameters:
      - name: studyKey
        in: path
        description: Key of target study
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        description: Batch of question definitions
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateQuestionsBatchRequest'
            example:
              questions:
              - codebookKey: null
                id: Q1
                tasks: cb
                type: o
                label: Likes
                text: What did you like about the product?
                help: Any help string for the product
                sortOrder: 10
                codingSource: v
                alternativeCodingSource: b
                externalQuestionId: null
              - codebookKey: null
                id: Q2
                tasks: cb
                type: o
                label: Dislikes
                text: What did you dislike about the product?
                help: Any help string for the product
                sortOrder: 20
                codingSource: v
                alternativeCodingSource: b
                externalQuestionId: null
              - codebookKey: null
                id: Q3
                tasks: c
                type: c
                label: Country
                text: Where are you from?
                help: Your country
                sortOrder: 30
                codingSource: v
                alternativeCodingSource: ''
                externalQuestionId: null
          text/json:
            schema:
              $ref: '#/components/schemas/CreateQuestionsBatchRequest'
            example:
              questions:
              - codebookKey: null
                id: Q1
                tasks: cb
                type: o
                label: Likes
                text: What did you like about the product?
                help: Any help string for the product
                sortOrder: 10
                codingSource: v
                alternativeCodingSource: b
                externalQuestionId: null
              - codebookKey: null
                id: Q2
                tasks: cb
                type: o
                label: Dislikes
                text: What did you dislike about the product?
                help: Any help string for the product
                sortOrder: 20
                codingSource: v
                alternativeCodingSource: b
                externalQuestionId: null
              - codebookKey: null
                id: Q3
                tasks: c
                type: c
                label: Country
                text: Where are you from?
                help: Your country
                sortOrder: 30
                codingSource: v
                alternativeCodingSource: ''
                externalQuestionId: null
          application/*+json:
            schema:
              $ref: '#/components/schemas/CreateQuestionsBatchRequest'
            example:
              questions:
              - codebookKey: null
                id: Q1
                tasks: cb
                type: o
                label: Likes
                text: What did you like about the product?
                help: Any help string for the product
                sortOrder: 10
                codingSource: v
                alternativeCodingSource: b
                externalQuestionId: null
              - codebookKey: null
                id: Q2
                tasks: cb
                type: o
                label: Dislikes
                text: What did you dislike about the product?
                help: Any help string for the product
                sortOrder: 20
                codingSource: v
                alternativeCodingSource: b
                externalQuestionId: null
              - codebookKey: null
                id: Q3
                tasks: c
                type: c
                label: Country
                text: Where are you from?
                help: Your country
                sortOrder: 30
                codingSource: v
                alternativeCodingSource: ''
                externalQuestionId: null
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/CreateQuestionsBatchResponse'
              example:
                studyKey: 35987
                questions:
                - key: 348
                  codebookKey: 4589
                  id: Q1
                  tasks: cb
                  type: o
                  label: Likes
                  text: What did you like about the product?
                  help: Any help string for the product
                  sortOrder: 10
                  codingSource: v
                  alternativeCodingSource: b
                  externalQuestionId: external_question_id_12345
                  errorMessage: null
                - key: 349
                  codebookKey: 4589
                  id: Q2
                  tasks: cb
                  type: o
                  label: Likes
                  text: What did you dislike about the product?
                  help: Any help string for the product
                  sortOrder: 10
                  codingSource: v
                  alternativeCodingSource: b
                  externalQuestionId: null
                  errorMessage: null
                - key: 350
                  codebookKey: 4589
                  id: Q3
                  tasks: c
                  type: c
                  label: Country
                  text: Where are you from?
                  help: Your country
                  sortOrder: 30
                  codingSource: v
                  alternativeCodingSource: ''
                  externalQuestionId: external_question_id_67890
                  errorMessage: null
                failedQuestions: null
                errorMessage: null
            application/json:
              schema:
                $ref: '#/components/schemas/CreateQuestionsBatchResponse'
              example:
                studyKey: 35987
                questions:
                - key: 348
                  codebookKey: 4589
                  id: Q1
                  tasks: cb
                  type: o
                  label: Likes
                  text: What did you like about the product?
                  help: Any help string for the product
                  sortOrder: 10
                  codingSource: v
                  alternativeCodingSource: b
                  externalQuestionId: external_question_id_12345
                  errorMessage: null
                - key: 349
                  codebookKey: 4589
                  id: Q2
                  tasks: cb
                  type: o
                  label: Likes
                  text: What did you dislike about the product?
                  help: Any help string for the product
                  sortOrder: 10
                  codingSource: v
                  alternativeCodingSource: b
                  externalQuestionId: null
                  errorMessage: null
                - key: 350
                  codebookKey: 4589
                  id: Q3
                  tasks: c
                  type: c
                  label: Country
                  text: Where are you from?
                  help: Your country
                  sortOrder: 30
                  codingSource: v
                  alternativeCodingSource: ''
                  externalQuestionId: external_question_id_67890
                  errorMessage: null
                failedQuestions: null
                errorMessage: null
            text/json:
              schema:
                $ref: '#/components/schemas/CreateQuestionsBatchResponse'
              example:
                studyKey: 35987
                questions:
                - key: 348
                  codebookKey: 4589
                  id: Q1
                  tasks: cb
                  type: o
                  label: Likes
                  text: What did you like about the product?
                  help: Any help string for the product
                  sortOrder: 10
                  codingSource: v
                  alternativeCodingSource: b
                  externalQuestionId: external_question_id_12345
                  errorMessage: null
                - key: 349
                  codebookKey: 4589
                  id: Q2
                  tasks: cb
                  type: o
                  label: Likes
                  text: What did you dislike about the product?
                  help: Any help string for the product
                  sortOrder: 10
                  codingSource: v
                  alternativeCodingSource: b
                  externalQuestionId: null
                  errorMessage: null
                - key: 350
                  codebookKey: 4589
                  id: Q3
                  tasks: c
                  type: c
                  label: Country
                  text: Where are you from?
                  help: Your country
                  sortOrder: 30
                  codingSource: v
                  alternativeCodingSource: ''
                  externalQuestionId: external_question_id_67890
                  errorMessage: null
                failedQuestions: null
                errorMessage: null
    put:
      tags:
      - Questions
      summary: Adds new or updates existing questions in the specified study by using one call to API
      description: "This method expects an array of questions to update them in specified study.\n\n\n  \nquestion.type property uses following coding schema: \n<ul><li>c: Closed\n</li><li>d: Data\n</li><li>o: Open\n</li><li>s: Other/Specify\n</li><li>v: Value\n</li></ul>\n\n \nquestion.tasks property uses following coding schema: \n<ul><li>c: Code this Question\n</li><li>x: Crosstab this Question\n</li><li>b: Transcribe this Question\n</li><li>t: Translate this Question\n</li></ul>\n\n\nquestion.codingSource and question.alternativeCodingSource properties use following codes: \n<ul><li>v: Verbatim\n</li><li>b: Transcription\n</li><li>t: Translation\n</li><li>empty string: None\n</li></ul>"
      parameters:
      - name: studyKey
        in: path
        description: Key of target study
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        description: Batch of question definitions
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateQuestionsBatchRequest'
            example:
              questions:
              - key: 200001
                id: null
                tasks: ct
                type: null
                label: Likes
                text: Updated title of q1
                help: Any help string for the product
                sortOrder: 10
                codingSource: v
                alternativeCodingSource: b
                externalQuestionId: null
              - key: 200002
                id: null
                tasks: null
                type: null
                label: Dislikes
                text: What did you like about the product?
                help: Any help string for the product
                sortOrder: 20
                codingSource: t
                alternativeCodingSource: b
                externalQuestionId: null
              - key: 200003
                id: null
                tasks: b
                type: null
                label: Neutral Neutral Neutral Neutral Neutral Neutral Neutral Neutral
                text: What did you like about the product?
                help: Any help string for the product
                sortOrder: 30
                codingSource: ''
                alternativeCodingSource: ''
                externalQuestionId: null
          text/json:
            schema:
              $ref: '#/components/schemas/UpdateQuestionsBatchRequest'
            example:
              questions:
              - key: 200001
                id: null
                tasks: ct
                type: null
                label: Likes
                text: Updated title of q1
                help: Any help string for the product
                sortOrder: 10
                codingSource: v
                alternativeCodingSource: b
                externalQuestionId: null
              - key: 200002
                id: null
                tasks: null
                type: null
                label: Dislikes
                text: What did you like about the product?
                help: Any help string for the product
                sortOrder: 20
                codingSource: t
                alternativeCodingSource: b
                externalQuestionId: null
              - key: 200003
                id: null
                tasks: b
                type: null
                label: Neutral Neutral Neutral Neutral Neutral Neutral Neutral Neutral
                text: What did you like about the product?
                help: Any help string for the product
                sortOrder: 30
                codingSource: ''
                alternativeCodingSource: ''
                externalQuestionId: null
          application/*+json:
            schema:
              $ref: '#/components/schemas/UpdateQuestionsBatchRequest'
            example:
              questions:
              - key: 200001
                id: null
                tasks: ct
                type: null
                label: Likes
                text: Updated title of q1
                help: Any help string for the product
                sortOrder: 10
                codingSource: v
                alternativeCodingSource: b
                externalQuestionId: null
              - key: 200002
                id: null
                tasks: null
                type: null
                label: Dislikes
                text: What did you like about the product?


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