The Sign API is an offering of Rabo Identity Services to sign documents with various signing methods. You can define and integrate the entire signing flow into your own business and company branding.
We support various endpoints and flexibility to support a large number of business requirements.
Each signing flow consists of the below mandatory steps:
- Uploading the document(s)
- Creating the signing order
- Downloading the signed document(s)
Continuing the flow, all the characteristics of a specific order should be defined, example:
- Number of documents to be signed.
- Number of signatories required to sign specific documents.
- Dependencies between signatories.
- Notifications to invite signatories and/or inform your own backend application on status changes.
- Generation process of signed documents.
- Signing methods allowed to be used by the signatories.
More information on the possibilities on the API can be found in the API specifications.
Using the API
After your account set up is complete, subscribe the Sign API to your application.
Upload a document
Upload the PDF document to be signed by the signatory using a POST request and apply the Content-Type application/pdf
POST https://api.rabobank.nl/openapi/ris/sign/documentsEach uploaded document generates a unique documentId
{
"documentId": "100420245qd24azed9o7yx5grbfdntzxo1s91jfbh6cu3cgn6k2n5frtku"
}If multiple documents need to be signed, you can invoke the upload endpoint multiple times. You should reference the unique documentId when creating a Signing order.
The maximum file upload size is 5 MB.
Create a signing order
After uploading the document(s) to the platform, the unique documentId value(s) should be used in the Signing order request.
The signing order request contains all the specifications associated to that specific request. The signing order request is built up in three building blocks:
- The
order, containing alltaskandpackagingTaskobjects - The
task, defines the values for a specific signatory - The
packagingTask, defines how the signed document should be generated
For multiple documents, we provide two options:
- Generate a single PDF document containing all the uploaded documents including all signatures. In this case only one
packagingTaskshould be defined. - Generate several PDF documents containing specific uploaded documents and signatures. For each output document, a
packagingTaskshould be created.
In the below example, one task is defined where the signatory should sign a specific document with the iDIN Signing method. The packagingTask defines that a single PDF document should be generated with the obtained signature.
To view all possible parameters, read the endpoint description for POST/ris/sign/order
{
"tasks": [
{
"id": "8fe64ae0-a5ca-4066-a0c9-49ba7cf510e2",
"documents": [
{
"action": "SIGN",
"description": "Doc 1.pdf",
"documentRef": "100420245qd24azed9o7yx5grbfdntzxo1s91jfbh6cu3cgn6k2n5frtku",
"id": "ad0fba5b-3647-4e92-b50e-01e2b5df870c",
"source": "SESSION"
}
],
"signatureMethods": [
{
"handwritten": false,
"name": "idin-ident",
"type": "AUTHENTICATION_BASED"
}
],
"notifications": [
{
"id": "844e000a-6cc0-4b13-a622-79986a25fb36",
"header": "Document ready to be signed",
"message": "<insert message>",
"recipient": "[email protected]",
"schedule": [
{
"triggerStatus": "CREATED"
}
],
"sender": "[email protected]",
"type": "EMAIL"
}
]
}
],
"packagingTasks": [
{
"id": "4d02444b-755d-4264-a8fb-9368545e5c92",
"sendToArchive": false,
"method": "pades",
"notifications": [
{
"id": "36b99c1e-b2bd-41a8-ab09-8c1c49a61d70",
"header": "Document ready to be signed",
"message": "<insert message>",
"recipient": "[email protected]",
"schedule": [
{
"triggerStatus": "COMPLETED"
}
],
"sender": "[email protected]",
"type": "EMAIL"
}
],
"documents": [
{
"taskId": "8fe64ae0-a5ca-4066-a0c9-49ba7cf510e2",
"documentIds": [
"ad0fba5b-3647-4e92-b50e-01e2b5df870c"
]
}
]
}
]
}After the request is created, a unique id is generated for each order. The signingUrl field in the task object contains a URL where the signatory can view and sign the document.
{
"id": "100420242c7t5yagf64jjl2h28yn8h49opzlam45715liuow3q9pzwg5e8",
"tasks": [
{
"id": "8fe64ae0-a5ca-4066-a0c9-49ba7cf510e2",
"documents": [
{
"id": "ad0fba5b-3647-4e92-b50e-01e2b5df870c",
"description": "Doc 1.pdf",
"action": "SIGN",
"source": "SESSION",
"documentRef": "100420245qd24azed9o7yx5grbfdntzxo1s91jfbh6cu3cgn6k2n5frtku",
"sendResultToArchive": false
}
],
"signatureMethods": [
{
"name": "idin-ident",
"type": "AUTHENTICATION_BASED",
"handwritten": false
}
],
"notifications": [
{
"id": "844e000a-6cc0-4b13-a622-79986a25fb36",
"recipient": "[email protected]",
"sender": "[email protected]",
"header": "Document ready to be signed",
"message": "<insert message>",
"type": "EMAIL",
"schedule": [
{
"triggerStatus": "CREATED",
"delay": {}
}
]
}
],
"signingUrl": "https://api.rabobank.nl/std/docaction/rabobank?request_id=100420242c7t5yagf64jjl2h28yn8h49opzlam45715liuow3q9pzwg5e8&task_id=8fe64ae0-a5ca-4066-a0c9-49ba7cf510e2"
}
],
"packagingTasks": [
{
"id": "4d02444b-755d-4264-a8fb-9368545e5c92",
"sendToArchive": false,
"method": "pades",
"notifications": [
{
"id": "36b99c1e-b2bd-41a8-ab09-8c1c49a61d70",
"recipient": "[email protected]",
"sender": "[email protected]",
"header": "Document ready to be signed",
"message": "<insert message>",
"type": "EMAIL",
"schedule": [
{
"triggerStatus": "COMPLETED"
}
]
}
],
"documents": [
{
"taskId": "8fe64ae0-a5ca-4066-a0c9-49ba7cf510e2",
"documentIds": [
"ad0fba5b-3647-4e92-b50e-01e2b5df870c"
]
}
]
}
]
}After the signing order is created, the signatory should be invited to sign the document.
You can define the notification category in the notification:
EMAIL, to send out email notifications to a defined email addressSMS, to send out SMS notifications to a defined mobile phone numberURL, to send out webhook notifications to your own backend
To view all possible parameters, read the notification object description for POST /ris/sign/order
Notifications can be defined on several levels:
order, this notifiation is associated to the entireorderand is triggered when alltasksare completedtask, this notification is associated to thetaskonlypackagingTask, this notifiaction is associated to thepackagingTaskonly
All notification objects support a schedule object, which can be used to further define the notification trigger. For example, this can be done on the CREATED, COMPLETED values as illustrated in the example above.
Retrieve the signed document
After the signing order is completed and all signatures are collected by the platform, the final signed document(s) can be retrieved by invoking the GET/result endpoint.
The signed document is returned in a PDF format and contains the collected evidence.
GET sign/orders/:orderId/packaging-tasks/:packagingTaskId/resultAdditional functionality
Besides the illustrated basic signing order flow, there are other features that can be applied in the signing order, which may be useful.
Retrieving status updates
After the signing order is created, it's possible to retrieve intermediate updates. The following two endpoints provide status updates on both task level and packagingTask level.
task events
GET /ris/sign/orders/:orderId/tasks/:taskId/statuspackagingTask events
GET /ris/sign/orders/:orderId/packaging-tasks/:packaging-tasks/statusGraphical profiles
Rabobank facilitates the frontend with Document viewer, which is easily customizable. For more information, contact your Implementation manager.
Task dependencies
In case multiple signatories are required to sign a certain document in a sequence, example, Person A should sign the document before Person B. You can add task dependencies to the signing order.
- Each response contains a X-Trace-Id header which can be used for troubleshooting failed transactions
- Certain fields may not be available in the response body, this depends on the availability in the source and the type of request. Read the response schema object to understand which fields can be part of the response body.
Other scenarios
All functionality can be tested out in Sandbox.
All responses are signed by Rabobank, to validate the response read Validate signed responses