Bundle one or more documents into a Binder and run them through Rocket Lawyer's electronic signature workflow. Manage binder lifecycle (status, locks), parties (signers, viewers, owners), documents and their pages / inputs, and orchestrate signature requests — invitations, signatures, reminders, finalisations, cancellations, declines, and viewer access. Supports email invites, embedded signing, and a single-call multi-document signing flow.
openapi: 3.0.0
info:
title: RocketSign & Binders API
description: |-
This API documentation describes the server-side contract by which complete documents can be managed and signed using the **RocketSign® & Binders API**.
<br/><br/>
For a step-by-step walkthrough of how to display and interact with your documents so you can
prepare them for signatures, sign and invite others to sign, check out [Quick Start: RocketSign
Embedded UX](/rocketsign-embedded-ux).
## Binder Lifecycle Overview
To get started with our RocketSign & Binders API, it helps to first understand the binder lifecycle. Here is a quick summary of the four binder states:
### IN_PREPARATION
When a binder is first created, it will be `IN_PREPARATION`. It will stay in this state until the document owner begins to sign or until parties are invited to sign. A binder will also return to `IN_PREPARATION` anytime signing is cancelled.
API calls to manipulate parties, documents and inputs can only be performed when a binder is `IN_PREPARATION`. It’s also the only time when the binder name can be changed.
### REVIEW_AND_SHARE
If a document owner chooses to sign first or if they are otherwise determined to be the only signer, the binder state transitions to `REVIEW_AND_SHARE` (specifically, this occurs as soon as they begin to sign). In this state, no changes can be made to the binder and only the document owner can sign.
### SIGN_IN_PROGRESS
After non-owner parties have been invited to sign, the binder state transitions to `SIGN_IN_PROGRESS`. The binder will remain in this state until all parties have signed/completed all mandatory boxes, or until signing is cancelled.
### SIGN_COMPLETED
When all mandatory boxes have been completed, the binder state becomes `SIGN_COMPLETED`. Once a binder transitions to the `SIGN_COMPLETED` state, it will remain in this state forever.
<img src="https://rl-cicdv2-apigee-public-prod.apigee.io/files/binder-lifecycle.png" />
version: v1
servers:
- url: 'https://api-sandbox.rocketlawyer.com/document-manager/v1'
paths:
/binders:
post:
responses:
'201':
description: The binder has been created
content:
application/json:
example:
id: 936b41f1-66bc-4076-8d0e-5025b8f4b700
name: Assured shorthold tenancy binder
status: IN_PREPARATION
parties:
- id: 9ba431fa-2dba-425b-a8cc-3b301c93d403
reference: partyTest-001
legalName: Owner Test
email: user1@rocketlawyer.co.uk
personId: b83a1b1e-04b2-4c74-b4eb-c1d3da1a9831
roles:
- OWNER
- SIGNER
metaData:
partyMetaData1: stringValue1
partyMetaData2: 3.14159
partyMetaData3: false
status: PENDING
- id: 74eaab2f-7e0a-4d04-a6f9-224d481a53be
reference: partyTest-002
legalName: Signer1 Test
email: user2@rocketlawyer.co.uk
roles:
- SIGNER
status: PENDING
documents:
- id: 22feb59b-678b-40bf-9ced-3d8458b8e153
name: Assured Shorthold Tenancy Agreement 2
signable: true
order: 1
inputs:
- id: cc82f7ea-f914-4e29-b0d3-bd913c6a1615
type: SIGNATURE_TEXT
partyReference: partyTest-001
status: PENDING
position:
type: PLACEHOLDER
identifier: signature-001
- id: 6feb3cb5-12b9-4fcf-b2ed-c1f620556068
type: SIGNATURE_TEXT
partyReference: partyTest-002
status: PENDING
position:
type: PLACEHOLDER
identifier: signature-002
pages: []
- id: e14e4809-4c31-4e8b-8e06-6f3dbb289b0d
name: Addendum to tenancy agreement
signable: false
order: 2
inputs: []
metaData:
externalDocId: 0178-4aa6-803f
events:
- id: ba593f45-6f68-459e-8217-5b0b1d110535
partyId: 9ba431fa-2dba-425b-a8cc-3b301c93d403
occurredAt: '2020-09-16T07:45:06.493086+00:00'
type: BINDER_CREATED
created: '2017-07-05T13:47:49+01:00'
defaultMessage: Invitation to sign
requests: []
timeOffset: '-09:00'
dateFormat: MM/DD/YYYY
configuration:
locale:
country: US
language: en
schema:
$ref: '#/components/schemas/BinderOut'
description: |
<b>Allowed roles:</b> BACKEND<br/>
Creates the new Binder
<ul>
<li>Creates full binder with documents, inputs and parties.</li>
<li>Note that binder status is still <b>IN_PREPARATION</b> as document(s) need to be uploaded.</li>
</ul>
operationId: POST_binders
requestBody:
content:
application/json:
example:
name: Binder1
defaultMessage: Invitation to sign
parties:
- reference: partyTest-001
legalName: Owner Test
email: user1@rocketlawyer.co.uk
roles:
- OWNER
- SIGNER
metaData:
partyMetaData1: stringValue1
partyMetaData2: 3.14159
partyMetaData3: false
- reference: partyTest-002
legalName: Signer1 Test
email: user2@rocketlawyer.co.uk
roles:
- SIGNER
documents:
- name: Assured Shorthold Tenancy Agreement
order: 1
inputs:
- type: SIGNATURE_TEXT
partyReference: partyTest-001
position:
type: PLACEHOLDER
identifier: signature-001
- type: SIGNATURE_TEXT
partyReference: partyTest-002
position:
type: PLACEHOLDER
identifier: signature-002
- name: Addendum to tenancy agreement
order: 2
metaData:
externalDocId: 0178-4aa6-803f
timeOffset: '-09:00'
dateFormat: MM/DD/YYYY
configuration:
locale:
country: US
language: en
schema:
$ref: '#/components/schemas/CreateBinderIn'
required: true
parameters:
- name: Content-Type
in: header
required: true
schema:
enum:
- application/json
type: string
get:
responses:
'200':
description: "The array of binder objects in JSON format
<br>Note: email addresses are only visible for Owner role. Non-owner Party only sees it's own email."
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BinderOut'
example:
- id: 7649c348-2a7c-4b49-960c-5bcae8e05b2c
name: Simple binder
status: IN_PREPARATION
documents:
- id: 80e31904-5947-4d21-a345-b0a2e62da4af
name: Employment contract
signable: true
order: 1
originalContentChecksum: 0da8395a881e5fc36cd7e272ff3b16d9fbed243c7b936278c7299da9d2c788ab
contentType: application/pdf
inputs:
- id: 91780f76-91a6-4e06-95c2-b5b1509ad6d0
type: SIGNATURE_TEXT
position:
type: SIGNATURE_PAGE
status: PENDING
partyReference: partyReference1
optional: false
content: {}
- id: 787e3e50-d091-4ae1-ac98-9ef688a1d2cb
type: DATE_SIGNED
position:
type: SIGNATURE_PAGE
status: PENDING
partyReference: partyReference1
optional: false
configuration:
autoComplete: false
content: {}
- id: 92538fe2-0317-430a-9581-989cdce193f1
type: SIGNATURE_TEXT
position:
type: SIGNATURE_PAGE
status: PENDING
partyReference: partyReference2
optional: false
content: {}
- id: d2e11512-8981-4ecb-a761-223c9a5817c3
type: DATE_SIGNED
position:
type: SIGNATURE_PAGE
status: PENDING
partyReference: partyReference2
optional: false
configuration:
autoComplete: false
content: {}
pages:
- id: 0dc384d6-edcb-5c60-8bad-771a225a092e
parties:
- id: 1d411047-e1a0-4509-9ea2-809ec22c4fd2
reference: partyReference1
legalName: Ryszard
email: user+owner@rocketlawyer.co.uk
jobTitle: Full time document signer
personId: b9a03570-06a5-4815-89d9-23cbb54ebff4
roles:
- OWNER
- SIGNER
status: PENDING
- id: f60881fd-e1db-4fb1-b095-86311a870bba
reference: partyReference2
legalName: Adam
email: user+signer@rocketlawyer.co.uk
jobTitle: Car seller
roles:
- SIGNER
status: PENDING
- id: b0ba924c-959b-42e2-8116-4d1e3bbb4c3f
reference: partyReference3
legalName: Julian Stanford
email: user+viewer@rocketlawyer.co.uk
jobTitle: Lawyer
roles:
- VIEWER
status: PENDING
events:
- id: ddb56dbe-b8db-4cef-8ecd-10245f212b03
partyId: 1d411047-e1a0-4509-9ea2-809ec22c4fd2
occurredAt: '2021-08-23T09:30:21.135033+00:00'
type: BINDER_CREATED
details: {}
locks: []
created: '2021-08-23T09:30:21.042213+00:00'
requests: []
timeOffset: '-08:00'
dateFormat: MM/dd/yyyy
configuration:
locale:
country: US
language: en
notification: true
description: |
<b>Allowed roles:</b> BACKEND<br/>
List of Binders
operationId: GET_binders
parameters:
- name: q
in: query
description: |
Specify filters in format: 'key:value|key:value'.
Possible keys: [partyEmail]
schema:
type: string
- name: limit
in: query
description: |-
Specify limit of results
Limits upper bound is 100.
schema:
default: 10
type: integer
- name: offset
in: query
description: |
Specify offset of result
schema:
default: 0
type: integer
- name: sort
in: query
description: |
Comma-separated list of pairs <field_name> <direction>.<br/>
Direction can be ascending (ASC) or descending (DESC) and is "ASC" by default therefore can be omitted.<br/>
Possible field names are: created.
schema:
default: id ASC
type: string
'/binders/{binderId}':
get:
responses:
'200':
description: "The binder object in JSON format or all documents uploaded to the Binder merged into one PDF.<br>Note: email addresses are only visible for Owner role. Non-owner Party only sees it's own email."
content:
application/json:
example:
id: 936b41f1-66bc-4076-8d0e-5025b8f4b700
name: Assured shorthold tenancy binder
status: IN_PREPARATION
parties:
- id: 9ba431fa-2dba-425b-a8cc-3b301c93d403
reference: partyTest-001
legalName: Owner Test
email: user1@rocketlawyer.co.uk
personId: b83a1b1e-04b2-4c74-b4eb-c1d3da1a9831
roles:
- OWNER
- SIGNER
metaData:
partyMetaData1: stringValue1
partyMetaData2: 3.14159
partyMetaData3: false
status: PENDING
- id: 74eaab2f-7e0a-4d04-a6f9-224d481a53be
reference: partyTest-002
legalName: Signer1 Test
email: user2@rocketlawyer.co.uk
roles:
- SIGNER
status: PENDING
documents:
- id: 22feb59b-678b-40bf-9ced-3d8458b8e153
name: Assured Shorthold Tenancy Agreement 2
signable: true
order: 1
inputs:
- id: cc82f7ea-f914-4e29-b0d3-bd913c6a1615
type: SIGNATURE_TEXT
partyReference: partyTest-001
status: PENDING
position:
type: PLACEHOLDER
identifier: signature-001
- id: 6feb3cb5-12b9-4fcf-b2ed-c1f620556068
type: SIGNATURE_TEXT
partyReference: partyTest-002
status: PENDING
position:
type: PLACEHOLDER
identifier: signature-002
pages: []
- id: e14e4809-4c31-4e8b-8e06-6f3dbb289b0d
name: Addendum to tenancy agreement
signable: false
order: 2
inputs: []
metaData:
externalDocId: 0178-4aa6-803f
events:
- id: ba593f45-6f68-459e-8217-5b0b1d110535
partyId: 9ba431fa-2dba-425b-a8cc-3b301c93d403
occurredAt: '2020-09-16T07:45:06.493086+00:00'
type: BINDER_CREATED
created: '2017-07-05T13:47:49+01:00'
defaultMessage: Invitation to sign
requests: []
timeOffset: '-09:00'
dateFormat: MM/DD/YYYY
configuration:
locale:
country: US
language: en
schema:
$ref: '#/components/schemas/BinderOut'
description: |
<b>Allowed roles:</b> FRONTEND (all parties), BACKEND<br/>
Retrieves binder
operationId: GET_binders-binderId
parameters:
- name: Accept
in: header
required: true
schema:
enum:
- application/json
- application/pdf
type: string
- name: unsigned
in: query
description: |
If present, then unsigned versions of all documents are served as a merged PDF.
Unsigned is in fact the last uploaded version of the document (just before invitation was triggered).
schema:
type: string
delete:
responses:
'204':
description: The binder has been deleted
description: |
<b>Allowed roles:</b> BACKEND<br/>
Deletes binder
operationId: DELETE_binders-binderId
patch:
responses:
'200':
description: The binder has been updated
content:
application/json:
example:
id: 936b41f1-66bc-4076-8d0e-5025b8f4b700
name: Assured shorthold tenancy binder
status: IN_PREPARATION
parties:
- id: 9ba431fa-2dba-425b-a8cc-3b301c93d403
reference: partyTest-001
legalName: Owner Test
email: user1@rocketlawyer.co.uk
personId: b83a1b1e-04b2-4c74-b4eb-c1d3da1a9831
roles:
- OWNER
- SIGNER
metaData:
partyMetaData1: stringValue1
partyMetaData2: 3.14159
partyMetaData3: false
status: PENDING
- id: 74eaab2f-7e0a-4d04-a6f9-224d481a53be
reference: partyTest-002
legalName: Signer1 Test
email: user2@rocketlawyer.co.uk
roles:
- SIGNER
status: PENDING
documents:
- id: 22feb59b-678b-40bf-9ced-3d8458b8e153
name: Assured Shorthold Tenancy Agreement 2
signable: true
order: 1
inputs:
- id: cc82f7ea-f914-4e29-b0d3-bd913c6a1615
type: SIGNATURE_TEXT
partyReference: partyTest-001
status: PENDING
position:
type: PLACEHOLDER
identifier: signature-001
- id: 6feb3cb5-12b9-4fcf-b2ed-c1f620556068
type: SIGNATURE_TEXT
partyReference: partyTest-002
status: PENDING
position:
type: PLACEHOLDER
identifier: signature-002
pages: []
- id: e14e4809-4c31-4e8b-8e06-6f3dbb289b0d
name: Addendum to tenancy agreement
signable: false
order: 2
inputs: []
metaData:
externalDocId: 0178-4aa6-803f
events:
- id: ba593f45-6f68-459e-8217-5b0b1d110535
partyId: 9ba431fa-2dba-425b-a8cc-3b301c93d403
occurredAt: '2020-09-16T07:45:06.493086+00:00'
type: BINDER_CREATED
created: '2017-07-05T13:47:49+01:00'
defaultMessage: Invitation to sign
requests: []
timeOffset: '-09:00'
dateFormat: MM/DD/YYYY
configuration:
locale:
country: US
language: en
schema:
$ref: '#/components/schemas/BinderOut'
description: |
<b>Allowed roles:</b> FRONTEND (OWNER only), BACKEND<br/>
Updates binder
<ul>
<li>A binder can be updated only when it is in the IN_PREPARATION status.</li>
<li>Updates comply as per RFC-7396</li>
</ul>
operationId: PATCH_binders-binderId
requestBody:
content:
application/json:
example:
name: Binder1 name changed
parties:
- id: 9ba431fa-2dba-425b-a8cc-3b301c93d403
legalName: Owner Test changed
email: user1_changed@rocketlawyer.co.uk
metaData: null
- id: 74eaab2f-7e0a-4d04-a6f9-224d481a53be
schema:
$ref: '#/components/schemas/UpdateBinderIn'
required: true
parameters:
- name: Content-Type
in: header
required: true
schema:
enum:
- application/merge-patch+json
type: string
parameters:
- name: binderId
in: path
required: true
schema:
type: string
'/binders/{binderId}/status':
get:
responses:
'200':
description: Status of the binder and result of preflight validations
content:
application/json:
example:
status: IN_PREPARATION
readyForSign: false
unfilledConditions:
- status: 400
code: error.client.condition.singleMatchingPlaceholderIdentifier
title: Unfilled condition
detail: 'Invalid identifier (_ID_1234_), not found in uploaded document'
source:
pointer: /documents/0/inputs/3/position/identifier
- status: 400
code: error.client.condition.documentContentUploaded
title: Unfilled condition
detail: Document content has to be uploaded
source:
pointer: /documents/1
schema:
$ref: '#/components/schemas/StatusOut'
description: |
<b>Allowed roles:</b> FRONTEND (all parties), BACKEND<br/>
Series of validations (preflight check) is performed on binder with status IN_PREPARATION.
Response clearly indicates if binder is ready to be FINALISED or if some changes are still needed.
operationId: GET_binders-binderId-status
parameters:
- name: Accept
in: header
required: true
schema:
enum:
- application/json
type: string
parameters:
- name: binderId
in: path
required: true
schema:
type: string
'/binders/{binderId}/locks':
post:
responses:
'201':
description: The lock has been created (acquired).
content:
application/json:
example:
id: 373b69fc-9c60-47b1-85f5-0f6f179fde18
reason: Reason for the Lock
type: CANCELLATION
schema:
$ref: '#/components/schemas/LockOut'
description: |
<b>Allowed roles:</b> BACKEND <br/>
Creates of lock preventing certain actions on the binder. In example having a cancellation lock on a binder will prevent signing from being cancelled.
operationId: POST_binders-binderId-locks
requestBody:
content:
application/json:
example:
type: CANCELLATION
reason: Reason for the Lock
schema:
$ref: '#/components/schemas/LockIn'
required: true
parameters:
- name: Accept
in: header
required: true
schema:
enum:
- application/json
type: string
parameters:
- name: binderId
in: path
required: true
schema:
type: string
'/binders/{binderId}/locks/{lockId}':
delete:
responses:
'204':
description: The lock has been deleted (released).
description: |
<b>Allowed roles:</b> BACKEND <br/>
Delete a lock from the binder.
Locks can be deleted only by the client that acquired the lock
operationId: DELETE_binders-binderId-locks-lockId
parameters:
- name: Accept
in: header
required: true
schema:
enum:
- application/json
type: string
parameters:
- name: lockId
in: path
required: true
schema:
type: string
- name: binderId
in: path
required: true
schema:
type: string
'/binders/{binderId}/parties':
get:
responses:
'200':
description: ''
content:
application/json:
example:
id: 03cf517c-dee7-4e72-b2b7-dc6086dc4f47
reference: partyTest-003
legalName: Ashima 'SIGNER'
email: aParty+SIGNER@rocketlawyer.co.uk
personId: b83a1b1e-04b2-4c74-b4eb-c1d3da1a9831
roles:
- SIGNER
status: PENDING
schema:
$ref: '#/components/schemas/PartyOut'
'400':
description: The party ID from the passed Service Token is not present in the Binder object.
'403':
description: Passed service token does not give permission to view parties of this Binder.
description: |
<b>Allowed roles:</b> FRONTEND (OWNER only), BACKEND<br/>
Get party represented by service token.
operationId: GET_binders-binderId-parties
parameters:
- name: serviceToken
in: query
required: true
description: Service Token of a party to check the details about
schema:
type: string
post:
responses:
'201':
description: ''
content:
application/json:
example:
id: 03cf517c-dee7-4e72-b2b7-dc6086dc4f47
reference: partyTest-003
legalName: He Who Must Not Be Named
email: signer@rocketlawyer.co.uk
personId: b83a1b1e-04b2-4c74-b4eb-c1d3da1a9831
roles:
- SIGNER
status: PENDING
schema:
$ref: '#/components/schemas/PartyOut'
description: |
<b>Allowed roles:</b> FRONTEND (OWNER only), BACKEND<br/>
Add a party to a binder
<ul>
<li>Normally a party can be added only when the binder is in the `IN_PREPARATION` state.</li>
<li>A party with the `VIEWER` role can be added even after sign invitation is triggered. If the party is added
after sign invitation, an email containing link to binder will be send to the recently
added viewer.</li>
</ul>
operationId: POST_binders-binderId-parties
requestBody:
content:
application/json:
example:
reference: partyTest-002
legalName: Ashima 'SIGNER'
email: example+SIGNER@rocketlawyer.co.uk
roles:
- SIGNER
schema:
$ref: '#/components/schemas/CreatePartyIn'
required: true
parameters:
- name: Content-Type
in: header
required: true
schema:
enum:
- application/json
type: string
parameters:
- name: binderId
in: path
required: true
schema:
type: string
'/binders/{binderId}/parties/{partyId}':
patch:
responses:
'200':
description: The binder has been updated
content:
application/json:
example:
legalName: Owner Test changed
email: user1_changed@rocketlawyer.co.uk
schema:
$ref: '#/components/schemas/PartyOut'
description: |
<b>Allowed roles:</b> FRONTEND (OWNER only), BACKEND<br/>
Update party.
<ul>
<li>A party can be updated only when binder is in the `IN_PREPARATION` state.</li>
<li>Updates comply with RFC-7396</li>
</ul>
operationId: PATCH_binders-binderId-parties-partyId
requestBody:
content:
application/json:
example:
legalName: Owner Test changed
email: user1_changed@rocketlawyer.co.uk
schema:
$ref: '#/components/schemas/PatchPartyIn'
required: true
parameters:
- name: Content-Type
in: header
required: true
schema:
enum:
- application/merge-patch+json
type: string
delete:
responses:
'204':
description: Party has been deleted
description: |
<b>Allowed roles:</b> FRONTEND (OWNER only), BACKEND<br/>
Delete a party.
<ul>
<li>Normally a party can only be deleted when binder is in the `IN_PREPARATION` state.</li>
<li>If the party has the `VIEWER` role, it may be deleted even when the binder is in a different state.</li>
<li>The owning party cannot be deleted.</li>
</ul>
operationId: DELETE_binders-binderId-parties-partyId
parameters:
- name: partyId
in: path
required: true
schema:
type: string
- name: binderId
in: path
required: true
schema:
type: string
'/binders/{binderId}/documents':
post:
responses:
'201':
description: Document created
content:
application/json:
example:
id: a023c3c5-5859-40a1-a2a6-150a75c35ab6
name: Tenancy agreement
signable: true
order: 1
inputs:
- id: 3071aec4-94c7-490e-a721-f9008f418dbb
type: SIGNATURE_TEXT
position:
type: SIGNATURE_PAGE
status: PENDING
partyReference: partyTest-001
- id: 8e48c3f5-1957-43af-91bc-7fe5358e55b2
type: SIGNATURE_TEXT
position:
type: SIGNATURE_PAGE
status: PENDING
partyReference: partyTest-002
schema:
$ref: '#/components/schemas/DocumentOut'
description: |
<b>Allowed roles:</b> FRONTEND (OWNER only), BACKEND<br/>
Adds a document to a binder.
operationId: POST_binders-binderId-documents
requestBody:
content:
application/json:
example:
name: Tenancy agreement
order: 1
inputs:
- type: SIGNATURE_TEXT
partyReference: partyTest-001
position:
type: SIGNATURE_PAGE
- type: SIGNATURE_TEXT
partyReference: partyTest-002
position:
type: SIGNATURE_PAGE
schema:
$ref: '#/components/schemas/CreateDocumentIn'
required: true
parameters:
- name: Content-Type
in: header
required: true
schema:
enum:
- application/json
type: string
parameters:
- name: binderId
in: path
required: true
schema:
type: string
'/binders/{binderId}/documents/{documentId}':
get:
responses:
'303':
description: Redirection to the file
headers:
location:
description: location of the resource where the client should be redirected to
schema:
# --- truncated at 32 KB (132 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/rocket-lawyer/refs/heads/main/openapi/rocket-lawyer-rocketsign-binders-api-openapi.yml