Start
Overview
You can start sign flow in legale by using this API.
You can pass multiple signers so that document can be signed by several persons in one flow.
You can check the status of document by using this API and get back the signed document by using this API if document was signed.
API detail
Request
- URL:
/sign/start/{{GUID}}
- Method:
POST
- Content-Type:
application/json
- Body:
{
"flow_type": "priority",
"expiration": 3,
"share_signed_document": true,
"signer_list": [
{
"sign_flow": "other",
"sign_method": "no_sms",
"email": "signer.email@legale.io",
"phone": null,
"firstname": "Signer",
"lastname1": "Name",
"lastname2": "Example",
"device_id": "E3EJJ305D-A91E-59FD-8A29-9D2E8C8B9CA4",
"video_validation": false,
"selfie_validation": false,
"id_validation": false,
"is_fingerprint": true,
"is_NID": true,
"x1": 255,
"y1": 255,
"x2": 295,
"y2": 325,
"pageno": 1,
"anchor": "Signer1",
"skip_email": true,
"sign_status_callback_url": "https://your.service.com/sign_callback",
},
]
}
Value | Type | Is required | Description |
---|---|---|---|
flow_type | str | No | Available values are priority , simultaneously . Default value is priority . If you set this value priority , document sign flow will flow one signer by one signer. This means document will be sent to next signer after completing the current signer's sign flow. If you set this value simultaneously , document will sent to all signer's at the same time, signers can sign document regardless other signers signed or not. |
expiration | int | No | This parameter is to determine the expiration date. It should be number in days. |
share_signed_document | bool | No | This parameter is to determine the email notification after sign. Default value is false . If you set this value as true , all signers will receive signed document email notification after sign process finished. |
signer_list
Value | Type | Is required | Description |
---|---|---|---|
sign_flow | str | Yes | Sign flow type |
sign_method | str | Yes | Sign method you wanna to use to sign document |
email | str | Yes | Signer email |
phone | str | No | Signer phone to use receive OTP. This parameter is needed when you set sign_method as sms |
firstname | str | No | Signer first name |
lastname1 | str | No | Signer first last name |
lastname2 | str | No | Signer second last name |
device_id | str | No | Device ID of your tablet or mobile device that you wanna send to sign. This parameter is needed when you set sign_method as tablet_sign |
video_validation | bool | Yes | To require the video validation of signer in Remote and Remote SMS method |
selfie_validation | bool | Yes | To require the selfie validation of signer in Remote and Remote SMS |
id_validation | bool | Yes | To require the Identity Documentation validation of signer in Remote and Remote SMS |
is_fingerprint | bool | No | To require fingerprint when you sign document on mobile device. This parameter is needed when you set sign_method as tablet_sign |
is_NID | bool | No | To require national ID image when you sign document on mobile device. This parameter is needed when you set sign_method as tablet_sign |
x1 , y1 , x2 , y2 | float | No | Signature image position coordinate. (x1, y1) is the left bottom corner, (x2, y2) is the top right corner. Origin of coordinate is bottom left corner of document. Recommended ratio of width to height of signature image position is 3:1 |
pageno | int | No | Page number of document to insert the signature image in. The first page of document is 1 . |
anchor | str | No | The specific word in your document which you want to put the signature image on. The start point of anchor text will be the top left corner of the signature image. The sign image size will be 180 * 60 px rectangle by default. |
skip_email | bool | No | If set true , system will not send an email to remote signer or approver, you can get sign urls from response. |
sign_status_callback_url | str | No | Sign callback URL of your service to get back the callback request of every sign status, system will send to this url the sign status. |
sign_flow
Available value | Available sign methods | Description |
---|---|---|
me | certification , local_certificate , sms , no_sms | Sign by myself, this means document will be signed by you. In this flow, you are the signer of document |
other | sms , no_sms | Sign by other person, this means document will be signed by other person, not by legale user. |
legale | certification , no_certification | Sign by legale user, this means document will be signed by other legale user. |
approve | approve , approve_legale , approve_api | This flow is to approve document by some persons, not adding digital signature into document, just approve current document sign flow by person. |
tablet | tablet_sign | This flow is to send document to tablet, on the tablet, you can add fingerprint into the document. |
signing_portal | signing_portal | This flow is to send document to sign in signing portal. |
sign_method
Available value | Available sign flows | Description |
---|---|---|
sms | me , other | Sign document using Remote SMS, signer will receive the sign request through his email. In this case, phone number is required, otherwise signer will not be able to receive OTP |
no_sms | me , other | Sign document using Remote, in this case, signer will receive the sign request through his email. No need to pass the phone number |
certification | me , legale | Sign document using cloud certificate, in this case, signer can be you or other legale person. Signer will receive sign request in his legale account |
no_certification | legale | Sign document using other sign method such as Remote or Remote SMS, in this case, signer can choose his sign method except certification. Signer will receive sign request in his legale account |
local_certificate | me | Sign document using local certificate, in this case, signer can be you or other legale person. Signer will receive sign request in his legale account. Signer should have his local certificate. This method is working on only Windows 10 for now. |
approve | approve | This is not digital sign. This method will send document to approver to approve current flow by himself. Approver is not legale user in this case. |
approve_legale | approve | This is not digital sign. This method will send document to approver to approve current flow by himself. Approver should be legale user in this case. |
approve_api | approve | This is not digital sign. You will receive a url from API response in this method, after that, you can approve that document by sending a new POST request to that url. |
tablet_sign | tablet | This is sign method to document to sign in mobile device. |
signing_portal | signing_portal | This is sign method to document to sign in signing portal. After start sign process, you can search and sign the documents from here. |
- Sign status callback request body
{
"GUID": "3470cf1d-dddd-4b59-a22f-445aaef913d2",
"priority": 19288490,
"sign_status": 2,
"signed_at": "2021-10-19T16:05:44.158662Z"
}
Value | Description |
---|---|
GUID | Document GUID |
priority | Sign priority |
sign_status | 2 : Signed, 3 : Rejected |
signed_at | Datetime of sign event in UTC |
Response
Success
- Status code:
200
- Body:
{
"data": [
"https://app.legale.io/api/remote/3470cf1d-dddd-4b59-a22f-445aaef913d2/0",
null,
//...
],
"code": null,
"message": ""
}
Error
- Status code:
400
- Body:
{
"code": "INVALID_DOCUMENT_STATUS",
"message": "Document is already in sign flow",
}
Error code | Type | Description |
---|---|---|
INVALID_DOCUMENT_STATUS | str | Document is already in another status, you can start sign flow with only document of sign_status 0. |