Web service parameters
This operation allows to submit from EVICERTIA an EviSign contract with the following data:
- LookupKey[optional]: Identifier allocated by the user, it can be used later to locate an evidence through the query web service (EviSignQuery).
- Subject: Subject of the contract to be sent.
- Document: Document or contract to be signed by the parties (in PDF format).
- SigningParties: List of signers of the document, with the following data for each signer:
- Name: Full name of the person who must sign the document/contract.
- Address: E-mail address or telephone number of the signer, to which the signature request will be sent.
- SigningOrder: Order in which the signers will have the opportunity to sign the document and attachment(s) where appropriate. If not specified, it will be sent to all of them at the same time. It is a positive integer, and the same value can be specified for more than one signer. This allows a particular group of signers to sign at the same time, even before or after other signers sign.
- SigningMethod: Type of signature to request. [More information on section "Examples and further information about parameters"]:
- Challenge: Challenge question/answer. The operation will be carried out if the question selected as challenge by the issuer to be answered correctly.
- EmailPin: Security code PIN sent to e-mail. The operation will be carried out after identifying the user that accesses or signs, requesting a random PIN sent to his e-mail address.
- Handwriting: Digitalized signature. Handwritten digitalized signature or dynamic biometrics signature, depending on the capture device.
- MobilePin: Security code PIN sent to mobile phone. The operation will be carried out after identifying the user that accesses or signs, requesting a random PIN sent to his mobile phone.
- WebClick: Click in web through safe link or locator. The operation will be carried out if the reference or locator of the message is known.
- Other values that should only be reported if the corresponding method has been selected are as follows:
- PhoneNumber: Mobile phone number to send the PIN to when the signing method is MobilePin.
- AllowVoicePinFallback: It indicates whether the signer can choose to be informed of the signature PIN by voice call, in case PIN forwarding is requested. Only applicable when the signature method is MobilePin.
- WhatsAppPinPolicy: Indicates the default value for the PIN sending policy by WhatsApp. It only applies when the signature method is MobilePin.
- Disabled: The WhatsApp channel is not enabled to send the PIN. Corresponds to the Normal delivery policy (by SMS).
- Optional: The WhatsApp channel is enabled to send the PIN as an alternative to SMS.
- Fallback: The WhatsApp channel is enabled to send the PIN only on retry.
- SignDelivery: Obsolete. Since August 2018 this parameter is obsolete and is only maintained for backward compatibility reasons. You must use the SignStep parameter that is explained on this page.
- EmailAddress: Email account to send the PIN to when the chosen method is EmailPin.
- SignatureChallenge: Question asked when the signature method is Challenge.
- SignatureChallengeResponse: Answer to the previous question.
- AddressType: Via by which you want to notify the signer. It can be through a phone number "PhoneNumber" or an email account "Email".
*Note: The PIN code has a life time of 60 minutes, after this time it will be necessary to request another PIN code. The number of 9 attempts to correctly enter the PIN code sent is also established.
- SignerGeoLocationPolicy [Optional]: This setting allows the sender to request the browser location data from the signer during the signing process.
- Required: The collection of coordinates is enabled and also mandatory for the signature.
- Enabled: Collection of coordinates enabled but not mandatory for signature.
- Disabled: Coordinates collection for signature disabled.
- LegalName: Legal name, tax id, identity document and/or full name of the individual recipient of the message (the more identifying data the better).
- DisableSignRequests: It disables sending a notification or any signature request reminder/forwarding to the notification address. The signature will be carried out using a tablet or through representative signature. It can only contain two values “true” or "false". If "true" the signature request is not sent. Incompatible with AttachToSignatureRequest/SignatureRequestInfoText if all signers set it to “true”. By default is "false".
- DisableFinalNotification: It disables the sending of the final notification to the signer once signed/rejected. It can only contain two values "true" or “false”. If "true" the final notification is not sent. This option is incompatible with AttachToFinalNotification o FinalNotificationInfoText if all signers set it to “true”. By default is "false".
- DisableStateNotifications: It disables the sending of state change notifications to the signer (for example, expire or cancelled). It can only contain two values "true" or "false". If "true" state change notifications are not sent. By default is "false".
- RequiresCaptcha: Enable turing test (captcha) in the signature. It can only contain two values "true" or "false". If "true" the captcha is disabled.
- SignatureAppearances: Information about the geometric position in which the signature must be entered in the contract. [More information on section "Examples and further information about parameters"]:
- This position is indicated by including the position in JSON format.
- SignatureQuestions: List of questions the signer must answer during the signature process. There can be several questions, and they are all included in the node SignatureQuestion. [More information on section "Examples and further information about parameters"]:
- NOTE: Contact support@evicertia.com, before using this node.
- NOTE: It is highly important to respect "case sensitive" of parameter TypeName.
- Key: Question identifier, which will serve the transmitting system to find the answer given by the user. It is recommended to include unique words such as NIF, Account, email.
- Label: Text to be shown to the user as a question to enter.
- TypeName: Identifier of the type of question, which will allow the validation of the data entered by the signer. It is important to respect "case sensitive" of the names shown below:
- SpanishDocumentId: Identity document with validation of NIF, NIE and company’s NIF.
- DocumentId: Identity document without validation.
- BankAccount: Bank account (letters and numbers without restrictions).
- BankAccountES: Old Spanish bank account or CCC (legacy).
- BankAccountIBAN: -> European bank account where the account is not validated, only the IBAN control digit.
- BankAccountIBANES: -> Bank account with Spanish IBAN (both IBAN control digit of bank account are validated).
- EmailAddress: Email with validation of being well formed, but it does not validate if it is a valid address or the signer's address.
- IntlVatId: Tax identifier.
- SwiftCode: SWIFT code.
- SpanishVatId: Spanish tax identifier.
- PhoneNumber: Telephone number in international format (por example, +34914237080).
- Password: Password.
- Text: Text: letters, numbers and/or punctuation marks with the value of the requested data.
- MultiLineText: Multiline text: several lines with letters, numbers and/or punctuation marks with the value of the requested data.
- Number: Integer with sign.
- Decimal: Number with decimals and/or sign.
- Date: Date in format dd-mm-yyyy.
- CheckBox: Mark or unmark the checkbox.
- SelectList: Choose one option from the list.
- Image: Upload an image or photo.
- File: Attach file.
- DynamicSignature: Visual representation of the handwritten signature along with biometric information.
- DefaultValue: Default value to be displayed.
- Required: It indicates if the signer must compulsorily answer the question.
- Language: Represents the language in which you want to see some data of the notifications and that are provided by the operating system or the browser (culture). Values that can be indicated are type: es (for Spanish), en (for English), ca (for Catalan), pt (for Portuguese) and fr (for French).
- In case of indicating a Language that does not exist, a CultureNotFoundException is displayed.
- Role: The signer’s role. He can be:
- Signer: Signer.
- Reviewer: Reviewer. He/she can accept or reject the EviSign, but he/she does not appear as the signer.
- SignStep: Time when signature process is carried out. More information clicking here
- FinalNotificationAddress: It represents the email address to which the final notification will be sent.
- DeliverySubDomain: Registered Delivery Channel identifier to upload the signature portal from an iframe.
- DeliveryCustomUrl: Redirect URL for the signer to access the appropriate Delivery Channel. Optional, it can only be indicated if DeliverySubDomain is reported.
- DeliveryWebView: Registered Delivery Channel identifier to upload the signature portal from a mobile app.
- DelegatedSignature: Indicates if delegated signature is activated
- WhatsAppPinPolicy: Indicates the default value for the PIN sending policy by WhatsApp. It only applies when the signature method is MobilePin.
- Disabled: The WhatsApp channel is not enabled to send the PIN. Corresponds to the Normal delivery policy (by SMS).
- Optional: The WhatsApp channel is enabled to send the PIN as an alternative to SMS.
- Fallback: The WhatsApp channel is enabled to send the PIN only on retry.
- SignatureRequestTemplate: Contains the identifier of the template to be used in the signature request communication.
- SignatureRequestTemplateValues: It contains an array of value keys, where the variables defined in the template content and the value it receives in the emission are reported.
- SignatureReminderTemplate: Contains the identifier of the template to be used in the reminder communication.
- SignatureReminderTemplateValues: It contains an array of value keys, where the variables defined in the template content and the value it receives in the emission are reported.
- FinalNotificacionTemplate: Contains the identifier of the template to be used in the final notification communication.
- FinalNotificacionTemplateValues: It contains an array of value keys, where the variables defined in the template content and the value it receives in the emission are reported.
- ProgressNotificationTemplate: Contains the identifier of the template to be used in the progress communication.
- ProgressNotificationTemplateValues: It contains an array of value keys, where the variables defined in the template content and the value it receives in the emission are reported.
- InterestedParties: List of interested parties of the document, with the following data for each interested party:
- Name: Full name of the person receiving the information.
- LegalName: Legal name, tax id, identity document and/or full name of the individual recipient of the message (the more identifying data the better).
- Address: E-mail address of the interested party to whom the notification will be sent once the document has been signed.
- Options: Sending/processing options of the message:
- The following is an example of a SummaryAffidavit node with a Masking node.
"SummaryAffidavit" :
{
"IncludeDocument":"True",
"IncludeEvents" : "False",
"IncludeAttachments" : "False",
"IncludedCommitments" : "Signers",
"Masking" : ["client@testing.com","$SigningParties.Email"]
}
- SecurityTags: Security labels, and they serve to control access to an EviSign. Only users with the same tag will be able to access the same document.
- It is important to note that tags must be less than 16 characters, and there can only be one tag per EviSign.
- In the case of Rest/JSON it must be reported as indicated in the specifications below.
- PushNotificationUrl: URL of contract’s issuer to which EVICERTIA will do a POST when an event related to the contract occurs, sending a JSON with information about the event Therefore, the issuer can develop a controller that allows to capture these requests and proceed to update the status of the contracts in its own information systems.
- PushNotificationFilter: List of events you would like to be notified of in PushNotificationUrl. Possible values are:
- Processed: The contract has been admitted in the system and is ready to be sent.
- Sent: The signature notification has been sent to the signer.
- Delivered: Confirmation of delivery of signature notification to the signer has been received.
- Signed: The signer has signed the contract.
- Rejected: The signer has rejected the contract.
- FullySigned: All the signers have signed the contract.
- FullySent: The signature request has been sent to all the signers.
- FullyDelivered: The signature request has been delivered to all the signers.
- Closed: The contract is closed, no further events are expected.
- AffidavitPublished: A new Affidavit has been generated, it was requested on demand by the issuer and will contain the information collected so far.
- PushNotificationExtraData: Text field in which the issuer of the contract may indicate additional data. These data will be sent later in each push notification that is made.
- InterestedPartiesNotifications: List of events you would like to be notified to interested parties. Possible values are
- Attachments: List [optional] with message attachments.
- DisplayName: Name of the attachment.
- FileName: Name of the file.
- MimeType[optional]: Information on mime type of attachment.
- ContentId[optional]: Mime identifier of the attachment.
- ContentDescription[optional]: Mime description of the attachment.
- Data: Content (bytes) of the file to be attached.
- Attributes[optional]: Attributes that we want to indicate about the attachment:
POST https://app.ecertia.com/api/EviSign/Submit HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==
Host: app.ecertia.com {
"LookupKey" : "Evi",
"Subject" : "Enviando eViSign via WS",
"Document" : "[ATTENTION: attachment BASE64 in PDF format would appear here]",
"SigningParties":
{
"Name" : "PruebasEvi en Hotmail",
"Address" : "pruebas_evi@hotmail.com",
"SigningMethod" : "EmailPin"
},
"Options" : {}
}
Attachments:[optional] List of message attachments:
Note: for a higher compression BASE64 of PDF file has been replaced by the tag "[ATTENTION: BASE64 for the PDF file would appear here]".
In case of successful sending, the identifier allocated to the evidence (uniqueId) that can be used later to consult its state is returned
Example of answer in JSON
{
"uniqueId":"ca6c20b5-832c-4a30-bda8-a16300a5d248"
}
Idempotence Activation
There is the option to activate the idempotency capability to avoid sending the same EviSign more than once in case of repeated submitting. For that, a request with the name "X-Evi-IdempotencyToken", must be added to the request headers, adding as a value some random text (the use of a GUID is recommended).
More information is given below and examples of the parameters are given, so that they are understood more easily. This section is organized in alphabetical order.
AdditionalCommitments
The behaviour of that field is as follows:
BY DEFAULT, it displays this text:
By marking ACCEPT and then pressing the SIGN button, you are formally declaring that you ACCEPT the document and contents that are shown herein.
But if the parameter is reported this way:
{"AdditionalCommitments":["List 1","List 2","List 3"]}
It is displayed as follows:
By marking ACCEPT and then pressing the SIGN button, you are formally declaring that you ACCEPT the document and contents that are shown herein, and in particular, you acknowledge that:
* List 1
* List 2
* List 3
Finally if the node is reported this way:
{"AdditionalCommitments":[]}
It is displayed as follows:
By marking ACCEPT and then pressing the SIGN button, you are formally declaring that you ACCEPT the document and contents that are shown herein, and in particular, you acknowledge that:
*
CustomFields
As indicated above, CustomsFields are internal fields that allow data that later will be included in the searches to be included, and they also add logic from EVICERTIA’s client business when submitting contracts.
Even so, when issuing CustomFields, you can add as many nodes CustomField as you want, bearing in mind the following limits:
- If these are issued EviSignSubmit.CustomFields.CustomField.IsLookupKey=true and in addition EviSignSubmit.LookupKey=My-internal-ID
- The following error returns:
{
"ErrorCode":"InvalidOperationException",
"Message":"Custom fields will overwrite LookupKey. Must empty LookupKey or avoid set IsLookupKey = true on custom fields"
}
To solve this error, the node must be reported EviSignSubmit.CustomFields.CustomField.IsLookupKey=false or, on the contrary, do not report the node EviSignSubmit.LookupKey
When node is set to "true" EviSignSubmit.CustomFields.CustomField.IsLookupKey, this information will be displayed in the node EviSignQuery.LookupKey.
Information appearing in EviSignSubmit.LookupKey node is the information included in the node EviSignSubmit.CustomFields.CustomField.Value
It should also be taken into account that since node EviSignSubmit.CustomFields.CustomField.Value can be repeated several times, so in node EviSignQuery.LookupKey it is separated by "::". Please find here below part of an answer from EviSignQuery:
{
{
"EvidenceId":"61d195aa-50c3-4e89-bd6a-a2f000abf656",
"LookupKey":"A0000000::7777A",
"Subject":"ES-Pers-Evide-AddiFields-IsLookupkey-true-NoLookupkey",
"Document":"",
"State":"Sent"
}
}
As shown in the example, two different EviSignSubmit. CustomFields.CustomField. Value were issued, one with value A0000000 and the other one 7777A.
FinalNotificationInfoText
Some images to see the difference between including or not including this value are shown below:
- Image of a notification where the FinalNotificationInfoText not customized
Signature request without text customization
- Image of a notification where FinalNotificationInfoText is customized.
Signature request with text customization
LandingPageInfoText
Some images to see the difference between including or not including this value are shown below:
- Image of a notification where parameter LandingPageInfoText is not customized
Contract signing page, with the text set by default
- Image of a notification where LandingPageInfoText is customized.
Contract signing page, with the text set by default
- Finally, if you have chosen to request the signature on delivery (SignDelivery = true), and the parameter LandingPageInfoText is also customized, you can see that the message is displayed at the beginning, even before displaying the content.
Personalized text on the start page of the signing process, where the contract is not yet accessible
SignatureAppearances
An example is shown below, where a signature is included on two different pages 1 and 3, the values start counting from the bottom left. Version in the example indicates if the signature is a GSD or a simple file.
{"[{""PageNumber"":1,""Top"":100,""Bottom"":80,""Left"":30,""Right"":230},{""PageNumber"":3,""Top"":110,""Bottom"":80,""Left"":30,""Right"":230}]",""Version"":1}
Where:
PageNumber | Page number on which the signature will be displayed |
|
Top | Represents the distance in points of the upper right corner of the signature box from the bottom edge of the signature box. | |
Bottom | Represents the distance in points in the upper left corner of the signature box from the bottom edge of the signature box. | |
Left | Represents the distance in dots from the bottom left corner of the signature box, from the left-hand side. | |
Right | Represents the distance in points from the top right corner of the signature box, from the left-hand side. | |
Version | null >> The signature area shall be set in the signed document affidavit. 0 >> The signature area shall be set in the signed document affidavit. 1 >> The signature area will be set in the original signed document, this is a GSD functionality. |
|
If you want, for example, to raise the signature up, you only need to increase both Top and Bottom values in the same amount.
SignatureQuestions
As indicated in the section above, it is very important to respect the case sensitive and only these values can be:
- SpanishDocumentId
- DocumentId
- SpanishBankAccount
- EmailAddress
It should also be taken into account that only the fields and have validation, that is, if a deposit account or a NIF (or CIF or NIE) is entered, they are validated to be valid. All fields appear later in the affidavits.
Here below there are a couple of examples of how the node of SignatureQuestions is completed
{
{
"Key":"NIF",
"Label":"Document Id",
"TypeName":"SpanishDocumentId",
"DefaultValue":"",
"Required":"true
}
}
{
{
"Key":"NIF",
"Label":"Document Id",
"TypeName":"EmailAddress",
"DefaultValue":"",
"Required":"true
}
{
"Key":"Email",
"Label":"Email of document’s signer",
"TypeName":"DocumentId",
"DefaultValue":"",
"Required":"true
}
}
SignatureRequestInfoText
Some images to see the difference between including or not including this value are shown below:
- Image of a notification where the parameter SignatureRequestInfoText is customized
- Image of a notification where SignatureRequestInfoText is customized
SignedRedirectUrl
As indicated above, this is a URL that appears on the web server of the issuer of the contract, and that may contain additional information about the signing process, or the following steps that the client is going to take with regard to the contract.
The format of the SignedRedirecUrl has to be a valid URL and must start with http or https.
As part of the EVICERTIA service, it shows the following information in the redirect URL:
- Uniqueid of the signed contract, which corresponds to the identifier of the contract issued.
- Information about the final state of signature:
- accepted=True, if the contract has been accepted.
- accepted=False, if the contract has been rejected.
An example of each of them is given below:
SigningMethod
When indicating a signature method, it is not necessary to fill in all the indicated parameters, since they are not mandatory, for example, if it is indicated that the type of signature of EmailPin, it is not necessary to fill in SignatureChallenge or SignatureChallengeResponse.
The following considerations must be taken into account:
- SigningMethod = Challenge, then you have to fill in SignatureChallenge and SignatureChallengeResponse.
- SigningMethod = EmailPin, in this case, if EmailAddres is filled in, the pin to email is sent to that account. If instead it is left blank, the signer can indicate an email to which the pin will be sent.
- SigningMethod = Handwriting, this method is only valid to sign in tablet or through the HTML5 canvas for web signature. Furthermore, the node SignatureAppearances can be filled out to indicate the signature’s position.
- SigningMethod = MobilePin, in this case, if PhoneNumber is filled in, the SMS pin is sent to that number. If instead it is left blank, the signer can indicate a phone number to which the SMS pin will be sent.
- In the case of Rest/JSon it should be reported as follows:
{{"SecurityTags":["STRING"]}}
PushNotificationFilter
This method allows to report changes in the state of an evidence, without the need to periodically check its status.
Every time an evidence changes its state, the user will be notified through a POST to the URL shown as a parameter of the request.
Please find here below the common information returned for any push notification for an EviSign:
- Identifier: Identifier of the event.
- Kind: Mnemonic of the notification received.
- Date: Date of event.
- EvidenceId: Identifier of evidence.
- EvidenceType: Type of evidence.
- EvidenceState: Status of evidence.
- Site: Name of user’s site.
- Owner: Name of site’s user.
- OwnerEmail: Email of site’s user.
- AdditionalData: Additional information in the form of a key-value.
In addition, depending on the type of event, specific properties will be added in AdditionalData:
- Signed / Rejected:
- SignerName: Signer’s name.
- SignerNotificationAddres: Signer’s address.
- SignerNotificationAddresType: Type of signer’s address.
- SignerRole: Signer’s role.
- Sent:
- Retry: It shows the number of attempts carried out.
- Sent / Delivered:
- SignerName: Signer’s name.
- SignerNotificationAddres: Signer’s address.
- SignerNotificationAddresType: Type of signer’s address.
- EventDescription: Description of the event.
- SignerRole: Signer’s role.
- TransmissionSuccess: It indicates if the transmission was successful.
- TransmissionDescription: Brief description of the notification.
- Closed:
- OutCome: Outcome of processing.
- CancelComments: If the EviSign is cancelled and a reason is given as to why, it will appear in this property.
In the case where additional data is indicated in the PushNotificationExtraData parameter, it will be added in a property called ExtraData inside AdditionalData
- In the case of REST/JSON it should be reported as follows:
"PushNotificationFilter":["STRING"]
- In the case of SOAP it should be reported as follows:
<typ:PushNotificationFilter>
<typ:EviSignSubmit.PushNotifications>Name of the event</typ:EviSignSubmit.PushNotifications>
</typ:PushNotificationFilter>
{
"Identifier": "3b61916c-c442-419f-8f71-a4cf00d33797",
"EvidenceId": "8be457b1e2a24570b4ada4cf00d335d2",
"EvidenceType": "eviSign",
"Kind": "Processed",
"Date": "2015-07-08T10:49:00.8907070Z",
"Site": "soapevi",
"Owner": "SOAP",
"OwnerEmail": "soapevi@gmail.com",
"AdditionalData": {
}
}
{
"Identifier": "3b61916c-c442-419f-8f71-a4cf00d33797",
"EvidenceId": "8be457b1e2a24570b4ada4cf00d335d2",
"EvidenceType": "eviSign",
"Kind": "Processed",
"Date": "2015-07-08T10:49:00.8907070Z",
"Site": "soapevi",
"Owner": "SOAP",
"OwnerEmail": "soapevi@gmail.com",
"AdditionalData": {
}
}
{
"Identifier": "dd9f60e5-c880-4c67-8aee-a87000e1b20e",
"EvidenceId": "00b17d3bfd564dedad32a87000d12f02",
"EvidenceType": "eviSign",
"Kind": "Sent",
"Date": "2018-01-22T13:41:42.8767119+01:00",
"Site": "pruebas",
"Owner": "Pruebas evicertia",
"OwnerEmail": "pruebas@evicertia.com",
"AdditionalData": {
"SignerName": "Pruebas Evicertia",
"SignerNotificationAddres": "pruebas-firmante@evicertia.com",
"SignerNotificationAddresType": "EmailAddress",
"EventDescription": "Sent",
"SignerRole": "Signer"
"TransmissionSuccess": true
"TransmissionDescription": "The signature request has been sent to pruebas-firmante@evicertia.com"
"Retry": 1,
"ExtraData": "{\"myId\": \"99cf386b-1590-4ddb-af68-607b3e7c1194\", \"myCreationDate\": \"2018-01-22T12:54:00.4367924+01:00\"}
}
}
ISO8601 Notation
The ISO8601 format allows us to create a string of characters that form a time period.
These character strings that define time periods must always be preceded by the letter "P", then the number with the frequency with a maximum of two digits "nn", and finally the daily "D" or weekly "W" frequency must be indicated.
The following examples are given with the above details:
- Frequency of sending every 7 days: P7D
- Frequency of sending every 12 days: P12D
- Frequency of sending every 2 weeks: P2W