EviSignSubmit

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 notified of the signature PIN by voice call. It only applies 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".
- Legal Name: 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.
- AllowOverride: It indicates whether or not to change the signer. NOTE: this property is obsolete and it will disappear.
- 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, befre 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.
InterestedParties: List of interested parties of the document, with the following data for each interested party:
- Address: E-mail address of the interested party to whom the notification will be sent once the document has been signed.
Options: OSending/processing options of the message:
- CostCentre [optional]: In terms of invoicing, it allows to group sendings. to automate invoicing and to allocate expense.
- TimeToLive (minutes): Time (in minutes) that the message/contract will be available before proceeding to close the tracking of the message. In those cases in which the notification/contract is accessible via a link, once that period has elapsed and if it has never been accessed, this link is no longer available.
  - Number of minutes.
- SignatureRequestInfoText: Text appearing in the notification "Signature request". This field can be formatted using the markup wikiplex.
- LandingPageInfoText: Text appearing on the initial page of the EVICERTIA signature process website. This field can be formatted using the markup wikiplex.
- FinalNotificationInfoText: Text that appears in the notification that is sent indicating the final state of the contract (if it has been signed, rejected or expired). This field can be formatted using the markup wikiplex.
- SignedRedirectUrl: URL to which the contract is redirected once the signature process is completed:
  - This website is usually on the client's own server, and may contain more information about what type of information the signer can receive in the following steps.
  - It is important that this URL exists on the client's server because otherwise, and depending on the configuration of the client's servers, you will receive a 404 or page not found.
  - Furthermore, EVICERTIA provides additional information indicating whether the contract has been accepted or rejected as a parameter in the URL. See section "Examples and further information about parameters."
- RequireCaptcha: Obsolete. Since September 2014 this parameter is deprecated and is only maintained for backwards compatibility reasons. You must use the RequiresCaptcha parameter at SigningParties level explained on this page.
- EvidenceAccessControlMethod: Access control method to the custody. Values to be displayed are as follows:
  - AutoChallenge: Request of random known data, the operation will be carried out if a random question about a known data, such as the e-mail address of the recipient, is answered correctly.
  - Challenge: Challenge question/answer, the operation will be carried out if the question selected as challenge by the issuer to be answered correctly.
  - Session: Users of related sites (issuer/recipient).
  - Public: Anyone who knows the link will be able to access the content.
  - Other values that should only be reported if the corresponding method has been selected are as follows:
    - EvidenceAccessControlChallenge: If option Challenge has been selected as EvidenceAccessControlMethod this is where you specify the question.
    - EvidenceAccessControlChallengeResponse: If Challenge has been selected as EvidenceAccessControlMethod this is where you specify the answer to the question raised in EvidenceAccessControlChallenge.
- AttachToFinalNotification: It allows to modify the content of the final notification indicating that the contract has been signed, and the main document and attachments can be added to the notification:
  - EvidenceAttachments: It allows to send the attachments included as part of the notification or contract.
  - EvidenceContent: It allows to send the main document included as part of the notification or contract.
  - EvidenceContentAndAttachments: It allows to send the main document and the attachments included as part of the notification or contract.
  - Nothing [By default]: By default, notifications are sent without any type of attachment.
- AttachToSignatureRequest: It allows to modify the content of the signature request notification, and the main document and attachments can be added to the notification.
  - EvidenceAttachments: It allows to send the attachments included as part of the notification or contract.
  - EvidenceContent: It allows to send the main document included as part of the notification or contract.
  - EvidenceContentAndAttachments: It allows to send the main document and the attachments included as part of the notification or contract.
  - Nothing [By default]: By default, notifications are sent without any type of attachment.
- AdditionalCommitments: By default, the text "By marking ACCEPT and then pressing the SIGN button, you are formally declaring that you ACCEPT the contents and documents that are shown herein, and in particular, you acknowledge that:." Here you can add as a list a series of additional clauses that you want to be signed (LOPD (Organic Law for Data Protection) consent, particular conditions,...). These conditions are registered in the following strings:
  - string: Conditions to be shown as lists and that are indicated in the previous point.
  - More information on section "Examples and further information about parameters"
- CustomFields: It allows to include internal fields when submitting contracts that will be used later in the searches, and whose objective is to allow business validations to be included before submitting contracts. The information included in this node is displayed in LookupKey:
  - CustomField: within the node CustomFields, 1 a n CustomField can be included. Fields that may be completed are as follows:
    - Key: identifier or key of the CustomField. Compulsory.
    - Label: Label that you want to define. Compulsory.
    - Value: Value. Compulsory.
    - IsLookupLey: It can only contain two values "true" or "false". If "true" then the value will be included within the lookupkey and indexed to increase the speed of searching.
    - TypeName: : Type of field to be displayed
      - Text: It allows to include any type of text.
    - DefaultValue: It allows to include a default value within CustomField.
    - DefaultValueIsForced: If "true" then the value is required to be included.
    - Required: It can only contain two values "true" or "false". If "true" then the value is compulsory.
    - ValidationRegex: It allows to include regex expressions that will validate whether or not the entered value complies with these regular expressions. If it is not met, the validation message or validationmessages will be displayed.
    - ValidationMessage: Validation message when the value entered does not comply with the regular expression.
    - MaxLength: Number representing the maximum length that the additional field will have.
  - It is recommended to contact support before using these options.
  - More information on section "Examples and further information about parameters"
- OnlineRetentionPeriod [optional]: Time (in years) of online retention. Default value is 1 year. This parameter is important for invoicing purposes.
- NotaryRetentionPeriod [optional]: If enabled, a 5-year notarial retention will be applied; otherwise nothing will be applied. This parameter is important for invoicing purposes.
- NotaryProfile [optional]: Notary’s identifier who will carry out custody at the notary’s office It should appear if a NotaryRetentionPeriod greater than (0) years is selected.
- CommitmentOptions [optional]: Text appearing in the checks of the EVICERTIA page to reach an agreement. Possible values are as follows:
  - Accept, Text "Accept" appears in EviSign and check "Accept" appears on the agreement page.
  - Reject, Text "Reject" appears in EviSign and check "Reject" appears on the agreement page.
  - AcceptOrReject, text "Accept/Reject" appears in EviSign and checks "Accept" and "Reject"appear on the agreement page. This is the default value.
- CommitmentCommentsAllowed [optional]: It indicates whether or not to include comments in the rejection of the agreement:
  - True: Comments are allowed. This is the default value, but "CommitmentOptions" must be different from "Accept".
  - False: Comments are not allowed.
- CertificationLevel: It specifies the level of tracking and certification that will be applied to the message (EviMail, EviSms, EviNotice). Values to be displayed are as follows:
  - None: None – Only tracking of status, alerts and traceability.
  - Standard: Standard – Generation of an affidavit (receipt) when the tracking of status is over.
  - Advanced: Advanced – several affidavits (one for each event) and timestamp. This is the default value. This parameter is important for invoicing purposes.
- AffidavitProfile: It specifies what and how the affidavits will be generated during the process. This parameter is important for invoicing purposes. Values to be displayed are as follows:
  - None: None affidavit will be generated.
  - Basic: Generation of an affidavit (receipt) when the tracking of status is over. This is the default value in case of selecting Standard in CertificationLevel.
  - AdvancedContentOnSubmit: Several affidavits (one for each event) and timestamp. The content certification affidavit will show the body of the message and the attachments.
  - AdvancedContentOnClose: everal affidavits (one for each event) and timestamp. Generation of an affidavit (receipt) when the tracking of status is over. The affidavit receipt will show the body of the message and the attachments. This is the default value in case of selecting Advanced in CertificationLevel.
  - AdvancedContentOnSubmitAndOnClose: Several affidavits (one for each event) and timestamp. The content certification affidavit and the affidavit receipt will show the body of the message and the attachments. In addition, an affidavit will be generated after the tracking ends.
- AffidavitsOnDemandEnabled: It allows to activate the affidavit generation upon request capability. AffidavitProfile value needs to be AdvancedContentOnSubmit, AdvancedContentOnClose, or AdvancedContentOnSubmitAndOnClose.
- FinalRejectedNotificationInfoText: Text that appears in the notification that is sent indicating the final state of the contract (if it has been signed, rejected or expired).
- SignatureReminderInfoText: Text appearing in the notification "Signature request reminder". This field can be formatted using the markup wikiplex.
- ExpiredNotificationInfoText: Text appearing in the notification that is sent when the contract has expired.
- NumberOfReminders: Number of notifications that you want to configure as a reminder in the signature request. The notification service has the following limitations:
  - If it is specified or it is specified that it is equal to zero, the default notifications of EVICERTIA are set, which at this time it is a reminder when 50% of the time set for the expiration of the EviSign or TTL has elapsed.
  - Si the TTL is less than 7200 (60x24x5) reminders will not be sent. This value is set as the minimum default value from which reminders are sent.
  - If a very high number of reminders is indicated for a very short time to live (TTL) or when there is more than one a day, for example 10 notifications in two days, the following error is returned: The number of reminders is too big for the configured time to live.
  - For all other cases, you can configure the number of reminders you want as long as there is more than one day between reminders.
  - This parameter is incompatible with the parameter Reminders.
- Reminders: Set how often signature reminders will be made. This parameter is incompatible with NumberOfReminders.
  - *Initial: String, time interval in ISO8601 format specifying the number of days or weeks after which the first signature reminder will be issued (from the EviSign issue date).
  - Repeat: String, Time interval in ISO8601 format indicating the frequency with which the set configuration for signature reminders is repeated.
  - Days: Array, indicates the days of the week on which signature reminders will be sent. This field is configured as a list of the days of the week in English, separated by ",". Default: [ Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday ]
  - TimeRange: Array, indicates the time ranges selected for sending signature reminders. Allowed time ranges:
    - FROM08TO10: 08:00 - 10:00
    - FROM10TO12: 10:00 - 12:00
    - FROM12TO15: 12:00 - 15:00
    - FROM15TO19: 15:00 - 19:00
    - FROM19TO22: 19:00 - 22:00
    - Default: [FROM08TO10, FROM10TO12, FROM12TO15, FROM15TO19, FROM19TO22]
  - Max: Number, indicates the maximum number of signature reminders that can be sent during the lifetime of the signature process.
  - Stop: String, time interval in ISO8601 format representing the deadline for sending the last signature reminder.
  - TimeZone: String, name of the TimeZone (with the values of the TimeZones Etc/GMT) to be used for the calculation of the time when the reminders will be sent. Default: Etc/GMT0
- Language: It 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) and pt (for Portuguese) and fr (for French).
  - In case of indicating a Language that does not exist, a CultureNotFoundException is displayed.
- AffidavitLanguage: It represents the language in which you want to generate the affidavits. Values that can be indicated are type: es (for Spanish), en (for English), ca (for Catalan) and pt (for Portuguese).
  - In case of indicating a Language that does not exist, a CultureNotFoundException is displayed.
- SummaryAffidavit: Allows to generate an affidavit at the end of the process with the possibility to customise the content of the affidavit and hide some fields if desired.
  - IncludeDocument: Indicates if the document must be added in the affidavit.
  - IncludeEvents: Indicates if the events should be added in the Affidavit.
  - IncludeAttachments: Indicates if the attachments should be added in the affidavit.
  - IncludedCommitments : Indicates if signatures of signatories should be added in the affidavit.
    - None: Signatures are not added to the affidavit. This is the default value.
    - Signers: The signatures of the participants with signatory role are added ("Signer").
    - Reviewers: The signatures of participants with a reviewer role are added ("Reviewer").
    - All: The signatures of the participants with a reviewer and signatory role are added.
  - Masking:List of texts and/or known fields to be masked.
    - Texto: Content present in the affidavit to be masked that is not present in the document.
    - Campos conocidos:
      - $SigningParties.Email
      - $SigningParties.PhoneNumber
      - $SigningParties.Address
      - $SigningParties.FinalAddressNotification
  - The following is an example of a SummaryAffidavit node with a Masking node.

SummaryAffidavit

			"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.
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.

Issuer: Name to overwrite the issuer of the contract.
- 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:
  - Attribute: This property will contain as many Attribute nodes as needed and within them different key-values are allocated:
    - Key: Name of the key.
    - Value: Value for the previous key.
  - Here below are the key-values that can be used in this node:
    - Key = RequireContentCommitment, Value = true, indicates that attachments must be signed, regardless of the contract itself.
    - Key = RequireContentCommitmentOrder, Value = Number, indicates the order number in which the attachment will be displayed:
      - After the Main Document: Positive value greater than '0'.
      - Before the Main Document: Negative value lower than '0'.
      - Notes:
        Values must be other than 0.
        For multiple attachments, the values must be different and will be are sorted from highest negative to highest positive.
  - Here below there is an example of a node attachment with a node attributes.
    [ { "UniqueId":"00000000-0000-0000-0000-000000000000", "CreationDate":"0001-01-01T00:00:00", "EvidenceUniqueId":"00000000-0000-0000-0000-000000000000", "DisplayName":"4kb.pdf", "Filename":"4kb.pdf", "Data":"[ATTENTION: attachment BASE64 in PDF format would appear here]", "Attributes": [ { "Key":"RequireContentCommitment", "Value":true }, { "Key":"RequireContentCommitmentOrder", "Value":1 } ] } ]

Example of request in JSON

 POST https://app.evicertia.com/api/EviSign/Submit HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==
Host: app.evicertia.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" : {}
}

Example of request in JSON

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).

Examples and further information about parameters

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.

{"[{""PageNumber"":1,""Top"":100,""Bottom"":80,""Left"":30,""Right"":230},{""PageNumber"":3,""Top"":110,""Bottom"":80,""Left"":30,""Right"":230}]"}

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

Only one question

{
	{
		"Key":"NIF",
		"Label":"Document Id",
		"TypeName":"SpanishDocumentId",
		"DefaultValue":"",
		"Required":"true
	}
}

Two questions

	{
		{
			"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

Signature request without text customization

Image of a notification where SignatureRequestInfoText is customized

Signature request with text customization

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 accepted.

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.

SecurityTags

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:

EventIdentifier: Identifier of the event.
EventType: Type of event.
EventDate: 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>

Example of push notification answer (PROCESSED)

	{
		"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": {
		}
	}

Example of push notification answer (PROCESSED)

	{
		"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": {
		}
	}

Example of a push notification answer (SENT)

	{
		"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 (AllowOverride)",
			"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

Page tree

EviSignSubmit

Web service parameters

Idempotence Activation

Examples and further information about parameters

AdditionalCommitments

CustomFields

FinalNotificationInfoText

LandingPageInfoText

SignatureAppearances

SignatureQuestions

SignatureRequestInfoText

SignedRedirectUrl

SigningMethod

SecurityTags

PushNotificationFilter

ISO8601 Notation