openapi: 3.0.0
info:
title: Authentication Accesstoken Interviews API
version: 1.0.0
description: "This API documentation describes the authentication mechanisms that enable access to the Rocket Lawyer’s APIs. The Rocket Lawyer API Platform uses Oauth 2.0 access tokens (as per [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)) to authenticate API requests and protect your resources. \n\nThis page provides a comprehensive overview of the three types of tokens — Access Tokens, Service Tokens, and Scoped Access Tokens — along with guidance on using these tokens effectively during interactions with Rocket Lawyer’s APIs.\n\nGuides that provide step-by-step instructions for how to authenticate using the Rocket Lawyer embeddable UXs can be viewed in the [Guides section](/guides)). \n\nExplore the different authentication tokens and their usage within Rocket Lawyer's API ecosystem using the sections below:\n\n# Access Token\n\nAccess Tokens are used whenever backend systems need to interact with Rocket Lawyer's APIs. Calls made with these tokens can access the data for all of your customers associated with the App you created in the developer center. Example usage is to start new interviews or retrieve all documents and binders.\n\nTo create an Access Token, issue a POST to /auth/accesstoken using valid credentials, these can be obtained from the [RocketLawyer Developer Portal](https://developer.rocketlawyer.com/) - see the [Welcome Guide](/welcome-guide)) for how to obtain these.\n\nThen include the Access Token as a bearer token in the Authorization header of your API requests to access our API resources.\n\nThis token can be used to start a new interview and retrieve the necessary document templates, establishing a secure foundation for the session.\n\nAccess Tokens expire after 10 hours. During this time, you should securely store this token in your backend for use in future requests. Creating a new access token does not invalidate any previously generated access tokens, your app can have more than one valid access token at a time.\n\n# Service Token\n\nService Tokens are a means for one application to delegate authority to API resources to less privileged applications. Typically a backend application will generate a service token to be distributed to a frontend application, to securely access a specific API resource. Service Tokens are generated with parameters like the purpose, interview ID, and Unique Party Identifier (UPID) that describe the scope of access that can be granted to the frontend application.\n\nGenerate a Service Token by sending a request to the Authentication endpoint with the necessary parameters. \n\nThe Service Token can then be passed to your frontend to be used in an Embedded UX component or to enable your frontend to access the Rocket Lawyer APIs through the creation of a scoped access token. This token has a 1-year expiration time.\n\n\n# Scoped Access Token\n\nA Scoped Access Token is typically used to authenticate frontend interactions. You need to create these tokens only if calling the Rocket Lawyer APIs from your front-end, for example if building your own UX. If using the embedded UX then these tokens are created and handled within the component.\n\nScoped Access Tokens grant access to specific resources, such as an interview (identified by interviewId) or linked to a particular party (identified by a UPID). \n\nTo obtain a Scoped Access Token, you must first generate a Service Token that specifies the resources that can be accessed. To create a scoped access token you need to create a new Developer app in the [RocketLawyer Developer Portal](https://developer.rocketlawyer.com/) that has front-end only scope. Contact Rocket Lawyer developer support (api@rocketlawyer.com) who will help provide this. The key and secret from this front-end app should be used to create the scoped access token. \n\nYou should include this token in the Authorization header of your frontend API requests.\n\n# Application Scope \nDeveloper apps can be created with either backend or frontend access scope. Apps with backend scope are used for server-to-server communication and can access all our APIs. Apps with frontend scope are used by a web frontend to access our APIs and are restricted in the calls they can make to support the UX. If building your own UX, you will need an app with frontend scope.\n\n**Note** You must not use a Developer App that has backend access to authenticate into Rocket Lawyer APIs from your front-end. This will expose your backend credentials that have access to all your customers' data in the browser.\n"
termsOfService: https://rocketlawyer-public-us.apigee.io/terms
servers:
- url: https://api-sandbox.rocketlawyer.com/partners/v1/auth
description: Sandbox
- url: https://api.rocketlawyer.com/partners/v1/auth
description: Production
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
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:
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
pageDataDisplayCyclical:
allOf:
- $ref: '#/components/schemas/pageDataDisplayCommon'
- $ref: '#/components/schemas/pageDataDisplayCyclicalElements'
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
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
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
questions:
type: array
items:
$ref: '#/components/schemas/question'
previewPatchRequest:
properties:
mimeType:
$ref: '#/components/schemas/previewMimeType'
currentPageDataPatchRequest:
properties:
format:
$ref: '#/components/schemas/pageDataPatch'
InterviewCompleteResponse:
type: object
properties:
binder:
$ref: '#/components/schemas/binder'
pageDataDisplaySingle:
allOf:
- $ref: '#/components/schemas/pageDataDisplayCommon'
- $ref: '#/components/schemas/pageDataDisplaySingleElements'
interviewsGetResponse:
type: array
items:
$ref: '#/components/schemas/interview'
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
previewMimeType:
description: Mime-type for the preview.
type: string
enum:
- text/html
default: text/html
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
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
create_interview_with_binder:
allOf:
- type: object
properties:
binderId:
$ref: '#/components/schemas/binderId'
- $ref: '#/components/schemas/createInterview'
required:
- binderId
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
nextPageDataPatchRequest:
properties:
format:
$ref: '#/components/schemas/pageDataPatch'
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
help:
type: string
example: Your name should go here.
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
pageId:
type: string
description: An opaque ID for a page. Do not depend on the format of these IDs.
example: Fkbbc110f2d2eb
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
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'
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](/)
'
create_interview_with_party_email:
allOf:
- type: object
properties:
partyEmailAddress:
$ref: '#/components/schemas/partyEmailAddress'
- $ref: '#/components/schemas/createInterview'
required:
- partyEmailAddress
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
InterviewCreateRequest:
oneOf:
- $ref: '#/components/schemas/create_interview_with_party_email'
- $ref: '#/components/schemas/create_interview_with_binder'
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
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
storageType:
description: 'Specifies the type of backend data storage strategy used for this interview.
'
type: string
enum:
- ephemeral
- persistent
default: persistent
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
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
previousPageDataPatchRequest:
properties:
format:
$ref: '#/components/schemas/pageDataPatch'
interviewId:
description: The unique identifier of the Interview.
type: string
example: 76105b3e-ac8a-4202-8ed2-b991a02b8456
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
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
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
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
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'
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
tamClass:
type: string
description: 'The classification of the entity. Can be either:
- `Person`
- `Organization`
- `Property`
'
enum:
- Person
- Organization
- Property
example: Person
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
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/rocket-lawyer/refs/heads/main/openapi/rocket-lawyer-interviews-api-openapi.yml