Skip to main content

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",
},
]
}
ValueTypeIs requiredDescription
flow_typestrNoAvailable 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.
expirationintNoThis parameter is to determine the expiration date. It should be number in days.
share_signed_documentboolNoThis 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
ValueTypeIs requiredDescription
sign_flowstrYesSign flow type
sign_methodstrYesSign method you wanna to use to sign document
emailstrYesSigner email
phonestrNoSigner phone to use receive OTP. This parameter is needed when you set sign_method as sms
firstnamestrNoSigner first name
lastname1strNoSigner first last name
lastname2strNoSigner second last name
device_idstrNoDevice 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_validationboolYesTo require the video validation of signer in Remote and Remote SMS method
selfie_validationboolYesTo require the selfie validation of signer in Remote and Remote SMS
id_validationboolYesTo require the Identity Documentation validation of signer in Remote and Remote SMS
is_fingerprintboolNoTo require fingerprint when you sign document on mobile device. This parameter is needed when you set sign_method as tablet_sign
is_NIDboolNoTo 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, y2floatNoSignature 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
pagenointNoPage number of document to insert the signature image in. The first page of document is 1.
anchorstrNoThe 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 boolNoIf set true, system will not send an email to remote signer or approver, you can get sign urls from response.
sign_status_callback_url strNoSign 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 valueAvailable sign methodsDescription
mecertification, local_certificate, sms, no_smsSign by myself, this means document will be signed by you. In this flow, you are the signer of document
othersms, no_smsSign by other person, this means document will be signed by other person, not by legale user.
legalecertification, no_certificationSign by legale user, this means document will be signed by other legale user.
approveapprove, approve_legale, approve_apiThis flow is to approve document by some persons, not adding digital signature into document, just approve current document sign flow by person.
tablettablet_signThis flow is to send document to tablet, on the tablet, you can add fingerprint into the document.
signing_portalsigning_portalThis flow is to send document to sign in signing portal.
  • sign_method
Available valueAvailable sign flowsDescription
smsme, otherSign 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_smsme, otherSign document using Remote, in this case, signer will receive the sign request through his email. No need to pass the phone number
certificationme, legaleSign 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_certificationlegaleSign 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_certificatemeSign 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 approveThis 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 approveThis 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 approveThis 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 tabletThis is sign method to document to sign in mobile device.
signing_portal signing_portalThis 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"
}
ValueDescription
GUIDDocument GUID
prioritySign priority
sign_status2: Signed, 3: Rejected
signed_atDatetime 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 codeTypeDescription
INVALID_DOCUMENT_STATUSstrDocument is already in another status, you can start sign flow with only document of sign_status 0.