Use this endpoint to create an operation. This endpoint has a lot of optional parameters available as we want to allow you to achieve a very high level of specilization to your use case, but you probably won't need them all and could be overwhelming at first. Remember to check the examples/ folder as we cover there a lot very common use cases that may fit exactly what you want.
Basically, you will have to send a pdf (encoded in base64 or specifying the id of a template that you have uploaded to the platform), some configuration options (optional) and a list of signatories
The files array
The files array is the main object where you declare the operation/s you want to create. Usually, your files array will only contain one entry as you just want to send one pdf to one ore more signers. If you send more than one file object, multiple operations will be created, you can chain those operations (see next table) so signers will have to sign the first one, then the next one and so on as a chain. That's what we call a "chained operation".
If you want to send multiple pdfs and allow yours signers to sign all in only one operation, please refer to "create envelope" endpoint, a different concept where users review all the documents and then sign all at once with just one signature
The file object
Inside the files array, you have to send at least one object with this parameters
| parameter | value details | summary |
|---|---|---|
| name (string) | required without "template_id" | The name of the file you want to show to your signers |
| base64file (string) | required without "template_id" | The content of the pdf file, encoded in base64. Tecalis Signature only admit pdf files to sign, check pdf-utils conversion/to-pdf method if you want to convert a file to pdf |
| template_id (string) | required without "base64file" | Use the pdf file of a template you have previously created at Tecalis Signature admin panel (you can extract this id from the url where you edit a template). You can also send "name" parameter if you want to set a different name |
| configure (object) | (optional) can be ommited | The place where you configure your operation, see the dedicated section to a full reference of available options |
| receivers (array of objects) | required | In this array you will declare who will sign this document, a document can have more than one signer. Check the dedicated section to a full reference |
The configure object
This object is optional, also, all parameters inside it are optional so you can omit it**.** It allows you to configure global options of the operation, but don't forget to take a look to the receivers parameter (next table) for some specific configurations applied per signer that are not possible to set in this object
| name | value details | summary |
|---|---|---|
| signature_type (string) | simple, handwritten, certificate, email_certificate, otp. Default: handwritten | The type of signature you want to use in the operation. simple (simple signature), handwritten (advanced signature), certificate (advanced signature with certificate), email_certificate (certified send), otp (otp signature) |
| workflow_type (string) | parallel,sequential,bulk. Default: parallel | Parallel workflow allows signers to sign in any given order. Sequential forces signers to sign in a given order, notifying next one when previous one has signed. Bulk means you want to send a individual copy of this document to each signer, so one operation will be generated for each signer |
| subject (string) | The subject of the email, if you want to customize it | |
| message (string) | A custom message for the email, it'll also appear in the signature web when the signer opens the operation | |
| hashtags (array of strings) | No need to add a # at the beginnig. Example: ["new_york", "companies"] | You can define hashtags for your document, so later you can filter in Tecalis Signature admin panel the documents |
| expiration (date/datetime) | min: now, max: +90 days from now. Format: (Y-m-d or Y-m-d H:m:s). Timezone: UTC+0 | By default, operations expire after 15 days if not signed by every signer. You can modify this by sending a custom date or date time (important: send it in UTC+0) |
| signature_color (string) | css color, black by default. Value Examples: "red", "#CECECE" | You can change the signature color signers will use in the sign panel. Any css color in text or hexadecimal color are allowed |
| allow_delegation (boolean) | default: false | Allows signers to delegate their signature in another person during the sign process |
| allow_validation (boolean) | default: false | Allows signers to ask another person to review the operation before they sign |
| allow_comments (boolean) | default: false | Allows signers to add comments to the sign operation, that must be reviewed from the Tecalis Signature Admin Panel |
| force_scroll (boolean) | default: false | Signers must pass all pages, or scroll down to the bottom, before been allowed to sign (sign button will be disabled |
| scheduled_send_datetime (datetime) | format: Y-m-d H:m:s. Min: now. Timezone: UTC+0 | If set, this operation won't be sent to the receivers until the specified datetime (important: send it in UTC+0). Have into account that a cron reviews each 5 minutes this scheduled operations, so a bit of delay may ocurr |
| attachments (array of objects) | "name": the name of the attachment. "base64content": the content of the file in base64 | Here you can add files that will be attached to the email that the signer receives to star signature |
| observers (array of objects) | "name": full name of the observer, "email": email of the observer | Observers are validators that must give they ok to the document before is sent to the signers |
| reminders_days (int) | min: 1 | An email will be sent each {reminder_days} days reminding pending signers that they have an operation to sign |
| signed_copies_to (array of objects) | "name": fullname of the person who will receive a signed copy, "email: email where to send a signed copy | After all signer has signed, a copy of the signed document will be sent via email to this emails (notice: signers already receive a copy by default, so use this param only for external people not involved in the signature operation) |
| notify_expiration_days_before (int) | min 1 | An email will be sent to the sender (your signature user email) {notify_expiration_days_before} days before the expiration date |
| webhook (url string) | Must be a valid url | After a signer sucessfuly signs the document, it will be redirected to the specified url in this param |
| post_callback_url (url string) | Must be a valid url | Set here a valid URI that will be called via POST every time the general status of a document changes (e.g: all signers has signed, one signer has declined to sign, observers have validated the document, the document has expired, etc). Signature will send you this json in the body to the given url, telling you the document and current status { "document_id": (string) "the id of the document", "status": (int 0,2,4,6) the status, "expired": (boolean) is document expired?, "post_callback_url_token": optional sec. token (see next param) } # Example { "document_id": "6578acas5678cd56", "status": 2, "expired": false } |
| post_callback_url_token (string) | When you set a callback with post_callback_url, you can also set a custom security token that will be sent back to you in the body as part of the callback | |
| metadata (object) | Max object size: 1000 characters | Metadata is a free form json object where you can add data for your internal use (maybe a id that correlates this operation with an element of your system). |
The receivers object
The receivers object represents the signers of the operation, allowing you to declare them and make an specific configuration for each one. At least one receiver is required.
| name | value details | summary |
|---|---|---|
| email (string) | required. Must be a valid email. | The email of the signer. If, for some reason, you don't have access to his email, you can send a faked one (like [email protected]), but we recommend to use a real one so signers can receive communications related to the sign proccess |
| formElements (array of objects) | optional, default [] | The form elements assigned to this signers, please refer to the section below for an in deep explanation |
| name (string) | optional | The name of the signer |
| surname (string) | optional | The surname of the signer |
| locale (string) | values (en, es, de, it, fr, pt, br), defaults to your user locale (the language you have set in your Tecalis Signature admin panel) | Set the language in wich the receiver will receive Tecalis Signature communications. Also sets the language of the Signature process (the web where signers sign) but take into account that the user browser language has preference over this config, so if you set locale to "de", but the user has his browser in portuguese, "pt" will be used instead |
| documentID | required if require_documentID is true | The document id of the signer (nif, cif, passport, etc) |
| require_documentID | ||
| phone | required if send_methods.phone is true. Allows characters -+ and spaces: regex:^[- +()0-9]{9,}$^ | The mobile phone of the signer. This field is required if you want to send the operation link by sms. By default, the spanish prefix (+34) is used to send the sms, if the mobile is not from Spain you have to specify the prefix (i.e: +2516666666) |
| send_methods (object) | { email (boolean, default true), sms (boolean, default false) } | Set the methods to send the operation link to the signers (email, sms, or none if you set both to false). By default, email is true. You can manually get each signer link using document/:id/signature_links method if you decide set email and sms to false |
| otp (boolean) | default false | Set this to true if you want to ask for a OTP verification before sign (send a verification code via sms to the user), if your signature_type is otp, this field is not needed |
| otp_allow_edit_phone (boolean) | deafault false | If you have set a phone to the signer, set this to true if you want to allow the signer to use a different mobile number. If set to false, the phone of the signer will be the only option to receive the otp code unless you haven't specified a phone |
| not_a_signer (boolean) | default false | Setting this to true, this signer becomes a "filler", a rol that is only allowed to fill fields, but will not sign the document. Keep in mind that you will need at least one signer in the receivers array. It's also recommended to set workflow to type sequential, so that the filler can fill the fields before the operation is closed (all signers have signed) |
| kyc (object) | mode (required, string, accepted values (none, auto, manual, files), with_selfie (required, boolean), additional_documents (required, object) | Add Identity verification with Tecalis Identity to the sign operation, if you set a documentID to this signer, KYC will need to be done with the same ID document (dni, nie, passport, etc). This object is described in its own section below this table, so please refer there for a in deep explanation |
| notifications (object) | {sign (boolean, default true), signed (boolean, default true), signed_copy (boolean, default true)} | This object allows you to better control communications between signer and Tecalis Signature via email/sms, allowing you to disable some communications you don't want to happen. "sign" is the email the signer receives informing that it has to sign a document, "signed" is the email confirming that it has succesfully signed the document, "signed_copy" is received when all signers has sign, with the signed document attached to the email |
| validate_fields (array of objects) | [{name (required, string}, value (required, string)}] | The signer will be prompted (before sign) to validate (agree) with the set of key values array set in this parameter. If it doesnt agree with the info showed, the operation will be automatically cancelled. Example: [{name:"IBAN", value: "ES12345789"}, {name:"Address", value:"Fake street 123"}] |
| address (string) | Address of the signer | |
| province (string) | Province of the signer | |
| zip (string) | Zip of the signer | |
| nationality (string) | Nationality of the signer | |
| country (string) | Country of the signer | |
| edit_signatures (booleans) | default: false | Allow users to add and remove signature boxes in your document. Only applies to handwritten signatures and regular sign operations (no envelopes) |
FormElements
Form elements are fillable elements with which signers can interact and later get stamped on the document when is signed, one of the most common case uses is add a sign box so the signer's signature get printed in the final pdf.
Those elements are pretty complex to generate and position via api, so the reccomended aproach is to generate a template or layout in the admin panel with the fields you want to set in the formElements array of your signer/s
Then, with template (or layout) get info method you can recover those formElements and use them with minor modifications in your receiver formElements array (mainly, change the "page" atributte where you want them to be shown, as they already have a correct position value that you configured in the admin panel). If you want to use one form element multiple times, we recommend that you regenerate their "uuid" attribute to some unique value to avoid weird baheaviors in the sign proccess.
With that said, you have to options to send formElements: send the json strucuture of the element, or a template_id/layout_id to refer to the template from which you want to import form elements. Use the later if you don't need to modify them, send them manually if you need to modify page, uuid or other attributes. You can combine both, or send multiple template_id, so your form elements can look like some of the following examples
"formElements": [
{
"template_id": "631f060a0c85c750720462c2"
}
]
"formElements": [
{
"uuid": "c674a18e-e833-457b-8cfd-e448f1a1add2",
"type": "signature",
"name": "signature",
"page": 1,
"x": 104,
"y": -185,
"w": 203,
"h": 149,
"oldW": 200,
"oldH": 100,
"label": "",
"dragCache": {
"x": 104,
"y": 185
},
"value": null,
"required": false,
"disabled": false,
"visible": true,
"percentages": {
"x": 0.08573784006595218,
"y": -0.1077744466615623,
"w": 0.16735366859027206,
"h": 0.08680212190579882
},
"pdfDisplayerDocumentWidth": 1213,
"pdfDisplayerDocumentHeight": 1716.5478991596638
},
{
"uuid": "dde72edc-6f4b-430d-a8fa-fee7515a6108",
"type": "textbox",
"name": "textbox",
"page": 1,
"x": 104,
"y": -341,
"w": 202,
"h": 39,
"oldW": 180,
"oldH": 38,
"label": "",
"dragCache": {
"x": 104,
"y": 341
},
"value": null,
"required": false,
"disabled": false,
"visible": true,
"percentages": {
"x": 0.08573784006595218,
"y": -0.19865452060320402,
"w": 0.1665292662819456,
"h": 0.022720018485410432
},
"pdfDisplayerDocumentWidth": 1213,
"pdfDisplayerDocumentHeight": 1716.5478991596638
}
]
"formElements": [
{
"template_id": "631f060a0c85c750720462c2"
},
{
"layout_id": "631f05d0e6830e72c16f23e2"
},
{
"uuid": "dde72edc-6f4b-430d-a8fa-fee7515a6108",
"type": "textbox",
"name": "textbox",
"page": 1,
"x": 104,
"y": -341,
"w": 202,
"h": 39,
"oldW": 180,
"oldH": 38,
"label": "",
"dragCache": {
"x": 104,
"y": 341
},
"value": null,
"required": false,
"disabled": false,
"visible": true,
"percentages": {
"x": 0.08573784006595218,
"y": -0.19865452060320402,
"w": 0.1665292662819456,
"h": 0.022720018485410432
},
"pdfDisplayerDocumentWidth": 1213,
"pdfDisplayerDocumentHeight": 1716.5478991596638
}
]
Requesting KYCs in receiver object
The kyc object of a receiver has the following structure, with three optional parameters
mode (string, values: "none", "auto", "manual", default "none"):
none: no kyc, if you dont want to add a kyc, just dont send the "kyc" object in the receiver object
auto: this will require user to show document ID to the camera and will be validated in the moment
manual: this will only require the user to take a picture of its document ID, but no validation of the image will be performed. Use this only if you trust the signer or don't care to much about having valid document pictures
files: only the files declared in additional_documents will be collected, no photo / ocr of documentId will be required
with_selfie (boolean, default false):
If true, after the user shows its ID document to the camera, a proof of life (in auto mode) or a simple picture of his face (in manual mode) will be requested. The proof of life consists in try to determine the signer is there (not a photo or some other cheats) and try to match it with the ID document picture. So, for maxium security / reliablity, set auto mode with_selfie = true.
additional_documents (array of objects):
If, after the verification proccess, you want to request additional documents to the user, you can set in this array the needed configs. Extensions can be used to set allowed extension types (string or array of allowed extensions without dots, i.e: ["png", "pdf"], default "all" [all extensions allowed]), capture_mode can be "photo" (take a photo), "upload" (manually upload a file) or "photo_upload" (both methods available), copies says how many photos or uploads is the receiver expected to do for each requested document
Example:
"kyc":{
"mode":"auto",
"with_selfie":true,
"additional_documents":[
{
"name":"Insurance first two pages",
"subtext":"Send first and second page of your insurance contract",
"required":true,
"copies":2,
"extensions":"all",
"capture_mode":"photo_upload",
"instructions":"Take photos or upload scanned images of the first and second page of your insurance contract"
}
]
},