SignHero API v2. Protocol Design Principles. API Key Authentication

Transcription

1 SignHero API v2 Protocol Design Principles API Key Authentication Access Token Revocation Create Signature Flow Documents Create Signing Process Retrieve Signature Flow Search Signature Flows Cancel Signature Flow Delete Signature Flow Protocol Design Principles Protocols are designed using JSON-pure principles over HTTP POST. All character sets are UTF-8. All requests have MIME type application/json, except document uploads, which have MIME type multipart/form-data. All responses are JSON objects with MIME type application/json, except document downloads, which are binary streams with MIME type application/pdf. API Key Authentication Clients are authenticated using access tokens obtained by presenting a shared secret. POST "action_str" : "create", "data_type" : "access_token", "request_map" : "client_id" : "123e4567-e89b-12d3-a ", "client_secret" : "1498b03d760b233673e0955ea00f8270ccf3a2e22093e69fc112168bb486ab29"

2 Response "action_str" : "created", "data_type" : "access_token", "user_msg": "access_token created", "trans_map" : "auth_key" : Access Token Revocation To disable your current access token, send a request to the authentication endpoint: POST "action_str" : "delete", "data_type" : "access_token", "trans_map":, "request_map":

3 Response "action_str": "deleted", "data_type": "access_token", "user_msg": "access_token deleted", "response_map":, "trans_map": You can also disable all your access tokens with one request: POST "action_str" : "delete", "data_type" : "access_tokens", "trans_map":, "request_map":

4 Response "action_str": "deleted", "data_type": "access_tokens", "user_msg": "access_tokens deleted", "response_map":, "trans_map": Create Signature Flow Creating a signature flow is a two-part operation: first, upload the documents to sign, second, create the process which signs them. Documents To upload a document post a multipart/form-data request to the documents endpoint: POST The multi-part request needs to include a payload_data field, which contains the document to sign, and an operation_data field, which contains the JSON-Pure object Content-Disposition: form-data; name="operation_data" "action_str":"create","data_type":"document","log_list":["trans_map":" auth_key":"ywmtgeygak_ceeahbgx148sd2waaavip_r17t2xygd71ijdlworpwnvxcxk19n4 ","request_map": Content-Disposition: form-data; name="payload_data"; filename="contract.pdf" Content-Type: application/pdf %PDF-1.5

5 Response "action_str": "created", "data_type": "document", "user_msg": "document created", "trans_map":, "response_map": "document_id": "d807b62c-08bb-11e7-a cc4" To get a copy of the current document make a download request to the documents endpoint. "action_str": "retrieve", "data_type": "document", "trans_map":, "request_map": "document_id": "d807b62c-08bb-11e7-a cc4" The successful response is a binary stream with MIME type application/pdf. Create Signing Process To create a signing process send a request which lists the identifiers of the uploaded documents as well as the rest of the information about the signing process. POST Map title Title for the signature flow.

6 locale signature_invitation signature_invitation:subject signature_invitation:message documents document:id signers signer:name signer: signer:locale Language of the signing page and s. Supported locales are en and fi. Defaults to en. Signature invitation. Subject of the sent to the signers. Custom message in the sent to the signers. Array of documents sent for signature. Identifier of the document. Array of signers. Name of the signer. address of the signer. Language of the signing page and s. Supported locales are en and fi. Defaults to the locale of the signature flow. "action_str": "create", "trans_map":, "request_map": "title": "My first signature flow", "locale": "en", "signature_invitation": "subject": "Please sign this important contract", "message": "This contract is very important, please sign it right now.", "documents": [ "d807b62c-08bb-11e7-a cc4" "signers": [ "name": "Wilberforce Ahab", " ": "Wilberforce.Ahab@acme.com" ] The successful response includes the identifiers of the process and signers.

7 Response "action_str": "created", "user_msg": "signature_flow created", "trans_map":, "response_map": "process_id": "d7e bb-11e7-a cc4", "signers": [ "2d871e79-0b23-11e7-93dc ef10" ] Retrieve Signature Flow Retrieves the details and status of a signature flow. POST "action_str": "retrieve", "trans_map":, "request_map": "process_id": "ae3b e7-a cfede40" Response Map created modified Time when the signature flow was created. Time when the signature flow was last modified.

8 completed canceled status pending_count documents signers signer:status signer:signed signer:declined Time when the signature flow was completed. Time when the signature flow was canceled. Status of the signature flow: pending, declined, completed or canceled. Number of pending signatures. List of documents sent for signature. List of signers. Status of the signer: pending, signed or declined. Time when the signer signed the documents. Time when the signer declined to sign. Response

9 "action_str": "retrieved", "user_msg": "signature_flow retrieved", "trans_map":, "response_map": "uuid" : "ae3b e7-a cfede40", "title": "My second signature flow", "created": , "modified": , "status": "completed", "pending_count": 0, "require_strong_auth": false, "signature_invitation": "subject": "Signature invitation", "message": "Your signature is requested for a document, using SignHero digital signatures service.", "locale": "en", "documents": [ "uuid": "aebd05c e7-93dc ef10", "file_name": "contract.pdf" "signers": [ "uuid": "ae8a5cf e7-93dc ef10", "name": "Wilberforce Ahab", " ": "Wilberforce.Ahab@acme.com", "locale": "en", "embed": false, "status": "signed", "signed": "completed":

10 Search Signature Flows You can retrieve all your flows or search them based on their status. POST Map status scope Filters results based on the status field. Accepted values are pending, completed and canceled. Constrains search results to only processes created by the user. Accepted values are user and group. Defaults to user. limit Number of results to return. The maximum number of results is cursor Cursor to retrieve the next set of results. "action_str": "retrieve", "data_type": "signature_flows", "trans_map":, "request_map": "status": "pending", "scope" : "user", "limit": 1 Response Map cursor To retrieve the next set of results, pass this cursor in the request map with your next call.

11 Response "action_str": "retrieved", "data_type": "signature_flows", "user_msg": "signature_flows retrieved", "trans_map":, "request_map": "signature_flows": [ "uuid" : "d7e bb-11e7-a cc4", "title": "My first signature flow", "created": , "modified": , "status": "pending", "pending_count": 1, "locale": "en" "cursor": "OikKAfqAM_qDdXVpZGM4M2FhZWVmMy0wMjU2LTExZTctYjM5Ni0wMjQyOWYyOTU1ZGSDdHlwZ UtzaWduX3Byb2Nlc3P7gDHS-w==" Cancel Signature Flow A signature flow that has not been completed can be canceled. Signers will not be able to review and sign the documents anymore. POST

12 "action_str": "update", "trans_map":, "request_map": "process_id": "ae3b e7-a cfede40", "cancel": true Response "action_str": "updated", "user_msg": "signature_flow updated", "response_map":, "trans_map": Delete Signature Flow A signature flow that has been completed or canceled can be deleted from search results. POST

13 "action_str": "delete", "trans_map":, "request_map": "process_id": "ae3b e7-a cfede40" Response "action_str": "deleted", "user_msg": "signature_flow deleted", "response_map":, "trans_map":