Voxco Studies API

openapi: 3.2.0
info:
  title: Ascribe Coder AICoder Studies 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: Studies
paths:
  /Studies:
    get:
      tags:
      - Studies
      summary: Get all studies
      description: 'The list of Studies returned may be optionally filtered by id, status, and client company.


        When filtering by id the asterisk * character may optionally be used as a leading or trailing wildcard.'
      parameters:
      - name: idFilter
        in: query
        description: 'If omitted, the returned Studies are not filtered by id.


          Otherwise filter the returned Studies by this case-insensitive value.


          Leading and/or trailing asterisk characters (character code 42) may be used:


          <ul><li>Leading and trailing asterisk : study id must contain the string between the asterisk characters.

          </li><li>Leading asterisk: study id must end with the string after the asterisk character.

          </li><li>Trailing asterisk: study id must start with the string before the asterisk character.

          </li><li>No leading or trailing asterisk: study id must match the specified value.


          </li></ul>

          Any asterisk character which is not the first or last character of the value is considered to be part of the requested id.'
        schema:
          type: string
      - name: statusMask
        in: query
        description: 'If omitted, Studies with any status are returned.


          If present, a string containing these characters, the presence of which specifies the status of the Studies desired:

          <ul><li>a: Archived

          </li><li>p: Coding in progress

          </li><li>c: Completed

          </li><li>d: Deleted

          </li><li>h: On hold

          </li><li>r: Review in progress

          </li><li>s: Shipping

          </li><li>u: Under construction


          </li></ul>

          For example, the value ''pc'' (or ''cp'') returns Studies with ''Coding in progress'' or ''Completed'' status.'
        schema:
          type: string
      - name: clientCompanyKey
        in: query
        description: 'If omitted or null, the Studies returned are not filtered by Company.


          Otherwise, the Studies returned are those assigned to the Company with the specified key.'
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetStudiesResponse'
              example:
                studies:
                - key: 544
                  quota: 5
                  id: S458-3
                  name: An example of study
                  description: Use this study only for testing
                  status: c
                  supervisorKey: 1001
                  clientCompanyKey: 45
                  endCompanyKey: 46
                  help: Call 02-863**90 if you have questions
                  createDateUtc: '0001-01-01T00:00:00'
                  startDateUtc: '2026-06-13T20:21:47.3064269+00:00'
                  dueDateUtc: '2026-06-20T20:21:47.3064279+00:00'
                  externalStudyId: null
                - key: 559
                  quota: null
                  id: S890
                  name: null
                  description: null
                  status: p
                  supervisorKey: null
                  clientCompanyKey: null
                  endCompanyKey: null
                  help: null
                  createDateUtc: '0001-01-01T00:00:00'
                  startDateUtc: null
                  dueDateUtc: null
                  externalStudyId: null
                errorMessage: null
    post:
      tags:
      - Studies
      summary: Create a new study
      description: Method creates a new study based on data from request body.
      requestBody:
        description: Information about the Study to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewStudyRequest'
            example:
              quota: 3
              id: S458-3
              name: Hair care
              description: Test of hair care products
              status: p
              supervisorKey: 44
              clientCompanyKey: 45
              endCompanyKey: 46
              help: Code frames must be spell-checked!
              startDateUtc: '2026-06-13T20:21:47.3196928+00:00'
              dueDateUtc: '2026-06-20T20:21:47.3197193+00:00'
              externalStudyId: null
          text/json:
            schema:
              $ref: '#/components/schemas/NewStudyRequest'
            example:
              quota: 3
              id: S458-3
              name: Hair care
              description: Test of hair care products
              status: p
              supervisorKey: 44
              clientCompanyKey: 45
              endCompanyKey: 46
              help: Code frames must be spell-checked!
              startDateUtc: '2026-06-13T20:21:47.3196928+00:00'
              dueDateUtc: '2026-06-20T20:21:47.3197193+00:00'
              externalStudyId: null
          application/*+json:
            schema:
              $ref: '#/components/schemas/NewStudyRequest'
            example:
              quota: 3
              id: S458-3
              name: Hair care
              description: Test of hair care products
              status: p
              supervisorKey: 44
              clientCompanyKey: 45
              endCompanyKey: 46
              help: Code frames must be spell-checked!
              startDateUtc: '2026-06-13T20:21:47.3196928+00:00'
              dueDateUtc: '2026-06-20T20:21:47.3197193+00:00'
              externalStudyId: null
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewStudyResponse'
              example:
                key: 544
                quota: null
                id: S458-3
                name: Hair care
                description: Test of hair care products
                status: p
                supervisorKey: null
                supervisorAssociateKey: null
                clientCompanyKey: 45
                endCompanyKey: null
                help: Code frames must be spell-checked!
                createDateUtc: '2026-04-29T20:21:47.3117267Z'
                startDateUtc: null
                dueDateUtc: null
                countQuestions: 0
                countResponses: 0
                countResponsesCoded: 0
                countTransactions: 0
                externalStudyId: null
                errorMessage: null
    put:
      tags:
      - Studies
      summary: Update an existing study
      description: Method updates an existing study by using data from request body.
      requestBody:
        description: Information about the Study to update.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateStudyRequest'
            example:
              studyKey: 10000
              quota: 3
              id: S458-3
              name: Hair care
              description: Test of hair care products
              status: p
              supervisorKey: 44
              clientCompanyKey: 45
              endCompanyKey: 46
              help: Code frames must be spell-checked!
              startDateUtc: '2026-06-13T20:21:47.3265196+00:00'
              dueDateUtc: '2026-06-20T20:21:47.3265468+00:00'
              externalStudyId: null
          text/json:
            schema:
              $ref: '#/components/schemas/UpdateStudyRequest'
            example:
              studyKey: 10000
              quota: 3
              id: S458-3
              name: Hair care
              description: Test of hair care products
              status: p
              supervisorKey: 44
              clientCompanyKey: 45
              endCompanyKey: 46
              help: Code frames must be spell-checked!
              startDateUtc: '2026-06-13T20:21:47.3265196+00:00'
              dueDateUtc: '2026-06-20T20:21:47.3265468+00:00'
              externalStudyId: null
          application/*+json:
            schema:
              $ref: '#/components/schemas/UpdateStudyRequest'
            example:
              studyKey: 10000
              quota: 3
              id: S458-3
              name: Hair care
              description: Test of hair care products
              status: p
              supervisorKey: 44
              clientCompanyKey: 45
              endCompanyKey: 46
              help: Code frames must be spell-checked!
              startDateUtc: '2026-06-13T20:21:47.3265196+00:00'
              dueDateUtc: '2026-06-20T20:21:47.3265468+00:00'
              externalStudyId: null
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateStudyResponse'
              example:
                key: 544
                quota: null
                id: S458-3
                name: Hair care
                description: Test of hair care products
                status: p
                supervisorKey: null
                supervisorAssociateKey: null
                clientCompanyKey: 45
                endCompanyKey: null
                help: Code frames must be spell-checked!
                createDateUtc: '2026-04-29T20:21:47.32497Z'
                startDateUtc: null
                dueDateUtc: null
                countQuestions: 0
                countResponses: 0
                countResponsesCoded: 0
                countTransactions: 0
                externalStudyId: null
                errorMessage: null
    delete:
      tags:
      - Studies
      summary: Delete study by key
      description: Method deletes the study by its key.
      requestBody:
        description: Information about the Study to delete.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteStudyRequest'
            example:
              studyKey: 29999
          text/json:
            schema:
              $ref: '#/components/schemas/DeleteStudyRequest'
            example:
              studyKey: 29999
          application/*+json:
            schema:
              $ref: '#/components/schemas/DeleteStudyRequest'
            example:
              studyKey: 29999
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteStudyResponse'
              example:
                errorMessage: null
  /Studies/{studyKey}:
    get:
      tags:
      - Studies
      summary: Get a study
      description: Method returns a definition of requested study by using its key.
      parameters:
      - name: studyKey
        in: path
        description: The key of the desired Study, which must be an integer value.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetStudyResponse'
              example:
                key: 544
                quota: null
                id: S458-3
                name: Hair care
                description: Test of hair care products
                status: c
                supervisorKey: null
                supervisorAssociateKey: null
                clientCompanyKey: 45
                endCompanyKey: null
                help: Code frames must be spell-checked!
                createDateUtc: '2026-04-29T20:21:47.3332828Z'
                startDateUtc: null
                dueDateUtc: null
                countQuestions: 22
                countResponses: 4968
                countResponsesCoded: 2379
                countTransactions: 2379
                externalStudyId: null
                errorMessage: null
  /Studies/Translate:
    post:
      tags:
      - Studies
      summary: Translate all Responses in a Study
      description: "The method scans all questions in the specified study and checks for the **Translate Task** option.\n\nQuestions with this option enabled are included in the translation process to the target language.\n\nFor each of the question the method scans all untranslated yet responses and translates them.\n \nAt the end of the translation operation, the method provides statistics, including the number of responses translated\n\nand the number of transactions performed for each translated question."
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranslateStudyRequest'
            example:
              studyKey: 10000
              targetLanguageCode: null
          text/json:
            schema:
              $ref: '#/components/schemas/TranslateStudyRequest'
            example:
              studyKey: 10000
              targetLanguageCode: null
          application/*+json:
            schema:
              $ref: '#/components/schemas/TranslateStudyRequest'
            example:
              studyKey: 10000
              targetLanguageCode: null
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslateStudyResponse'
              example:
                studyKey: 10000
                targetLanguageCode: null
components:
  schemas:
    UpdateStudyResponse:
      required:
      - countQuestions
      - countResponses
      - countResponsesCoded
      - countTransactions
      - createDateUtc
      - id
      - key
      - status
      type: object
      properties:
        errorMessage:
          type:
          - string
          - 'null'
        key:
          type: integer
          description: The key of the Study.
          format: int32
        quota:
          type:
          - integer
          - 'null'
          description: The quota for the Study
          format: int32
        id:
          minLength: 1
          type: string
          description: The id of the Study.
        name:
          type:
          - string
          - 'null'
          description: A user-friendly display name of the Study.
        description:
          type:
          - string
          - 'null'
          description: A description of the Study.
        status:
          minLength: 1
          type: string
          description: 'A one-character string which specifies the status of the Study:

            <ul><li>a: Archived

            </li><li>p: Coding in progress

            </li><li>c: Completed

            </li><li>d: Deleted

            </li><li>h: On hold

            </li><li>r: Review in progress

            </li><li>s: Shipping

            </li><li>u: Under construction</li></ul>'
        supervisorKey:
          type:
          - integer
          - 'null'
          description: 'The key of the Person who will do revision of coding work

            '
          format: int32
        supervisorAssociateKey:
          type:
          - integer
          - 'null'
          description: 'The key of the supervisor''s associate

            '
          format: int32
        clientCompanyKey:
          type:
          - integer
          - 'null'
          description: The Company to which this Study is assigned, or null if the Study is not assigned to a Company.
          format: int32
        endCompanyKey:
          type:
          - integer
          - 'null'
          description: 'The key of the Company for which this coding work is being performed

            '
          format: int32
        help:
          type:
          - string
          - 'null'
          description: Information to coders to assist in coding this Study.
        createDateUtc:
          type: string
          description: The UTC date/time the Study was created.
          format: date-time
        startDateUtc:
          type:
          - string
          - 'null'
          description: UTC date/time the Study was started.
          format: date-time
        dueDateUtc:
          type:
          - string
          - 'null'
          description: UTC date/time the Study was completed.
          format: date-time
        countQuestions:
          type: integer
          description: The number of Questions in the Study.
          format: int32
        countResponses:
          type: integer
          description: The sum of the number of Responses in each Question in the Study.
          format: int32
        countResponsesCoded:
          type: integer
          description: The sum of the number of Responses to which at least one Code has been assigned in each Question in the Study.
          format: int32
        countTransactions:
          type: number
          description: The number of transactions used by this Study.  Transactions are tokens of work performed on the Study.
          format: double
        externalStudyId:
          type:
          - string
          - 'null'
          description: External study id from StudyMaps
      additionalProperties: false
      description: The response with data of created study.
    DeleteStudyResponse:
      type: object
      properties:
        errorMessage:
          type:
          - string
          - 'null'
      additionalProperties: false
      description: Response for delete study action
    DeleteStudyRequest:
      required:
      - studyKey
      type: object
      properties:
        studyKey:
          type: integer
          description: Key of study to delete
          format: int32
      additionalProperties: false
      description: Request for delete study action
    NewStudyResponse:
      required:
      - countQuestions
      - countResponses
      - countResponsesCoded
      - countTransactions
      - createDateUtc
      - id
      - key
      - status
      type: object
      properties:
        errorMessage:
          type:
          - string
          - 'null'
        key:
          type: integer
          description: The key of the Study.
          format: int32
        quota:
          type:
          - integer
          - 'null'
          description: The quota for the Study
          format: int32
        id:
          minLength: 1
          type: string
          description: The id of the Study.
        name:
          type:
          - string
          - 'null'
          description: A user-friendly display name of the Study.
        description:
          type:
          - string
          - 'null'
          description: A description of the Study.
        status:
          minLength: 1
          type: string
          description: 'A one-character string which specifies the status of the Study:

            <ul><li>a: Archived

            </li><li>p: Coding in progress

            </li><li>c: Completed

            </li><li>d: Deleted

            </li><li>h: On hold

            </li><li>r: Review in progress

            </li><li>s: Shipping

            </li><li>u: Under construction</li></ul>'
        supervisorKey:
          type:
          - integer
          - 'null'
          description: 'The key of the Person who will do revision of coding work

            '
          format: int32
        supervisorAssociateKey:
          type:
          - integer
          - 'null'
          description: 'The key of the supervisor''s associate

            '
          format: int32
        clientCompanyKey:
          type:
          - integer
          - 'null'
          description: The Company to which this Study is assigned, or null if the Study is not assigned to a Company.
          format: int32
        endCompanyKey:
          type:
          - integer
          - 'null'
          description: 'The key of the Company for which this coding work is being performed

            '
          format: int32
        help:
          type:
          - string
          - 'null'
          description: Information to coders to assist in coding this Study.
        createDateUtc:
          type: string
          description: The UTC date/time the Study was created.
          format: date-time
        startDateUtc:
          type:
          - string
          - 'null'
          description: UTC date/time the Study was started.
          format: date-time
        dueDateUtc:
          type:
          - string
          - 'null'
          description: UTC date/time the Study was completed.
          format: date-time
        countQuestions:
          type: integer
          description: The number of Questions in the Study.
          format: int32
        countResponses:
          type: integer
          description: The sum of the number of Responses in each Question in the Study.
          format: int32
        countResponsesCoded:
          type: integer
          description: The sum of the number of Responses to which at least one Code has been assigned in each Question in the Study.
          format: int32
        countTransactions:
          type: number
          description: The number of transactions used by this Study.  Transactions are tokens of work performed on the Study.
          format: double
        externalStudyId:
          type:
          - string
          - 'null'
          description: External study id from StudyMaps
      additionalProperties: false
      description: The response with data of created study.
    TranslateStudyRequest:
      required:
      - studyKey
      - targetLanguageCode
      type: object
      properties:
        studyKey:
          type: integer
          description: Key of study
          format: int32
        targetLanguageCode:
          minLength: 1
          type: string
          description: Code of target language
      additionalProperties: false
      description: Request for translating study
    Study:
      required:
      - createDateUtc
      - id
      - key
      - status
      type: object
      properties:
        key:
          type: integer
          description: The key of the Study, which will not change for the lifetime of the Study.
          format: int32
        quota:
          type:
          - integer
          - 'null'
          description: 'The quota for the Study

            If no quota is set for the Study this field will not be present in the response.'
          format: int32
        id:
          minLength: 1
          type: string
          description: The id of the Study.
        name:
          type:
          - string
          - 'null'
          description: 'The name of the Study.


            If no study name is set for the Study this field will not be present in the response.'
        description:
          type:
          - string
          - 'null'
          description: 'The description of the Study.


            If no description is set for the Study this field will not be present in the response.'
        status:
          minLength: 1
          type: string
          description: 'A one-character string which specifies the status of the Study:

            <ul><li>a: Archived

            </li><li>p: Coding in progress

            </li><li>c: Completed

            </li><li>d: Deleted

            </li><li>h: On hold

            </li><li>r: Review in progress

            </li><li>s: Shipping

            </li><li>u: Under construction</li></ul>'
        supervisorKey:
          type:
          - integer
          - 'null'
          description: 'The key of the Person who will do revision of coding work


            If no supervisor is set for the Study this field will not be present in the response.'
          format: int32
        clientCompanyKey:
          type:
          - integer
          - 'null'
          description: 'The key of the Company for which this coding work is assigned


            If no client company is set for the Study this field will not be present in the response.'
          format: int32
        endCompanyKey:
          type:
          - integer
          - 'null'
          description: 'The key of the Company for which this coding work is being performed


            If no end customer company is set for the Study this field will not be present in the response.'
          format: int32
        help:
          type:
          - string
          - 'null'
          description: 'The information about the Study


            If no help information is set for the Study this field will not be present in the response.'
        createDateUtc:
          type: string
          description: The UTC date/time the Study was created.
          format: date-time
        startDateUtc:
          type:
          - string
          - 'null'
          description: 'UTC date/time the Study was started.


            If the date is not set yet for the Study this field will not be present in the response.'
          format: date-time
        dueDateUtc:
          type:
          - string
          - 'null'
          description: 'UTC date/time the Study was completed.


            If the date is not set yet for the Study this field will not be present in the response.'
          format: date-time
        externalStudyId:
          type:
          - string
          - 'null'
          description: External study id from StudyMaps
      additionalProperties: false
      description: A Study.
    GetStudyResponse:
      required:
      - countQuestions
      - countResponses
      - countResponsesCoded
      - countTransactions
      - createDateUtc
      - id
      - key
      - status
      type: object
      properties:
        errorMessage:
          type:
          - string
          - 'null'
        key:
          type: integer
          description: The key of the Study.
          format: int32
        quota:
          type:
          - integer
          - 'null'
          description: The quota for the Study
          format: int32
        id:
          minLength: 1
          type: string
          description: The id of the Study.
        name:
          type:
          - string
          - 'null'
          description: A user-friendly display name of the Study.
        description:
          type:
          - string
          - 'null'
          description: A description of the Study.
        status:
          minLength: 1
          type: string
          description: 'A one-character string which specifies the status of the Study:

            <ul><li>a: Archived

            </li><li>p: Coding in progress

            </li><li>c: Completed

            </li><li>d: Deleted

            </li><li>h: On hold

            </li><li>r: Review in progress

            </li><li>s: Shipping

            </li><li>u: Under construction</li></ul>'
        supervisorKey:
          type:
          - integer
          - 'null'
          description: 'The key of the Person who will do revision of coding work

            '
          format: int32
        supervisorAssociateKey:
          type:
          - integer
          - 'null'
          description: 'The key of the supervisor''s associate

            '
          format: int32
        clientCompanyKey:
          type:
          - integer
          - 'null'
          description: The Company to which this Study is assigned, or null if the Study is not assigned to a Company.
          format: int32
        endCompanyKey:
          type:
          - integer
          - 'null'
          description: 'The key of the Company for which this coding work is being performed

            '
          format: int32
        help:
          type:
          - string
          - 'null'
          description: Information to coders to assist in coding this Study.
        createDateUtc:
          type: string
          description: The UTC date/time the Study was created.
          format: date-time
        startDateUtc:
          type:
          - string
          - 'null'
          description: UTC date/time the Study was started.
          format: date-time
        dueDateUtc:
          type:
          - string
          - 'null'
          description: UTC date/time the Study was completed.
          format: date-time
        countQuestions:
          type: integer
          description: The number of Questions in the Study.
          format: int32
        countResponses:
          type: integer
          description: The sum of the number of Responses in each Question in the Study.
          format: int32
        countResponsesCoded:
          type: integer
          description: The sum of the number of Responses to which at least one Code has been assigned in each Question in the Study.
          format: int32
        countTransactions:
          type: number
          description: The number of transactions used by this Study.  Transactions are tokens of work performed on the Study.
          format: double
        externalStudyId:
          type:
          - string
          - 'null'
          description: External study id from StudyMaps
      additionalProperties: false
      description: The response to a query for a specific Study.
    UpdateStudyRequest:
      required:
      - studyKey
      type: object
      properties:
        studyKey:
          type: integer
          description: Key of a study that should be updated.
          format: int32
        quota:
          type:
          - integer
          - 'null'
          description: The quota for the Study
          format: int32
        id:
          maxLength: 30
          minLength: 1
          type:
          - string
          - 'null'
          description: 'The id of the new Study.


            Must be unique among all Studies in the Ascribe account of the current session by case-insensitive comparison.


            Must be at least 1 character and not more than 30 characters.'
        name:
          maxLength: 50
          minLength: 0
          type:
          - string
          - 'null'
          description: 'Optional name of this Study, intended to be more human-friendly than the id of the Study.


            Maximum of 50 characters.'
        description:
          type:
          - string
          - 'null'
          description: An optional description of the Study.
        status:
          maxLength: 1
          minLength: 0
          type:
          - string
          - 'null'
          description: 'Optional status of the Study.


            If specified, one of:

            <ul><li>a: Archived

            </li><li>p: Coding in progress

            </li><li>c: Completed

            </li><li>d: Deleted

            </li><li>h: On hold

            </li><li>r: Review in progress

            </li><li>s: Shipping

            </li><li>u: Under construction</li></ul>'
        supervisorKey:
          type:
          - integer
          - 'null'
          description: 'The key of the Person who will do revision of coding work


            If no supervisor is set for the Study this field will not be present in the response.'
          format: int32
        clientCompanyKey:
          type:
          - integer
          - 'null'
          description: Optional key of the Company for which this coding work is being performed.
          format: int32
        endCompanyKey:
          type:


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