ZapSign API
Create document via Upload
Create document via Upload

Optional fields

  • Document - JSON root:
    • lang (string): document language. Possible values: "pt-br" (Portuguese), "es" (Spanish), "en" (English). Default: "pt-br"
    • disable_signer_emails (boolean): To disable emails sent to signers, send this parameter to true. Default: false
    • signed_file_only_finished (boolean): To disable the "Download Original" and "Download Signed" buttons from the signer experience, enable this flag. Thus, you are the one who will be in charge of delivering the signed_file to the signer. Default: false
    • brand_logo (string): If you want to customize the logo of the signing experience for this specific document, submit the image URL (must be a publicly accessible link). Default: ""
    • brand_primary_color (string): If you want to customize the primary (button) color of the signing experience for this specific document, send it in rgb or hexadecimal. Ex: "#0011ee". Default: ""
    • brand_name (string): if you want to customize the sender name of emails sent to the signer, enter the brand name here. For example, if you entered "XPTO Advogados", the sender of the email will be "XPTO Advogados via ZapSign". Max-length: 100 characters. Default: ""
    • external_id (string): ID of the document in your application. Default: ""
    • folder_path (string): path of the folder inside ZapSign where the document will be placed. If the folders do not exist, they will be created automatically. Requirements: (1) folder_path can be up to 255 characters long, (2) each folder can be up to 50 characters long, (3) there is a limit of 5 folder levels. Ex.: "/api/" or "/folder1/folder2/folder3/". Default: "/" (no folder).
    • created_by (string): email of the user who will be defined as creator of the document, for internal organization purposes. If the email does not exist or is not your account user, this parameter will be ignored. Default: "" (document will have account owner as creator)
    • date_limit_to_sign (DateTime): Deadline for signing the document. (Accepted formats: YYYY-MM-DD, YYYY-MM-DDTH:m:s.ssssssZ)
    • signature_order_active (boolean): If true, the signer's signatures will be ordered sequentially. Default: false
    • observers (array<string>): represents document observers (limit 20), i.e. email addresses that will be notified upon completion of the signature flow. It's an array of strings.
  • Signers - for each signer:
    • auth_mode (string): You can choose the signer's authentication method. Possible values are: "assinaturaTela" (default) (signature on screen), "tokenEmail", "assinaturaTela-tokenEmail", "tokenSms" and "assinaturaTela-tokenSms". They correspond to the same methods available in the web interface.
    • email (string): You can set the signer's email.
    • send_automatic_email (boolean): If true, ZapSign will send an email to the signer with the link to sign the document. If false (default), you will be responsible for sharing the subscription link with the signatory, whether through your website, widget, WhatsApp, SMS, email, chat etc. Note: For this to work, it is mandatory that the signer's email address is defined.
    • order_group (integer): In case "signature_order_active" is active in the document, this field controls the signing order. Example: If the field is set to 0, then this signer will be the first to sign. If the field is set to 1, then this signer will be the second to sign and so on.
    • custom_message (string): (only relevant if send_automatic_email: true). The custom_message is the personalized message that you can insert in the email sent by ZapSign to the signer. Example: "Hello So-and-so, \n This is your employment contract. \n Hugs, Team XPTO". The \n symbol serves to "skip a line" in the email text. Default: ""
    • phone_country (string): You can set the phone (country code) of the signer. Default: "" (ie. US is "1")
    • phone_number (string): You can set the phone number of the signer. Example: "11998989222". Default: ""
    • lock_email (boolean): You can lock changes to the signer's email. Default: false
    • lock_phone (boolean): You can lock changes to the signer's phone. Default: false
    • lock_name (boolean): You can lock changes to the signer's name. Default: false
    • require_selfie_photo (boolean): You can ask the signer to take a selfie while signing. Default: false.
    • require_document_photo (boolean): You can ask the signer to take a photo of your personal document while signing. Default: false
    • selfie_validation_type (string): If you want to use facial recognition (liveness+document match validation) provided by Truora, please also define this field as "liveness-document-match". Default: "none". Note that this feature has an extra cost, please contact sales.
    • qualification (string): Qualification to appear in the signatures report. Ex: "Witness" value will result in "Signed as a witness". Default: ""
    • external_id (string): ID of the signer in your application. Default: ""
    • redirect_link (string): link to redirect after signer signs. For example: "". It will appear as a "CONTINUE" button below the "Download Original" and "Download Signed" buttons. Remember to insert http:// or https:// at the beginning of the link. Default: ""

Exemple Request

Parameters must be in JSON format in the request body:
"name":"Contrato de Admissão João",
"name":"João da Silva"
"name":"Fulano Siclano",
"email":"[email protected]",
"custom_message":"Olá Fulano, \n Este é o seu contrato de trabalho. \n Abraços, Equipe XPTO",


After a successful request, you should receive a response like this:
"open_id": 5,
"token": "eb9c367a-e62f-4992-8360-b0219deaeecc",
"status": "pending",
"name": "Contrato de Admissão João",
"original_file": "",
"signed_file": null,
"created_at": "2020-04-16T03:33:46.241747Z",
"last_update_at": "2020-04-16T03:33:46.241775Z",
"signers": [
"token": "921c115d-4a6e-445d-bdca-03fadedbbc0b",
"status": "new",
"name": "João da Silva",
"email": "",
"phone_country": "",
"phone_number": "",
"times_viewed": 0,
"last_view_at": null,
"signed_at": null
"token": "07fb0a0a-4b7d-49a5-bd7b-4958265c4e46",
"status": "new",
"name": "Fulano Siclano",
"email": "",
"phone_country": "",
"phone_number": "",
"times_viewed": 0,
"last_view_at": null,
"signed_at": null
What you should do with this response is send the signature link to the signers through your application.
The signature link consists of the route:{{signer_token}}
Thus, in the example above, where we have two signers, you must send two signature links, each signer with their respective token:
- João da Silva:
- Fulano Siclano:
And now just wait for the signers to sign!

Code examples


$url = "";
$ch = curl_init( $url );
$payload = array(
"name"=>"Contrato de Admissão João",
"name"=>"João da Silva"
"name"=>"Fulano Siclano",
"email"=>"[email protected]",
$json_payload = json_encode($payload);
curl_setopt( $ch, CURLOPT_POSTFIELDS, $json_payload );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
$result = curl_exec($ch);
// A depender da versão de php, curl e OpenSSL do seu servidor,
// você pode testar também outras opções do curl, como:
// curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, 0);
// curl_setopt ($ch, CURLOPT_SSL_VERIFYHOST, 0);
// curl_setopt ($ch, CURLOPT_FOLLOWLOCATION, TRUE);
// curl_setopt ($ch, CURLOPT_SSLVERSION, 6);
// curl_setopt ($ch, CURLOPT_USERAGENT, "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36");
// curl_setopt ($ch, CURLOPT_COOKIESESSION, TRUE);
// curl_setopt ($ch, CURLOPT_RETURNTRANSFER, 1);
// curl_setopt( $ch, CURLOPT_POSTFIELDS, $json_payload );
// curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
// curl_setopt ($ch, CURLOPT_HEADER, 1);
// curl_setopt ($ch, CURLOPT_POST, true);
// curl_setopt ($ch, CURLOPT_FRESH_CONNECT , 1);
// curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// Para testes/debug, descomentar:
// echo $result;
// echo curl_getinfo($ch);
// echo curl_errno($ch);
// echo curl_error($ch);


import requests
url = ""
payload = "{\"name\":\"Contrato de Admissão João\",\"signers\":[{\"name\":\"João da Silva\"},{ \"name\":\"Fulano Siclano\"}],\"base64_pdf\":\"JVBERi0xLjcNCiWhs8XXDQoxIDA...\"}"
headers = {
'Content-Type': 'application/json'
response = requests.request("POST", url, headers=headers, data = payload)


var request = require('request');
var options = {
'method': 'POST',
'url': '',
'headers': {
'Content-Type': 'application/json'
body: JSON.stringify({"name":"Contrato de Admissão João","signers":[{"name":"João da Silva"},{"name":"Fulano Siclano"}],"base64_pdf":"JVBERi0xLjcNCiWhs8XXDQoxIDA..."})
request(options, function (error, response) {
if (error) throw new Error(error);


json : string;
ArraySigner : TJSONArray;
ObjDoc, ObjSigner : TJSONObject;
ObjDoc := TJSONObject.Create;
ObjDoc.AddPair('name', 'Contrato de Locação');
ObjDoc.AddPair('base64_pdf', 'ASFASDFKÇLKÇGÇO#OP%$%#WERP#@&*OSADFJF...'); // Arquivo base64
ArraySigner := TJSONArray.Create;
ObjSigner := TJSONObject.Create;
ObjSigner.AddPair('name', 'João da Silva');
ObjSigner.AddPair('email', '[email protected]');
ObjSigner.AddPair('phone_country', '55');
ObjSigner.AddPair('phone_number', '11888121111');
// Opcional caso queira impedir alteração
ObjSigner.AddPair('lock_name', TJSONTrue.Create);
ObjSigner.AddPair('lock_email', TJSONTrue.Create);
ObjSigner.AddPair('lock_phone', TJSONTrue.Create);
ObjDoc.AddPair('signers', ArraySigner);
json := ObjDoc.ToString;
RESTClient.BaseURL := ' token..';