Back to Developers
Getting Started Authentication Document Workflows Resources What's New in API v2

API version:

Sending requests
Send custom documents for signature

Metadata

:author:
  :name: RightSignature
  :contact: support@rightsignature.com
:last_modified: 12-14-2021

Supported Formats

json
>>>

GET /public/v2/sending_requests/:id
Return the processing status of an existing Sending Request

Returns the status of the sending request.

Supported Formats

json

Errors

Code Description
400 invalid_scope
400 unauthorized_client
401 Could not find resource owner
401 Resource owner is not entitled
401 invalid_token
401 Must be authenticated.
401 Unauthorized application.
422 Bad input parameter. Error message should indicate which one and why.
404 Sending Request not found.
404 Sending Request '<ID>' not found.

Examples

GET /public/{version}/sending_requests/94816d85-f003-461d-bd23-021df5814e54
200
{
  "id": "94816d85-f003-461d-bd23-021df5814e54",
  "status": "waiting_for_file",
  "status_message": null,
  "upload_url": "https://rightsignature-sr-development.s3.amazonaws.com/public_api/sending_requests/94816d85-f003-461d-bd23-021df5814e54/test.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJSRMQNOZ6XOBJZ4A%2F20180507%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20180507T152332Z&X-Amz-Expires=3600&X-Amz-Signature=444cef94d31991e1f8c4d2de2423c9b2cd8bbd286a51fc2b494307c3cea7c02f&X-Amz-SignedHeaders=Host&x-amz-acl=private",
  "document_template_id": null,
  "created_at": "2018-05-07T08:23:32.620-07:00",
  "updated_at": "2018-05-07T08:23:32.620-07:00"
}

Params

Param name Description
id
required

Sending Request id

Validations:

  • Must be a String
>>>

POST /public/v2/sending_requests
Create a Sending Request

This generates a Sending Request for a one-off Document with a file.

The request will contain the file and Document attributes, that will be delivered after the file is uploaded.

The response will contain a upload_url where you can PUT to upload the file.

It is important to call api.rightsignature.com/public/{version}/sending_requests/:id/uploaded after the file is uploaded, to trigger the Document creation.

To upload the file, do a PUT to the response's upload_url with the file in the body. Ex. response

  {
"sending_request": {
  "id": "09001350-1853-471c-955a-abb7d3120aa1",
  "upload_url": "https://rightsignature-sr-production.s3.amazonaws.comsending_requests/dbc73bba-2fe6-4a73-a227-3d221e97fa4a/testSR.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJ6XOWM37KL6IPHHA%2F20160811%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20160811T192204Z&X-Amz-Expires=3600&X-Amz-Signature=9016aea2d753c1bc07e75b27c472cbced86f3f30957152c96aec1eae01b9d191&X-Amz-SignedHeaders=Host&x-amz-acl=private",
  "document_template_id":null,
  "created_at":"2016-08-10T18:57:29.400-07:00",
  "updated_at":"2016-08-10T18:57:29.400-07:00"
}

}

Ex. curl command to upload location file test_post.pdf

curl -v -X PUT -F 'file=@test_post.pdf' 'https://rightsignature-sr-production.s3.amazonaws.comsending_requests/dbc73bba-2fe6-4a73-a227-3d221e97fa4a/testSR.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJ6XOWM37KL6IPHHA%2F20160811%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20160811T192204Z&X-Amz-Expires=3600&X-Amz-Signature=9016aea2d753c1bc07e75b27c472cbced86f3f30957152c96aec1eae01b9d191&X-Amz-SignedHeaders=Host&x-amz-acl=private'

After uploading, you will need to do a POST to api.rightsignature.com/public/{version}/sending_requests/:id/uploaded.

Supported Formats

json

Errors

Code Description
400 invalid_scope
400 unauthorized_client
401 Could not find resource owner
401 Resource owner is not entitled
401 invalid_token
401 Must be authenticated.
401 Unauthorized application.
422 Bad input parameter. Error message should indicate which one and why.
404 User account is not enabled.
404 User has reached document limit.

Examples

POST /public/{version}/sending_requests
{
  "file": {
    "name": "my_upload.pdf",
    "source": "upload"
  },
  "document": {
    "signer_sequencing": false,
    "expires_in": 12,
    "name": "Sign me",
    "roles": [
      {
        "name": "a",
        "signer_name": "Geoff E",
        "signer_email": "geoff@example.com"
      }
    ]
  },
  "sending_request": {}
}
200
{
  "sending_request": {
    "id": "bf98b25c-a16b-4709-82fc-54034e736077",
    "status": "waiting_for_file",
    "status_message": null,
    "upload_url": "https://rightsignature-sr-development.s3.amazonaws.com/public_api/sending_requests/bf98b25c-a16b-4709-82fc-54034e736077/my_upload.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJSRMQNOZ6XOBJZ4A%2F20180507%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20180507T152332Z&X-Amz-Expires=3600&X-Amz-Signature=6ceecd6dfcf75b208b3cfd1386d9e6cd54c8df5ad9daa648fcc37fedef70f90f&X-Amz-SignedHeaders=Host&x-amz-acl=private",
    "document_template_id": null,
    "created_at": "2018-05-07T08:23:32.772-07:00",
    "updated_at": "2018-05-07T08:23:32.772-07:00"
  }
}

Params

Param name Description
file
required

Upload file information

Validations:

  • Must be a Hash
file[name]
required

Filename withe extension

Validations:

  • Must be a String
file[source]
required

Source of file. Only 'upload' is supported.

Validations:

  • Must be one of: upload, remote_file.
document
required

Document information

Validations:

  • Must be a Hash
document[name]
required

Document name

Validations:

  • Must be a valid string.
document[signer_sequencing]
required

Send to signers in specified sequence.

Validations:

  • Must be one of: true, false.
document[personalized_messages]
optional

Use custom messages per signer. Specified in 'roles' attribute.

Validations:

  • Must be one of: true, false.
document[shared_with]
optional

Array of emails to CC document.

Validations:

  • Must be an array of String
document[identity_method]
optional

How to authenticate signers (email | none).

Validations:

  • Must be one of: email, none.
document[callback_url]
optional

Document callback url. The URL will receive a POST for each of the following document events: created, viewed, signed, executed, voided, declined. Note that due to the asynchronous nature of processing, the order in which the document callbacks are sent is not guaranteed. Only HTTP ports 80, 8000-8099, 3000-3009 and HTTPS port 443 is supported. Basic auth is also supported. Ex. “me:pass@yourhost.example:8001/callback”.

Note: This is different from the sending request callback url which receives status updates regarding the sending request itself.

ex. callback when document is viewed

{
  "callbackType":"Document",
  "id":"edc7823a-7b99-45d7-9c3c-c7dc81f8dbf2",
  "event":"viewed",
  "documentState":"pending",
  "createdAt":"2016-11-14T13:45:23.199-08:00"
}

Validations:

  • Must be a String
document[api_embedded]
optional

Whether the document should be embedded.

Validations:

  • Must be one of: true, false.
document[api_embed_width]
optional

Embed width
document[api_embed_height]
optional

Embed height
document[roles]
required

Document signers

Validations:

  • Must be an Array of nested elements
document[roles][name]
required

Role name. For text tags, the role name in the request must correspond to the recipient name given as the second argument (name) in the text tag. When signer sequencing is enabled, the role name must match the signer name set on the template.

Validations:

  • Must be a valid string.
document[roles][signer_name]
required

Signer name

Validations:

  • Must be a valid string.
document[roles][is_sender]
optional

Is signer the owner of document?

Validations:

  • Must be one of: true, false.
document[roles][sequence]
optional

Signer order (starting at 0), required if signer_sequencing is enabled.

Validations:

  • Must be a number.
document[roles][message]
optional

Custom message to signer.

Validations:

  • Must be a String
document[roles][signer_email]
required

Signer email

Validations:

  • Must be a String
document[expires_in]
required

Document expiration. Must be between 1 and 365 days
document[pin]
optional

Document pin. Must be between 10000 and 99999
document[tags]
optional

Optional key value tags for categorization
document[kba]
optional

Enable KBA on the document (applicable for KBA enabled plans)

Validations:

  • Must be one of: true, false.
callback_url
optional

URL to receive sending request status updates. The URL will receive a POST when the sending request is sent as a document or an error occured in processing. Only HTTP ports 80, 8000-8099, 3000-3009 and HTTPS port 443 is supported. Basic auth is also supported. Ex. value: “me:pass@yourhost.example/req_callback” ex. callback when successful {

"sending_request": {
  "id": "09001350-1853-471c-955a-abb7d3120aa1",
  "status": "completed",
  "document_template_id": "733816f6-939f-4a8d-98de-55e357ab07d4",
  "created_at":"2016-08-10T18:57:29.400-07:00",
  "updated_at":"2016-08-10T19:05:11.100-07:00"
}

} ex. callback when processing fails {

"sending_request": {
  "id": "09001350-1853-471c-955a-abb7d3120aa1",
  "status": "errored",
  "status_message": "File was password protected"
  "document_template_id": null,
  "created_at":"2016-08-10T18:57:29.400-07:00",
  "updated_at":"2016-08-10T19:05:11.100-07:00"
}

}

Validations:

  • Must be a String
>>>

POST /public/v2/sending_requests/:id/uploaded
Create a new Sending Request to ultimately send a one-off Document

Triggers the processing of the uploaded file into a Document. The file must be completely uploaded to the Sending Request's upload_url. Processing happens asynchronously, use api.rightsignature.com/public/v2/sending_requests/SENDING_REQUEST_ID to check the status or wait for updates if callback_url is set.

Supported Formats

json

Errors

Code Description
400 invalid_scope
400 unauthorized_client
401 Could not find resource owner
401 Resource owner is not entitled
401 invalid_token
401 Must be authenticated.
401 Unauthorized application.
422 Bad input parameter. Error message should indicate which one and why.
404 Sending Request not found.
404 Sending Request '<ID>' not found.
404 Sending Request already processed.

Examples

POST /public/{version}/sending_requests/SENDING_REQUEST_ID/uploaded

curl -H "Accept: application/json" -H "Content-Type: application/json" -X POST https://api.rightsignature.com/public/{version}/sending_requests/SENDING_REQUEST_ID/uploaded

{
  "id": SENDING_REQUEST_ID,
  "status": "processing",
  "status_message": null,
  "document_template_id": null,
  "created_at": "created date and time",
  "updated_at": "updated date and time",
  "document_preparation_url": null
}

Params

Param name Description
id
required

Sending Request ID

Validations:

  • Must be a String
prepare_document
optional

Whether the document should be sent or an url to be returned for preparing the document

Validations:

  • Must be one of: true, false.