# Signature
# Signature
Electronic signature ceremonies over the closing package: who signs what, in what order, and what comes back.
A caller sends the documents and the signer set. The product creates the ceremony, tracks each signer's progress, and returns the executed package with its certificate.
Signing order matters and is declared rather than inferred. Some documents require a specific sequence between borrower, coborrower and settlement agent, and a ceremony that lets them sign in any order produces a package a closer has to reject.
## Operations
### Operations
`POST` `/`
#### Create eSign
`post-esign`
Create eSign invokes a data partner to electronically sign a document.
To invoke Create eSign, you will need:
- a transaction_id, and
- a collection_id.
Once you have a transaction_id and collection_id, simply invoke Create eSign with your transaction_id, collection_id and a data partner name.
Create eSign returns, as a synchronous acknowledgement, a new collection_id. The new collection_id represents an empty container which will hold the data partner's response once processing has completed.
Data partners: HelloSign, Notarize, HelloFax, DocuSign, NotaryCam, eOriginal, Escrow Tab, Nexsys, OneSpan
##### Request
Exampleapplication/json
application/json Copy
```
{
"transaction_id": "uhz6t54e-9d74-g17e-99ca-a36b30vdfd35",
"collection_id": "hg62e49f-9d74-g17e-99ca-a36b30vdfd35",
"partner_name": "hellosign"
}
```
application/json Copy
```
{
"transaction_id": "",
"collection_id": "",
"partner_name": "hellosign"
}
```
##### Response
application/json Copy eSign request created successfully.
```
{
"collection_id": "e4502ed2-8df8-4b8f-84bd-a1097e999a77",
"message": "When ready, data will be available under the following collection_id. Use this new collection_id to get the execution status."
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
| `Content-Type` required | `string` header | — | — |
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id`required | `string` | Transaction ID |
| `collection_id`required | `string` | Collection ID |
| `partner_name`required | `string` | — |
##### Response `200``application/json`
2 fields
eSign request created successfully.
| Field | Type | Description |
| --- | --- | --- |
| `collection_id` | `string` | Collection ID |
| `message` | `string` | Message |
##### Other responses
`400``404`
`POST` `/blobs`
#### Create Blob
`post-esign-blob`
Create Blob creates a blob in Staircase.
A Binary Large Object (blob) is a collection of binary data stored as a single entity. Typically it represents a document, image or other multimedia object.
To invoke a partner product for eSign, you must first create a blob for your document. The presigned URL, which is returned as a response, represents a container in Staircase for your document. A presigned URL expires one hour after creation.
##### Request
application/json Copy
```
{
"extension": ".pdf"
}
```
##### Response
application/json Copy Blob created successfully
```
{
"blob_id": "a34c40a6-3c02-44f9-a696-cd7388f506d3",
"extension": ".pdf",
"presigned_urls": {
"upload": {
"url": "https://dev-data-manager-blobs-bucket.s3.amazonaws.com/a34c40a6-3c02-44f9-a696-cd7388f506d3"
}
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
| `Content-Type` required | `string` header | — | — |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `extension`required | `string` | Document extension |
##### Response `201``application/json`
3 fields
Blob created successfully
| Field | Type | Description |
| --- | --- | --- |
| `blob_id` | `string` | Blob ID |
| `extension` | `string` | File extension |
| `presigned_urls` | `object` | Presigned URL |
##### Other responses
`400`
`GET` `/blobs/{blob_id}`
#### Retrieve Blob
`get-esign-blob`
Retrieve Blob retrieves, for a given blob_id, presigned URLs for uploading and downloading the blob to and from Staircase.
##### Response
application/json Copy Blob retrieved successfully
```
{
"blob_id": "a34c40a6-3c02-44f9-a696-cd7388f506d3",
"extension": ".pdf",
"presigned_urls": {
"upload": {
"url": "https://dev-data-manager-blobs-bucket.s3.amazonaws.com/8u7z6t5r-3c02-44f9-a696-cd7388f506d3"
}
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `blob_id` required | `string (uuid)` path | `7b95d83e-205b-4610-b199-a4843fcb7027` | Blob ID |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
##### Response `200``application/json`
3 fields
Blob retrieved successfully
| Field | Type | Description |
| --- | --- | --- |
| `blob_id` | `string` | Blob ID |
| `extension` | `string` | File extension |
| `presigned_urls` | `object` | Presigned URL |
##### Other responses
`400``404`
`GET` `/blobs/{blob_id}/presigned-urls`
#### Retrieve Presigned URLs
`post-esign-presigned-urls`
Retrieve Presigned URLs retrieves, for a given blob_id, presigned URLs for uploading and downloading the blob to and from Staircase.
##### Response
application/json Copy Presigned urls retrieved successfully
```
{
"presigned_urls": {
"download": {
"url": "https://dev-data-manager-blobs-bucket.s3.amazonaws.com/a34c40a6-3c02-44f9-a696-cd7388f506d3"
},
"upload": {
"url": "https://dev-data-manager-blobs-bucket.s3.amazonaws.com/8u7z6t5r-3c02-44f9-a696-cd7388f506d3"
}
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `blob_id` required | `string (uuid)` path | `7b95d83e-205b-4610-b199-a4843fcb7027` | Blob ID |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
##### Response `200``application/json`
1 fields
Presigned urls retrieved successfully
| Field | Type | Description |
| --- | --- | --- |
| `presigned_urls` | `object` | — |
##### Other responses
`400``404`
`GET` `/blobs/{blob_id}/presigned-urls/{action}`
#### Retrieve Presigned URL for Action
`get-esign-presigned-url-for-action`
Retrieve Presigned URL for Action retrieves a presigned url for a specific action. An action can be download or upload.
##### Response
application/json Copy Presigned url retrieved successfully
```
{
"presigned_urls": {
"upload": {
"url": "https://dev-data-manager-blobs-bucket.s3.amazonaws.com/a34c40a6-3c02-44f9-a696-cd7388f506d3"
}
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `blob_id` required | `string (uuid)` path | `9aa12c27-4a36-4ea9-91d0-6342aaa18a05` | Blob ID |
| `action` required | `string` path | `upload` | Possible actions: - upload - download |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
##### Response `200``application/json`
1 fields
Presigned url retrieved successfully
| Field | Type | Description |
| --- | --- | --- |
| `presigned_urls` | `object` | — |
##### Other responses
`400``404`
`PUT` `/blobs/{blob_id}/presigned-urls/{action}`
#### Create Presigned URL
`put-esign-presigned-url-for-action`
Create Presigned URL creates a presigned URL in Staircase. The presigned URL is used to upload or download a blob (document). It expires one hour after creation.
##### Response
application/json Copy Presigned URL successfully created.
```
{
"presigned_urls": {
"upload": {
"url": "https://dev-data-manager-blobs-bucket.s3.amazonaws.com/8u7z6t5r-3c02-44f9-a696-cd7388f506d3"
}
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `blob_id` required | `string (uuid)` path | `a34c40a6-3c02-44f9-a696-cd7388f506d3` | Blob identifier |
| `action` required | `string` path | `upload` | Possible actions: - upload - download |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API Key |
##### Response `200``application/json`
1 fields
Presigned URL successfully created.
| Field | Type | Description |
| --- | --- | --- |
| `presigned_urls` | `object` | — |
##### Other responses
`400``404`
`POST` `/blobs/upload/{blob_id}`
#### Upload Blob
`post-esign-upload-blob`
Upload Blob uploads a document (blob) to a presigned URL via the HTML Request Maker Try It Out. Paste your Authorization Key into the request header, change the request body content type to binary, and browse to your document.
This endpoint should be used in the HTML Request Maker Try it Out only. To upload a document within code, you need to use upload presigned URL returned in the Create Blob response body.
```
import requests
# Create Blob endpoint returns blob_id and upload presigned url
presigned_url = ""
payload = request.get_data
headers = {
'Content-Type': 'application/pdf'
}
response = requests.put(url=presigned_url, headers=headers, data=payload)
print(response.text.encode('utf8'))
```
##### Request
application/octet-stream Copy
```
Select option 'binary' in order to upload file
```
##### Response
200400
application/json Copy Upload blob success message
```
{
"message": "Document has been uploaded successfully!"
}
```
application/json Copy Blob upload failed
```
{
"message": "Error uploading a document!"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `blob_id` required | `string (uuid)` path | `7c95d83e-215b-4610-b199-a4843fcb7027` | Blob ID |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
##### Response `200``application/json`
1 fields
Upload blob success message
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `400``application/json`
1 fields
Blob upload failed
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Other responses
`403``404`
`POST` `/build-payload`
#### Retrieve Product Elements Structure
`get-esign-translate-elements`
Retrieve Product Elements Structure retrieves a json schema for either:
- a collection used as part of a request for eSign, or
- a collection returned as part of response containing an electronically signed document.
To retrieve the schema needed for a collection that is part of a request for eSign:
Show the rest
1. Invoke Retrieve Request Elements to get an array of eSign request elements.
1. Place the output from Retrieve Request Elements into the Retrieve Product Elements Structure request body.
1. Place your api_key into the Retrieve Product Elements Structure header.
1. Send the request to Retrieve Product Elements Structure. You will receive a well-formed json schema in response, with null values that must be replaced with your own.
To review the response schema that contains the electronic signature provided by an eSign data partner:
1. Invoke Retrieve Response Elements to get an array of eSign response elements.
1. Place the output from Retrieve Response Elements into the Retrieve Product Elements Structure request body.
1. Place your api_key into the Retrieve Product Elements Structure header.
1. Send the request to Retrieve Product Elements Structure. You will receive a well-formed json schema in response, with null values that will be replaced by the data partner upon return of the electronically signed document.
##### Request
Exampleapplication/json
application/json Copy
```
{
"$.document_sets.document_set[0].documents.document[0].content.foreign_object.reference.location_label_value": "7e62ce76-d93d-4f31-92d3-45c2cb8255ea",
"$.document_sets.document_set[0].documents.document[0].signatories.signatory[0].allow_decline": true,
"$.document_sets.document_set[0].documents.document[0].signatories.signatory[0].signees.signee[0].name": "John",
"$.document_sets.document_set[0].documents.document[0].signatories.signatory[0].signees.signee[0].email": "Doe"
}
```
application/json Copy
```
{
"$.document_sets.document_set[0].documents.document[0].content.foreign_object.reference.location_label_value": null,
"$.document_sets.document_set[0].documents.document[0].signatories.signatory[0].signees.signee[0].name": null,
"$.document_sets.document_set[0].documents.document[0].signatories.signatory[0].signees.signee[0].email": null,
"$.document_sets.document_set[0].documents.document[0].signatories.signatory[0].allow_decline": null
}
```
##### Response
application/json Copy Elements retrieved successfully.
```
{
"document_sets": {
"document_set": [
{
"documents": {
"document": [
{
"content": {
"foreign_object": {
"reference": {
"location_label_value": ""
}
}
},
"signatories": {
"signatory": [
{
"allow_decline": "",
"signees": {
"signee": [
{
"name": "",
"email": ""
}
]
}
}
]
}
}
]
}
}
]
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
| `Content-Type` required | `string` header | — | — |
##### Other responses
`200``400``403`
`POST` `/embedded-document-urls`
#### Create eSign Embedded Document Urls
`post-esign-embedded-document-urls`
Initiate process for generating embedded document urls
##### Request
Exampleapplication/json
application/json Copy
```
{
"transaction_id": "uhz6t54e-9d74-g17e-99ca-a36b30vdfd35",
"collection_id": "hg62e49f-9d74-g17e-99ca-a36b30vdfd35"
}
```
application/json Copy
```
{
"transaction_id": "",
"collection_id": ""
}
```
##### Response
application/json Copy eSign embedded document urls request created successfully.
```
{
"request_id": "e4502ed2-8df8-4b8f-84bd-a1097e999a77"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
| `Content-Type` required | `string` header | — | — |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id`required | `string` | Transaction ID |
| `collection_id`required | `string` | Collection ID |
##### Response `202``application/json`
1 fields
eSign embedded document urls request created successfully.
| Field | Type | Description |
| --- | --- | --- |
| `request_id` | `string` | Request ID |
##### Other responses
`404``406`
`GET` `/embedded-document-urls/{request_id}`
#### Retrieve eSign Embedded Document URLs
`get-esign-embedded-document-urls`
Retireve embedded document URLs
##### Response
application/json Copy Embedded document urls retrieved successfully.
```
{
"signatures": [
{
"signer_name": "name1",
"signer_email_address": "name1@test.com",
"sign_url_data": {
"sign_url": "https://sign_url_name1_example.com",
"expires_at": 1605023817
}
},
{
"signer_name": "name2",
"signer_email_address": "name2@test.com",
"sign_url_data": {
"sign_url": "https://sign_url_name2_example.com",
"expires_at": 1605023817
}
}
]
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `request_id` required | `string` path | `9u8z7t65-cb71-4f20-8e40-7a829b52e91e` | Transaction ID |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
##### Response `200``application/json`
1 fields
Embedded document urls retrieved successfully.
| Field | Type | Description |
| --- | --- | --- |
| `signatures` | `array` | signatures |
##### Other responses
`202``400``404`
`GET` `/request-elements`
#### Retrieve Request Elements
`get-esign-request-elements`
Retrieve Request Elements retrieves a list of elements needed to invoke a data partner for eSign.
##### Response
application/json Copy Elements needed for request.
```
{
"$.document_sets.document_set[0].documents.document[0].content.foreign_object.reference.location_label_value": null,
"$.document_sets.document_set[0].documents.document[0].signatories.signatory[0].allow_decline": null,
"$.document_sets.document_set[0].documents.document[0].signatories.signatory[0].signees.signee[0].name": null,
"$.document_sets.document_set[0].documents.document[0].signatories.signatory[0].signees.signee[0].email": null
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
##### Other responses
`200``400`
`POST` `/request-elements/complete`
#### Validate Collection
`post-esign-collection-complete`
Validate Collection validates that a collection contains all of the elements needed to invoke a data partner for eSign.
##### Request
Exampleapplication/json
application/json Copy
```
{
"data": {
"document_sets": {
"document_set": [
{
"documents": {
"document": [
{
"content": {
"foreign_object": {
"reference": {
"location_label_value": "7f7703df-5653-4697-beb3-d716c185fc25"
}
}
},
"signatories": {
"signatory": [
{
"allow_decline": true,
"signees": {
"signee": [
{
"name": "Jon Snow",
"email": "jon.snow@hbo.com"
}
]
}
}
]
}
}
]
}
}
]
}
}
}
```
application/json Copy
```
{
"data": {
"document_sets": {
"document_set": [
{
"documents": {
"document": [
{
"content": {
"foreign_object": {
"reference": {
"location_label_value": null
}
}
},
"signatories": {
"signatory": [
{
"allow_decline": true,
"signees": {
"signee": [
{
"name": null,
"email": null
}
]
}
}
]
}
}
]
}
}
]
}
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
| `Content-Type` required | `string` header | — | — |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `data`required | `object` | — |
##### Response `400``application/json`
2 fields
Missing elements
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `errors` | `object` | List of elements that are missing |
##### Other responses
`200`
`GET` `/response-elements`
#### Retrieve Response Elements
`get-esign-response-elements`
Retrieve Response Elements retrieves a list of the electronic signature elements returned by an eSign data partner.
##### Response
application/json Copy Elements needed for request.
```
{
"$.document_sets.document_set[0].documents.document[0].signatories.signatory[0].electronic_signature.foreign_object.location_label_value": null,
"$.document_sets.document_set[0].documents.document[0].signatories.signatory[0].is_complete": null,
"$.document_sets.document_set[0].documents.document[0].signatories.signatory[0].is_rejected": null,
"$.document_sets.document_set[0].documents.document[0].signatories.signatory[0].signees.signee[0].name": null,
"$.document_sets.document_set[0].documents.document[0].signatories.signatory[0].signees.signee[0].email": null,
"$.document_sets.document_set[0].documents.document[0].signatories.signatory[0].signees.signee[0].status": null
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
##### Other responses
`200``400`
`GET` `/status/{transaction_id}/{collection_id}`
#### Retrieve Status
`get-esign-status`
Retrieve Status determines if a data partner has executed an eSignature for a document.
##### Response
200404
application/json Copy Statuses include: * REQUEST_MADE * WAITING_FOR_SIGNATURES
* COMPLETED
* ERROR
```
{
"status": "COMPLETED"
}
```
application/json Copy Status is unavailable
```
{
"error": "Request for specified transaction_id and collection_id was not found!"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `transaction_id` required | `string (uuid)` path | `9u8z7t65-cb71-4f20-8e40-7a829b52e91e` | Transaction ID |
| `collection_id` required | `string (uuid)` path | `e4502ed2-8df8-4b8f-84bd-a1097e999a77` | Collection ID |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
##### Response `200``application/json`
1 fields
Statuses include: * REQUEST_MADE
* WAITING_FOR_SIGNATURES
* COMPLETED
* ERROR
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Current execution status`WAITING_FOR_SIGNATURES``COMPLETED``ERROR``REQUEST_MADE` |
##### Response `404``application/json`
1 fields
Status is unavailable
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message |
##### Other responses
`400``403`
`POST` `/transactions`
#### Create Transaction
`post-esign-transaction`
Create Transaction creates a transaction in Staircase.
Transactions in Staircase are containers for all of the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business.
Transactions are identified by a unique key called transaction_id. As you use different Staircase products to gather the data needed for a specific instance of your transaction type, and receive different sets of output from each product, use the same transaction_id to correlate all of the outputs to the same transaction.
A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.
##### Response
application/json Copy Transaction successfully created.
```
{
"transaction_id": "a34c40a6-3c02-44f9-a696-cd7388f506d3"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
##### Response `201``application/json`
1 fields
Transaction successfully created.
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string` | Transaction ID |
##### Other responses
`400`
`GET` `/transactions/{transaction_id}/collections`
#### Retrieve Transaction Collections
`get-esign-transactions-collections`
Retrieve Transaction Collections retrieves a list of all collections associated with a transaction.
##### Response
200400
application/json Copy Transaction's list of collections successfully retrieved.
```
{
"collections": [
{
"collection_id": "hg62e49f-9d74-g17e-99ca-a36b30vdfd35",
"data": {
"document_sets": {
"document_set": [
{
"documents": {
"document": [
{
"content": {
"foreign_object": {
"reference": {
"location_label_value": "7f7703df-5653-4697-beb3-d716c185fc25"
}
}
},
"signatories": {
"signatory": [
{
"allow_decline": true,
"signees": {
"signee": [
{
"name": "Jon Snow",
"email": "jon.snow@hbo.com"
}
]
}
}
]
}
}
]
}
}
]
}
},
"metadata": {},
"transaction_id": "6t5r4wq1-9d74-g17e-99ca-a36b30vdfd35"
},
{
"collection_id": "b441470e-007c-4221-83c6-88db7e7594e0",
"data": {
"document_sets": {
"document_set": [
{
"documents": {
"document": [
{
"content": {
"foreign_object": {
"reference": {
"location_label_value": "7e62ce76-d93d-4f31-92d3-45c2cb8255ea"
}
}
},
"signatories": {
"signatory": [
{
"allow_decline": true,
"signees": {
"signee": [
{
"name": "John Doe",
"email": "john.doe@example.com"
}
]
}
}
]
}
}
]
},
"metadata": {}
}
]
}
},
"transaction_id": "6t5r4wq1-9d74-g17e-99ca-a36b30vdfd35"
}
]
}
```
application/json Copy Data validation request failed
```
{
"error": "Error creating collection.",
"status_code": 400,
"status_message": "{'data': ['Missing data for required field.']}"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `transaction_id` required | `string (uuid)` path | `3wet53r4-cb71-8u74-8e40-7a829b52e91e` | Transaction ID |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API Key |
##### Response `200``application/json`
1 fields
Transaction's list of collections successfully retrieved.
| Field | Type | Description |
| --- | --- | --- |
| `collections` | `array` | Data object |
##### Response `400``application/json`
3 fields
Data validation request failed
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message |
| `status_code` | `integer` | Status code |
| `status_message` | `string` | Status message |
##### Other responses
`404`
`POST` `/transactions/{transaction_id}/collections`
#### Create Collection
`post-esign-collection`
Create Collection creates a collection of elements required for eSign. A collection contains a digital representation of a document and is identified by collection_id. The collection, rather than a document, is passed to a data partner when requesting an electronic signature.
Before you can create a document collection, make sure you have:
- an api_key (authorization key), received via email when you signed up for Staircase.
- a transaction_id,created by invoking Create Transaction.
To create a document collection and receive a collection_id in response, you first need to complete 2 tasks:
Show the rest
1. Upload your document to Staircase, and
1. Create a json schema that describes a document.
To upload a document to Staircase:
1. Create a blob by invoking Create Blob. The blob is a container for your document, and is represented by a blob_id, which is returned by the service.
1. Upload your document (blob) to Staircase, using your blob_id. See Upload Blob for more detail.
There are a couple of ways you can create a json schema that describes a document:
1. Copy the example json schema given below for the request body, and insert your blob_id into the location_label_value schema element, or
1. Invoke Retrieve Product Elements Structure to get an example json schema. Insert your blob_id into the location_label_value schema element.
Once you have created a collection, you can send it, along with your api_key and transaction_id, to as many eSign data partners as you want.
##### Request
Exampleapplication/json
application/json Copy
```
{
"data": {
"document_sets": {
"document_set": [
{
"documents": {
"document": [
{
"content": {
"foreign_object": {
"reference": {
"location_label_value": "a7b098f5-e2d4-4c97-901c-e2abefcbc5dc"
}
}
},
"signatories": {
"signatory": [
{
"allow_decline": true,
"signees": {
"signee": [
{
"name": "Jon Snow",
"email": "jon.snow@hbo.com"
}
]
}
}
]
}
}
]
}
}
]
}
}
}
```
application/json Copy
```
{
"data": {
"document_sets": {
"document_set": [
{
"documents": {
"document": [
{
"content": {
"foreign_object": {
"reference": {
"location_label_value": ""
}
}
},
"signatories": {
"signatory": [
{
"allow_decline": true,
"signees": {
"signee": [
{
"name": "",
"email": ""
}
]
}
}
]
}
}
]
}
}
]
}
}
}
```
##### Response
application/json Copy Data validation request failed
```
{
"error": "Error creating collection.",
"status_code": 400,
"status_message": "{'data': ['Missing data for required field.']}"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `transaction_id` required | `string (uuid)` path | `3wet53r4-cb71-8u74-8e40-7a829b52e91e` | Transaction ID |
| `x-api-key` | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
| `Content-Type` required | `string` header | — | — |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `data`required | `object` | — |
| `metadata` | `object` | — |
##### Response `201``application/json`
4 fields
Collection successfully created.
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string` | Transaction ID |
| `collection_id` | `string` | Collection ID |
| `data` | `object` | Data object |
| `metadata` | `object` | Metadata object |
##### Response `400``application/json`
3 fields
Data validation request failed
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message |
| `status_code` | `integer` | Status code |
| `status_message` | `string` | Status message |
##### Other responses
`403``404`
`GET` `/transactions/{transaction_id}/collections/{collection_id}`
#### Retrieve Collection
`get-esign-collection`
Retrieve Collection retrieves a collection containing a document that has been electronically signed.
##### Response
application/json Copy Collection retrieved successfully
```
{
"collection_id": "hg62e49f-9d74-g17e-99ca-a36b30vdfd35",
"data": {
"document_sets": {
"document_set": [
{
"documents": {
"document": [
{
"content": {
"foreign_object": {
"reference": {
"location_label_value": "7e62ce76-d93d-4f31-92d3-45c2cb8255ea"
}
}
},
"signatories": {
"signatory": [
{
"allow_decline": true,
"signees": {
"signee": [
{
"name": "Jon Snow",
"email": "jon.snow@hbo.com"
}
]
}
}
]
}
}
]
}
}
]
}
},
"metadata": {},
"transaction_id": "6t5r4wq1-9d74-g17e-99ca-a36b30vdfd35"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `transaction_id` required | `string (uuid)` path | `7b95d83e-105b-4610-c199-a4843fcb7027` | Transaction ID |
| `collection_id` required | `string (uuid)` path | `9aad2227-4a36-5ea9-91d0-6342aaa18a05` | Collection ID |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
##### Response `200``application/json`
4 fields
Collection retrieved successfully
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string` | Transaction ID |
| `collection_id` | `string` | Collection ID |
| `data` | `object` | Data object |
| `metadata` | `object` | Metadata object |
##### Response `400``application/json`
3 fields
Data validation request failed
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message |
| `status_code` | `integer` | Status code |
| `status_message` | `string` | Status message |
##### Other responses
`403``404`
`PUT` `/transactions/{transaction_id}/collections/{collection_id}`
#### Update Collection
`put-esign-collection`
Update Collection updates a collection of elements required for an electronic signature.
##### Request
Exampleapplication/json
application/json Copy
```
{
"data": {
"document_sets": {
"document_set": [
{
"documents": {
"document": [
{
"content": {
"foreign_object": {
"reference": {
"location_label_value": "a7b098f5-e2d4-4c97-901c-e2abefcbc5dc"
}
}
},
"signatories": {
"signatory": [
{
"allow_decline": true,
"signees": {
"signee": [
{
"name": "Jon Snow",
"email": "jon.snow@hbo.com"
}
]
}
}
]
}
}
]
}
}
]
}
}
}
```
application/json Copy
```
{
"data": {
"document_sets": {
"document_set": [
{
"documents": {
"document": [
{
"content": {
"foreign_object": {
"reference": {
"location_label_value": ""
}
}
},
"signatories": {
"signatory": [
{
"allow_decline": true,
"signees": {
"signee": [
{
"name": "",
"email": ""
}
]
}
}
]
}
}
]
}
}
]
}
}
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `transaction_id` required | `string (uuid)` path | `3wet53r4-cb71-8u74-8e40-7a829b52e91e` | Transaction ID |
| `collection_id` required | `string (uuid)` path | `9u8z7t65-cb71-8u74-8e40-7a829b52e91e` | Transaction ID |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API Key |
| `Content-Type` required | `string` header | — | — |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `data`required | `object` | — |
| `metadata` | `object` | — |
##### Response `200``application/json`
4 fields
Collection successfully updated
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string` | Transaction ID |
| `collection_id` | `string` | Collection ID |
| `data` | `object` | Data object |
| `metadata` | `object` | Metadata object |
##### Other responses
`400``403``404`
## Errors
`400``403``404``406`
## More in Contract
- Previous product: Price
- Next product: Title