Create document via Upload

POST https://api.zapsign.com.br/api/v1/docs/

This endpoint allows you to create a document for signature from a PDF. You must send the data in JSON, as well as receive it in the same format.

Headers

Name	Type	Description
Authorization*	string	apiToken ahead of the "Bearer" text. Ex: Bearer c7f35c84-7893-4087-b4fb-d1f06c23

Name

Type

Description

Authorization*

string

apiToken ahead of the "Bearer" text.

Ex: Bearer c7f35c84-7893-4087-b4fb-d1f06c23

Request Body

Name	Type	Description
name	string	Title of the document. String of up to 255 characters
url_pdf	string	Define the PDF to be signed from a public URL with the file. For now, we only accept one file in PDF format, up to 10Mb.
base64_pdf	string	Alternative to url_pdf: Set the PDF to be signed, starting from a base64. You must convert the file to a base64 string and send it to us in this parameter (more details below).
signers[name]	Array<Signer>	The 'signers' field represents the people who will sign the document. You can find how to configure each signer bellow. It's an array of Signer objects.
url_docx	string	Alternative to url_pdf: Set the DOCX to be signed, starting from a public URL with the file.
base64_docx	string	Alternative to url_docx: Set the DOCX to be signed, starting from a base64. You must convert the file to a base64 string and send it to us in this parameter (more details below).
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
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.
reminder_every_n_days	integer	Represents the interval of days between reminders that will be sent to signers, as long as they don`t sign. There will be 3 tries at most. Observation: this field must only be filled if send_automatic_whatsapp or send_automatic_email are true. Example: if setted to 8 it will be sent one email every 7 days, until it's signed, for at most 21 days.
allow_refuse_signature	boolean	If true, signers have the option to refuse to sign. Default: false.
disable_signers_get_original_file	boolean	If true, signers do not have the option to download the original document. Default: false.

Name

Type

Description

name

string

Title of the document. String of up to 255 characters

url_pdf

string

Define the PDF to be signed from a public URL with the file. For now, we only accept one file in PDF format, up to 10Mb.

base64_pdf

string

Alternative to url_pdf: Set the PDF to be signed, starting from a base64. You must convert the file to a base64 string and send it to us in this parameter (more details below).

signers[name]

Array<Signer>

The 'signers' field represents the people who will sign the document. You can find how to configure each signer bellow.

It's an array of Signer objects.

url_docx

string

Alternative to url_pdf: Set the DOCX to be signed, starting from a public URL with the file.

base64_docx

string

Alternative to url_docx: Set the DOCX to be signed, starting from a base64. You must convert the file to a base64 string and send it to us in this parameter (more details below).

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

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.

reminder_every_n_days

integer

Represents the interval of days between reminders that will be sent to signers, as long as they don`t sign. There will be 3 tries at most. Observation: this field must only be filled if send_automatic_whatsapp or send_automatic_email are true. Example: if setted to 8 it will be sent one email every 7 days, until it's signed, for at most 21 days.

allow_refuse_signature

boolean

If true, signers have the option to refuse to sign.

Default: false.

disable_signers_get_original_file

boolean

If true, signers do not have the option to download the original document.

Default: false.

{
    "open_id": 5,
    "token": "eb9c367a-e62f-4992-8360-b0219deaeecc",
    "status": "pending",
    "name": "Jhon Doe Documents",
    "original_file": "https://zapsign.s3.amazonaws.com/pdf/62c2b027-d8fc-4392-xas75-f3c46c3cfc7a/d33336-4182-8c8b-ded5287e4c0f.pdf",
    "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
        }
    ]
}

Signers configuration

Document - JSON root:

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", "assinaturaTela-tokenSms", "tokenWhatsapp" and "assinaturaTela-tokenWhatsapp". They correspond to the same methods available in the web interface. Note: each automatic sending via WhatsApp (tokenWhatsapp) costs 0,1 USD and each token sending via SMS (tokenSms) costs 1 credit. Buy credits in Configuration > Plan.
- 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.
- send_automatic_whatsapp (boolean): If true, ZapSign will send a whatsapp message to the signer with the link to sign the document. Note: For this to work, it is mandatory that the signer's phone number is defined. each automatic sending via WhatsApp (tokenWhatsapp) costs 0,1 USD. Buy credits in Configuration > Plan.
- send_automatic_whatsapp_signed_file (boolean): If true, ZapSign will send a whatsapp message to the signer with the link to the signed document. Note: For this to work, it is mandatory that the signer's phone number is defined. each automatic sending via WhatsApp (tokenWhatsapp) costs 0,1 USD. Buy credits in Configuration > Plan.
- 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 1, then this signer will be the first to sign. If the field is set to 2, 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
- blank_email (boolean): You may not request the signer's email. Default: false
- hide_email (boolean): You can hide signer email in signatures report. Default: false
- lock_phone (boolean): You can lock changes to the signer's phone. Default: false
- blank_phone (boolean): You may not request the signer's phone number. Default: false
- hide_phone (boolean): You can hide the signer's phone in the signatures report. 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): Advanced biometric methods.

Selfie_validation_type	Description	Countries	Price per validation
liveness-document-match	Facial recognition that requires the signer to upload a photo of their identity document and record their face. It validates that the person is the same as in the document and that the person is present at the time of sign	CO, BR, MX, CL, PE	25 credits = $0.5 USD
identity-verification	Document validation and facial biometrics. It validates that the person is present at the time of signing, that the document is real, that the person is the same as in the document, and that the document is registered in government databases	CO, MX, CL, PE	55 credits = $1.1 USD

Selfie_validation_type

Description

Countries

Price per validation

liveness-document-match

Facial recognition that requires the signer to upload a photo of their identity document and record their face. It validates that the person is the same as in the document and that the person is present at the time of sign

CO, BR, MX, CL, PE

25 credits = $0.5 USD

identity-verification

Document validation and facial biometrics. It validates that the person is present at the time of signing, that the document is real, that the person is the same as in the document, and that the document is registered in government databases

CO, MX, CL, PE

55 credits = $1.1 USD

For more information about the validation, click here (Authentication Method: Identity Verification)

Add credits to your account in Settings > Plan > Credits and clicking the ‘Contact Support’

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: "https://www.seusite.com.br/agracimento". 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: ""

Request

Create document via PDF

Create document via DOCX

Delphi request example

var
  json : string;
  ArraySigner : TJSONArray;
  ObjDoc, ObjSigner : TJSONObject;
begin
   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', 'joaosilva@gmail.com.br');
   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);

   ArraySigner.AddElement(ObjSigner);

   ObjDoc.AddPair('signers', ArraySigner);
   json := ObjDoc.ToString;

   ObjDoc.DisposeOf;

   RESTClient.BaseURL := 'https://api.zapsign.com.br/api/v1/docs/?api_token=...seu token..';
   Request_remete.ClearBody;
   Request_remete.Body.Add(json,ContentTypeFromString('application/json'));
   Request_remete.Execute;
end;

Response

After a successful request, you should receive a response like this:

Caution: the original_file and signed_file links are temporary and expires in 60 minutes. In case your system needs to save those links it is recommended that you save them in your own CDN or that you call the Detail document endpoint every time your user needs a valid URL that will expires in more 60 minutes.

{
    "open_id": 5,
    "token": "eb9c367a-e62f-4992-8360-b0219deaeecc",
    "status": "pending",
    "name": "John's contract",
    "original_file": "https://zapsign.s3.amazonaws.com/pdf/62xxxxx-d8fc-4392-8575-f3c46c3cfc7a/df6bac91-2766-4182-8c8b-ded5287e4c0f.pdf",
    "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",
            "sign_url": "https://app.zapsign.co/verificar/921c115d-4a6e-445d-bdca-03fadedbbc0b",
            "status": "new",
            "name": "John Doe",
            "email": "",
            "phone_country": "",
            "phone_number": "",
            "times_viewed": 0,
            "last_view_at": null,
            "signed_at": null,
            "resend_attempts": null
        },
        {
            "token": "07fb0a0a-4b7d-49a5-bd7b-4958265c4e46",
            "sign_url": "https://app.zapsign.co/verificar/07fb0a0a-4b7d-49a5-bd7b-4958265c4e46",
            "status": "new",
            "name": "Grumpy Jones",
            "email": "",
            "phone_country": "",
            "phone_number": "",
            "times_viewed": 0,
            "last_view_at": null,
            "signed_at": null,
            "resend_attempts": 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:

https://app.zapsign.co/verificar/{{signer_token}}

Thus, in the example above, where we have two signers, you must send two signature links, each signer with their respective token:

- John Doe: https://app.zapsign.co/sign/921c115d-4a6e-445d-bdca-03fadedbbc0b

- Grumpy Jones: https://app.zapsign.co/sign/07fb0a0a-4b7d-49a5-bd7b-4958265c4e46

And now just wait for the signers to sign!

About the base64

Base64 its a simply way to convert files to text. You can check a more detailed definition here https://en.wikipedia.org/wiki/Base64. Therefore, convert a file to base64 and send it as a text on the request`s body is easier then dealing with the multipart/form-data, for example.

To test the API you can manually convert your PDF into a base64 through a lot of websites, such as this one: https://base64.guru/converter/encode/pdf

When the API is alredy integrated to your system, look for the correspondent function in your software language to convert files to base64.

Watch out: you must send the base64_pdf parameter only with the base64 file conversion. Dont send the data:application/pdf;base64, on your parameter.

Dont want to work with base64? Upload your PDF in a public URL and use the url_pdf parameter.

PreviousPlan Information NextCreate document via Template

Last updated 1 month ago