The Sign API through Rabo Identity Services (RIS), offers an digital signing solution for organizations to digitally sign legally binding documents. ## Before you begin Make sure you have a working sandbox account in the [Rabobank developer portal](https://developer.rabobank.nl/). Read [Get Started](https://developer.rabobank.nl/get-started) to set up an account and register an **Application**. **NOTE**: To use these API(s), a valid [TLS](https://developer.rabobank.nl/how-use-mutual-tls) certificate is required. ## Using the API After your account set up is complete, subscribe the **Sign API** to your application.

You should create separate applications for the pre-production and production environments to efficiently differentiate the API traffic.

## Upload a document Upload the PDF document to be signed by the signatory using a POST request and apply the `Content-Type application/pdf` ```json POST https://api.rabobank.nl/openapi/ris/sign/documents ``` Each uploaded document generates a unique `documentId` ```json { "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 all `task` and `packagingTask` objects - 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 `packagingTask` should be defined. - Generate several PDF documents containing specific uploaded documents and signatures. For each output document, a `packagingTask` should 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` ```json { "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": "", "recipient": "noreply@rabobank.nl", "schedule": [ { "triggerStatus": "CREATED" } ], "sender": "noreply@rabobank.nl", "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": "", "recipient": "noreply@rabobank.nl", "schedule": [ { "triggerStatus": "COMPLETED" } ], "sender": "noreply@rabobank.nl", "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. ```json { "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": "noreply@rabobank.nl", "sender": "noreply@rabobank.nl", "header": "Document ready to be signed", "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": "noreply@rabobank.nl", "sender": "noreply@rabobank.nl", "header": "Document ready to be signed", "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 address - `SMS`, to send out SMS notifications to a defined mobile phone number - `URL`, 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 entire `order` and is triggered when all `tasks` are completed - `task`, this notification is associated to the `task` only - `packagingTask`, this notifiaction is associated to the `packagingTask` only 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. ```json GET sign/orders/:orderId/packaging-tasks/:packagingTaskId/result ``` ## Additional 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 ```json GET /ris/sign/orders/:orderId/tasks/:taskId/status ``` `packagingTask` events ```json GET /ris/sign/orders/:orderId/packaging-tasks/:packaging-tasks/status ``` ### Graphical 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. ## Other scenarios All functionality can be tested out in Sandbox.

- 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.

All responses are signed by Rabobank, to validate the response read [Validate signed responses](https://developer.rabobank.nl/validate-signed-responses)