Rocket Lawyer Interviews API

openapi: 3.2.0
info:
  title: RocketDocument v2 Interviews API
  version: '2.2'
servers:
- url: https://api-sandbox.rocketlawyer.com/rocketdoc/v2
  description: sandbox
- url: https://api.rocketlawyer.com/rocketdoc/v2
  description: production
security:
- bearerAuth: []
tags:
- name: Interviews
paths:
  /interviews:
    post:
      tags:
      - Interviews
      operationId: create-interview
      summary: Create an Interview
      description: 'This endpoint allows you to create a new interview session.


        - Provide a reference to a Binder (`binderId`) or an owner email (`partyEmailAddress`).

        - If a `binderId` is provided, the new interview will be created within the context of this Binder.

        - If `binderId` isn''t provided, a new binder will be created.

        - User-entered information will be stored by Rocket Lawyer.


        **Service Token**:

        - A service token is provided in the response header, scoped to the `partyId`.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InterviewCreateRequest'
        required: true
      responses:
        '201':
          description: 'Successfully returns a newly created interview.

            '
          headers:
            rl-rdoc-servicetoken:
              schema:
                type: string
              description: 'The `Service Token`.

                <small>Not present when creating an Interview with a pre-existing Binder</small>

                '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/interview'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
      deprecated: false
    get:
      tags:
      - Interviews
      operationId: list-interviews
      summary: List All Interviews
      description: TThis endpoint retrieves a list of interviews in the requesting partner tenancy. You can optionally filter the results by `partnerEndUserId` to narrow the list to a specific end user. The response includes the interview names, IDs, templates used, current statuses, and storage types.
      parameters:
      - name: partnerEndUserId
        in: query
        description: 'The unique identifier of the partner''s end user used to filter the list of interviews. If provided, only interviews associated with this end user will be returned.

          '
        schema:
          $ref: '#/components/schemas/partnerEndUserId'
        required: false
      responses:
        '200':
          description: 'Successfully returns the status of all interviews belonging to the partner.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/interviewsGetResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
      deprecated: false
  /interviews/{interviewId}:
    get:
      tags:
      - Interviews
      summary: Retrieve Interview by ID
      description: Retrieves the details of an existing interview identified by the `interviewId`. This endpoint lets you fetch all the information related to a specific interview, including its status and associated data. This endpoint also enables you to resume a previously started interview.
      operationId: retrieve-interview
      parameters:
      - $ref: '#/components/parameters/interviewIdPath'
        description: The unique identifier of the interview to retrieve.
      responses:
        '200':
          description: 'Successfully returns the details of the specified interview.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/interview'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
      deprecated: false
    put:
      tags:
      - Interviews
      summary: Update an Interview
      description: This endpoint updates an existing Interview with data in the Tagged Answer Model (TAM) format. It's important to note that data previously entered for this interview will be lost.
      operationId: update-interview
      parameters:
      - $ref: '#/components/parameters/interviewIdPath'
        description: The unique identifier of the interview to update.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/interviewUpdateRequest'
      responses:
        '200':
          description: 'Successfully updates the specified interview.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/interview'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
      deprecated: false
    delete:
      tags:
      - Interviews
      summary: Delete an Interview
      description: Deletes an existing interview resource identified by the `interviewId`. This operation permanently removes the interview and its associated data from the Rocket Lawyer system.
      operationId: delete-interview
      parameters:
      - $ref: '#/components/parameters/interviewIdPath'
        description: The unique identifier of the interview to be deleted.
      responses:
        '204':
          description: The interview resource was successfully deleted.
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
      deprecated: false
  /interviews/{interviewId}/completions:
    post:
      tags:
      - Interviews
      summary: Complete an Interview
      description: Completes the specified interview for which answers have been supplied. This operation finalizes the interview, ensuring that all provided answers are processed and saved and final document stored at the binder.
      operationId: complete-interview
      parameters:
      - $ref: '#/components/parameters/interviewIdPath'
        description: The unique identifier of the interview to be completed.
      responses:
        '201':
          description: The interview was successfully completed and the answers have been processed and saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InterviewCompleteResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
      deprecated: false
  /interviews/{interviewId}/pages/{pageId}:
    get:
      tags:
      - Interviews
      summary: Retrieve a Page
      description: 'Retrieves a specific page of the interview identified by `interviewId` and `pageId`.


        For this call, the default format for `currentPageData` is set to `display`, and the default preview format is `text/html`.


        If you are on the first page of the interview, the previous page and the current page of the response object will be the same. Similarly, if you are on the last page of the interview, the current page and the next page will be the same.'
      parameters:
      - $ref: '#/components/parameters/interviewIdPath'
      - $ref: '#/components/parameters/pageRefPath'
      responses:
        '200':
          description: Successfully retrieves the specified page of the interview.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pageResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
      operationId: getInterviewsByInterviewIdPagesByPageId
      x-operation-id-source: derived
    patch:
      tags:
      - Interviews
      summary: Update an Interview Page's Answers
      operationId: update-page
      description: 'Submit the answers to the questions for a specific page of the interview, identified by `interviewId` and `pageId`.


        This operation can also be used to retrieve the next or previous page preview, and/or get the updated preview of the current page. This is controlled by the `format` key in each page''s respective data inside the request''s body.


        If you are on the first page of the interview, the previous page and the current page of the response object will be the same. Similarly, if you are on the last page of the interview, the current page and the next page will be the same.'
      parameters:
      - $ref: '#/components/parameters/interviewIdPath'
      - $ref: '#/components/parameters/pageIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/pagePatchRequest'
      responses:
        '200':
          description: Successfully submits the data for the specified page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pageResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
  /interviews/{interviewId}/tagged-answers:
    get:
      tags:
      - Interviews
      summary: Retrieve Interview Data
      description: 'Retrieves data from a interview in Tagged Answer Model (TAM) format.


        This endpoint allows you to fetch structured data for the interview, which includes the tagged answers aligned with the TAM structure.'
      operationId: retrieve-tagged-answers
      parameters:
      - $ref: '#/components/parameters/interviewIdPath'
      responses:
        '200':
          description: 'Returns all the answers for interview in tagged answer model (TAM) format.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tam'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
      deprecated: false
components:
  schemas:
    pageDataDisplaySingle:
      allOf:
      - $ref: '#/components/schemas/pageDataDisplayCommon'
      - $ref: '#/components/schemas/pageDataDisplaySingleElements'
    templateId:
      description: The unique identifier of the document template to be used for the interview. This template defines the structure and content of the interview. Retrieve a list of available templates with the [Get Templates](/get-templates) endpoint.
      type: string
      example: 0bf17ad8-a229-1289-ef4a-00b7c9ad9cab
    tamRole:
      description: A list of roles that the entity plays within the interview context. Roles define the specific function or position of the entity in the interview, such as 'Applicant' or 'Employer'.
      type: string
      example: Applicant
    create_interview_with_party_email:
      allOf:
      - type: object
        properties:
          partyEmailAddress:
            $ref: '#/components/schemas/partyEmailAddress'
      - $ref: '#/components/schemas/createInterview'
      required:
      - partyEmailAddress
    question:
      type: object
      properties:
        id:
          type: string
          example: Qkrp9n844hj7gtr
        title:
          type: string
          example: what is your name?
        hint:
          type: string
          example: Enter your name here
        fields:
          type: array
          items:
            $ref: '#/components/schemas/field'
        help:
          $ref: '#/components/schemas/help'
        showIf:
          description: if present then this is the field condition that must be met to show the question.
          type: string
          example: (Fl1cgaazb4yehd = true)
      required:
      - id
      - title
      - hint
      - fields
    storageType:
      description: 'Specifies the type of backend data storage strategy used for this interview.

        '
      type: string
      enum:
      - ephemeral
      - persistent
      default: persistent
    tamClass:
      type: string
      description: 'The classification of the entity. Can be either:

        - `Person`

        - `Organization`

        - `Property`

        '
      enum:
      - Person
      - Organization
      - Property
      example: Person
    answersPayload:
      description: 'A key-value object to include all provided answers. Each key refers to a answer unique identifier in the system (`Flfmulpp4orak5`), with its value being the actual answer provided by the end user.

        <small>Example: `{ "Flfmulpp4orak5": "true", "Flfmufliy5gnuf": "John Doe" }`</small>

        '
      type: object
      example:
        Flfmu8ta21l9eh: ''
        Flfmufliy5gnuf: ''
        Flfmulpp4orak5: 'true'
        Flfmum2u1mcvif: 'false'
        Flfmuuwxkfljt6: 'true'
        Flfmuwllpj97qz: 'false'
        Flfmuznrnxr8vn: ''
        Flfqvnvr121l11: ''
        Clfqvxpiwq5btl:
        - Flfqvvhivulxtb: answer 1
          Flfqvwpr3a35lw: answer 2
        - Flfqvvhivulxtb: answer 3
          Flfqvwpr3a35lw: answer 4
        Clfqxxxexkmjzr:
        - Flfqwerocs85au: ''
        Flfqyoh037bgfr: ''
        Flfqyp3z2r6prc: 'false'
    partyEmailAddress:
      type: string
      description: 'The email address of the party for whom the interview is being created.

        If provided, a new Binder is created for this email address.

        ⚠️ <small>This parameter is mutually exclusive with `binderId`.</small> ⚠️

        '
      example: user@xyzcompany.com
    field:
      description: 'The UI can choose which UI display component is best to display the type of data represented by these names.

        '
      type: object
      properties:
        id:
          type: string
          example: Fkrp98ynuj7gtr
        type:
          $ref: '#/components/schemas/fieldType'
        default:
          type: string
          description: Indicates the default value for this field - for example if it is a Radio button then could be "true". If there is no default then "" will be returned.
          example: ''
        label:
          type: string
          description: The label to apply to the input to guide the user about what information is expected. For example if the question is about Address then the label might be for City.
          example: City
        symbol:
          description: Any symbol relevant to display the field correctly.
          type: string
          example: $
      required:
      - id
      - type
      - default
      - label
    currentPageDataPatchRequest:
      properties:
        format:
          $ref: '#/components/schemas/pageDataPatch'
    tamEntityClass:
      description: The classification of the field within the entity. This defines the type or category of the field, aligning with the entity's role and characteristics.
      type: string
      example: Entity Type
    interviewsGetResponse:
      type: array
      items:
        $ref: '#/components/schemas/interview'
    tam:
      description: 'The Tagged Answer Model (TAM) represents the structured format for injecting data into an interview or retrieving data from an interview. This model maps the input data to the corresponding fields and entities within the document template.

        '
      type: object
      properties:
        name:
          type: string
          description: The name of the template being used for the interview.
          example: Employment contract
        templateId:
          $ref: '#/components/schemas/templateId'
        entities:
          type: array
          items:
            $ref: '#/components/schemas/tamEntity'
        fields:
          type: array
          items:
            $ref: '#/components/schemas/tamField'
      required:
      - name
      - entities
      - fields
    pageDataPatch:
      description: 'Describes the type of page data:

        - `reference`: Contains only the `pageId` and is used for iterating through an interview, providing navigation without detailed content.

        - `display`: Shows the full question information for that page, including all content necessary for the interview process.

        '
      type: string
      enum:
      - display
      - reference
      default: reference
    questions:
      type: array
      items:
        $ref: '#/components/schemas/question'
    nextPageDataPatchRequest:
      properties:
        format:
          $ref: '#/components/schemas/pageDataPatch'
    tamEntity:
      type: object
      description: Represents an entity involved in the interview process. Entities can be individuals, organizations, or properties, each playing specific roles within the context of the interview.
      properties:
        name:
          $ref: '#/components/schemas/tamEntityName'
        class:
          $ref: '#/components/schemas/tamClass'
        roles:
          type: array
          items:
            $ref: '#/components/schemas/tamRole'
        isCyclical:
          type: string
          enum:
          - true
          - false
          default: false
          description: True if this Entity is cyclical. Not present or false if not.
      required:
      - name
      - class
      - roles
    interviewUpdateRequest:
      type: object
      properties:
        inputData:
          $ref: '#/components/schemas/tam'
          description: 'The Tagged Answer Model (TAM) represents the structured format for injecting data into an interview or retrieving data from an interview. Retrieve a interview''s TAM with the following endpoint:

            - [Retrieve Interview Data](/)

            '
    pageDataDisplayCommon:
      type: object
      properties:
        pageId:
          $ref: '#/components/schemas/pageId'
        format:
          description: "Describes the type of page data: \n- `reference`: only contains a `pageId` and it is used for iterating through an interview.\n- `display`: shows the question information for the respective page.\n"
          type: string
          enum:
          - display
        isFirst:
          description: Defines if the page requested is the first page or not.
          type: boolean
        progressPercentage:
          type: integer
          example: '78'
        questions:
          $ref: '#/components/schemas/questions'
      required:
      - pageId
      - format
      - progressPercentage
      - questions
    pageDataDisplayCyclical:
      allOf:
      - $ref: '#/components/schemas/pageDataDisplayCommon'
      - $ref: '#/components/schemas/pageDataDisplayCyclicalElements'
    pageId:
      type: string
      description: An opaque ID for a page. Do not depend on the format of these IDs.
      example: Fkbbc110f2d2eb
    InterviewCreateRequest:
      oneOf:
      - $ref: '#/components/schemas/create_interview_with_party_email'
      - $ref: '#/components/schemas/create_interview_with_binder'
    binder:
      description: Return the `binderId` and `documentId`.
      type: object
      properties:
        binderId:
          $ref: '#/components/schemas/binderId'
        documentId:
          type: string
          description: The Document's unique identifier.
          example: 7d989647-ecf2-4673-9486-80c3b890ed3c
      required:
      - binderId
      - documentId
    pageDataReference:
      type: object
      properties:
        pageId:
          $ref: '#/components/schemas/pageId'
        format:
          description: "Describes the type of page data: \n- `reference`: only contains a `pageId` and it is used for iterating through an interview.\n- `display`: shows the question information for the respective page.\n"
          type: string
          enum:
          - reference
      required:
      - pageId
      - format
    createInterview:
      type: object
      properties:
        templateId:
          $ref: '#/components/schemas/templateId'
        partnerEndUserId:
          $ref: '#/components/schemas/partnerEndUserId'
        inputData:
          $ref: '#/components/schemas/tam'
          description: The Tagged Answer Model (TAM) represents the structured format for injecting data into an interview or retrieving data from an interview. Retrieve a template's TAM with the [Retrieve Tagged Answer Model](/get-template-tam) endpoint.
      required:
      - templateId
    tamEntityName:
      description: The name of the entity. This could be the name of a person, organization, or property involved in the interview.
      type: string
      example: Formed Entity
    help:
      type: string
      example: Your name should go here.
    binderId:
      type: string
      description: "The unique identifier of the Binder to which the interview will be added. \n⚠️ <small>This parameter is mutually exclusive with `partyEmailAddress`.</small> ⚠️\n"
      example: 0af17ba7-f332-5346-bb3f-00b7c9af7deb
    fieldType:
      description: Metadata type suggesting what this field should contain and loosely describing how a UI might display it for user interaction. The field type provides hints on the nature of the data and the appropriate form input controls to use.
      type: object
      enum:
      - TEXT
      - PARAGRAPH
      - DATE
      - DROPDOWN
      - NUMBER
      - CURRENCY
      - PERCENTAGE
      - SSN
      - RADIO
      - CHECKBOX
      - PHONE_NUMBER
      - PHONE_EXT
    pageDataDisplayCyclicalElements:
      type: object
      properties:
        cycleId:
          type: string
          description: 'Opaque UUID of the cycle.

            ⚠️ <small>present only if `type=cyclical`.</small> ⚠️

            '
          example: Clfqvxpiwq5btl
        type:
          description: Question being returned either a single or cyclical.
          type: string
          enum:
          - cyclical
        title:
          type: string
          description: 'Used primarily with chain cyclicals for the overall question title.

            <small>This in an optional field</small>.

            '
          example: Title of a cyclical question
        answers:
          type: array
          items:
            type: object
            description: "An array of answer objects for the questions on the page returned. \n⚠️ <small>Used where `pageData` is `type=cyclical`.</small> ⚠️\n"
            example:
            - Flfqvvhivulxtb: answer 1
              Flfqvwpr3a35lw: answer 2
            - Flfqvvhivulxtb: answer 3
              Flfqvwpr3a35lw: answer 4
      required:
      - cycleId
      - type
      - answers
    tamField:
      type: object
      description: Each field corresponds to a data point in the interview, allowing for the collection and retrieval of user-entered information. These fields are pre-filled with initial data and align with the template's structure, facilitating a customized and relevant interview process.
      properties:
        entity:
          description: This entity correlates with an object in the entities array, linking the field to a specific entity involved in the interview. The entity helps to contextualize the field within the broader interview structure.
          type: string
        fieldClass:
          $ref: '#/components/schemas/tamEntityClass'
        type:
          $ref: '#/components/schemas/fieldType'
        value:
          type: string
          description: The actual value of the field. This is the data entered by the user or provided initially, corresponding to the field's type and purpose within the interview.
        cycleId:
          description: "Id of the cycle. Not present if not cyclical. Cycle Ids can be of any type \nbut numerical is most intuitive and most predictable for sorting.\n"
          type: string
      required:
      - entity
      - fieldClass
      - type
      - value
    partnerEndUserId:
      type: string
      description: A unique identifier for the end user provided by the partner application. This helps in linking the interview to a specific user within the partner's system.
      example: cfd1ee5a-061a-40cc-be72-8cbb9945b5d9
    previewPatchRequest:
      properties:
        mimeType:
          $ref: '#/components/schemas/previewMimeType'
    preview:
      properties:
        mimeType:
          $ref: '#/components/schemas/previewMimeType'
        data:
          type: string
          description: Base64 encoded string of the html of the document representing the document preview, if answers have been provided then these will be included in the preview.
          example: PGh0bWw+PGJvZHk+Um9ja2V0RG9jdW1lbnQgcHJldmlldzwvYm9keT48L2h0bWw+Cg==
      required:
      - mimeType
      - data
    previousPageDataPatchRequest:
      properties:
        format:
          $ref: '#/components/schemas/pageDataPatch'
    pageDataDisplaySingleElements:
      type: object
      properties:
        type:
          description: Question being returned either a single or cyclical.
          type: string
          enum:
          - single
        answers:
          type: object
          description: The answer fields for the questions on the page returned.
          example:
            Flfmulpp4orak5: 'true'
            Flfmum2u1mcvif: 'false'
            Flfmuuwxkfljt6: 'true'
      required:
      - type
      - answers
    pageResponse:
      properties:
        answersPayload:
          $ref: '#/components/schemas/answersPayload'
        preview:
          $ref: '#/components/schemas/preview'
        previousPageData:
          oneOf:
          - $ref: '#/components/schemas/pageDataReference'
          - $ref: '#/components/schemas/pageDataDisplaySingle'
          - $ref: '#/components/schemas/pageDataDisplayCyclical'
        currentPageData:
          oneOf:
          - $ref: '#/components/schemas/pageDataReference'
          - $ref: '#/components/schemas/pageDataDisplaySingle'
          - $ref: '#/components/schemas/pageDataDisplayCyclical'
        nextPageData:
          oneOf:
          - $ref: '#/components/schemas/pageDataDisplaySingle'
          - $ref: '#/components/schemas/pageDataDisplayCyclical'
          - $ref: '#/components/schemas/pageDataReference'
    interviewId:
      description: The unique identifier of the Interview.
      type: string
      example: 76105b3e-ac8a-4202-8ed2-b991a02b8456
    previewMimeType:
      description: Mime-type for the preview.
      type: string
      enum:
      - text/html
      default: text/html
    create_interview_with_binder:
      allOf:
      - type: object
        properties:
          binderId:
            $ref: '#/components/schemas/binderId'
      - $ref: '#/components/schemas/createInterview'
      required:
      - binderId
    pagePatchRequest:
      properties:
        answersPayload:
          $ref: '#/components/schemas/answersPayload'
        currentPageData:
          description: An instruction object for the returned current page data.
          $ref: '#/components/schemas/currentPageDataPatchRequest'
        previousPageData:
          description: An instruction object for the returned previous page data.
          $ref: '#/components/schemas/previousPageDataPatchRequest'
        nextPageData:
          description: An instruction object for the returned next page data.
          $ref: '#/components/schemas/nextPageDataPatchRequest'
        preview:
          description: An instruction object for the preview data.
          $ref: '#/components/schemas/previewPatchRequest'
    InterviewCompleteResponse:
      type: object
      properties:
        binder:
          $ref: '#/components/schemas/binder'
    interview:
      type: object
      properties:
        interviewId:
          $ref: '#/components/schemas/interviewId'
        interviewName:
          type: string
          description: The Interview's name.
          example: Employment contract
        templateId:
          $ref: '#/components/schemas/templateId'
        templateVersionId:
          type: string
          description: The unique identifier of the template version being used for this interview.
          example: d9243532-6fae-41b8-a082-6d6844fa6246
        partnerEndUserId:
          $ref: '#/components/schemas/partnerEndUserId'
        storageType:
          $ref: '#/components/schemas/storageType'
        interviewStatus:
          type: string
          description: The current status of the Interview.
          enum:
          - created
          - completed
          example: created
        pageId:
          type: string
          description: If present, this is the last page updated by any process that updates the Interview.
          example: Pkyezdgfswi58z
        createdAt:
          type: string
          description: The date the resource was created.
          example: '2020-12-01T17:51:40.795Z'
        updatedAt:
          type: string
          description: The date the resource was updated.
          example: '2021-12-01T18:51:40.795Z'
        binder:
          $ref: '#/components/schemas/binder'
        answersPayload:
          $ref: '#/components/schemas/answersPayload'
      required:
      - interviewId
      - interviewName
      - interviewStatus
      - createdAt
      - updatedAt
      - templateId
      - templateVersionId
  parameters:
    pageRefPath:
      name: pageId
      in: path
      description: 'Either a pageId or a pseudonym for a page. Enter one of the following options:

        - `pageId`: The unique identifier of the requested page.

        - `"first"`: Pseudonym for the first page of the Interview.

        - `"last"`: Pseudonym for the last answered page by the end user of the Interview.

        '
      schema:
        type: string
      example: Pkbbc224f2d2eb
      required: true
    pageIdPath:
      name: pageId
      in: path
      description: 'Either a pageId or a pseudonym for a page. Enter one of the following options:

        - `pageId`: The unique identifier of the requested page.

        - `"first"`: Pseudonym for the first page of the Interview.

        - `"last"`: Pseudonym for the last answered page by the end user of the Interview.

        '
      schema:
        type: string
      example: Pkaab440f2d2eb
      required: true
    interviewIdPath:
      name: interviewId
      in: path
      description: The unique identifier of an interview.
      required: true
      schema:
        type: string
      example: 76105b3e-ac8a-4202-8ed2-b991a02b8456
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT