The EviSign API lets you submit documents for signature, track their progress, cancel or resend eligible requests, request on-demand affidavits and download evidence bundles. SignLink generates temporary URLs for parties to access an existing signing flow.
EviSign has entered Long-Term Support (LTS). It will continue to receive security patches and critical bug fixes, but no new features will be developed.
Use the interactive EviSign reference for all request and response fields, nested objects and enumeration values. This guide explains the workflow, conditional rules and examples. For signer experience, signature appearance settings and callback semantics, see the EviSign service guide.
| Environment | Issuer operations and Bundle | SignLink |
|---|---|---|
| Production | https://api.evicertia.com | https://app.evicertia.com |
| Pre-production / QA | https://api.ecertia.com | https://app.ecertia.com |
Append the complete path listed below to the appropriate host. SignLink uses /EviSign/SignLink on the application host, without a version prefix.
| Operation | Method and public path | Purpose |
|---|---|---|
| Submit | POST /v1/evisign/submit | Submit a document and parties. |
| Query | GET /v1/evisign/query | Read status and selected metadata. |
| Cancel | POST /v1/evisign/cancel | Request cancellation. |
| Resend | POST /v1/evisign/resend | Resend a party's signature request. |
| Affidavit Request | POST /v1/evisign/affidavitrequest | Request an affidavit asynchronously. |
| Bundle | GET /v2/evisign/{Id}/bundle | Download a ZIP of evidence files. |
| SignLink | POST /EviSign/SignLink | Generate a temporary signing URL. |
All seven operations require HTTP Basic authentication over HTTPS:
Authorization: Basic <base64(username:password)>API access and the EviSign service must be enabled for your site. Submit, Cancel and Resend also require the Sender role's operation permissions. The issuer API returns 403 Forbidden when the required permissions are missing. SignLink has separate error behavior: invalid or missing credentials return an empty 401 response; disabled API access or EviSign returns 500.
Cancel, Resend, on-demand affidavit requests and SignLink require the caller to own the EviSign. Bundle uses site-level access: the EviSign must belong to the authenticated site. Query is site-wide for users with the SiteUser role; other users see their own entries. Bundle remains site-wide for authorized callers regardless of that role.
See credential handling for storing credentials and protecting callback endpoints.
- Submit the main document, parties and options. Save the returned
uniqueIdand your ownLookupKey. - Track processing through Query and the callbacks selected in
Options.PushNotificationFilter. A successful Submit response means the request was accepted; document processing and signing continue asynchronously. - Deliver the signing experience through the platform's signature-request notification or generate a SignLink after the EviSign has been processed. Treat that returned URL as sensitive.
- Track party commitments and the overall outcome. A party's signature and the whole EviSign reaching its final outcome are distinct events.
- Retrieve available evidence through Bundle. For an additional on-demand affidavit, request it while the EviSign is eligible, then wait for publication before downloading it.
Use States and outcomes and the service lifecycle when interpreting progress. Optional files become available as the workflow generates them; requesting a bundle does not create missing evidence.
POST /v1/evisign/submitThe body contains the main document and the parties involved in the transaction. Subject must be nonblank and Document must contain nonempty Base64-encoded document bytes. At least one party is needed; a normal signing request supplies SigningParties with the intended signers.
| Field | Description |
|---|---|
Subject | Required. Subject of the signature request. |
Document | Required. Main document as Base64 bytes. Use a valid PDF for the signing workflow. |
SigningParties | Parties taking part in the signing or reviewing flow. See the next section and the full schema. |
InterestedParties | Observers notified about the lifecycle; each has an Address and optional progress-notification template settings. |
LookupKey | Your reference for later lookup and correlation. |
Options | Lifetime, certification, signing decisions, notifications, affidavits, retention and presentation settings. |
Attachments | Supporting files, each with Base64 Data, file metadata and optional Attributes. |
Issuer | Issuer display name shown to parties. |
From | Optional sender email; it must meet account and sender authorization rules. It is not an arbitrary display address. |
DisableSenderHeader | Controls whether the sender header is omitted. Defaults to false when omitted, overriding the site default. |
ReplyTo | Reply-to address, validated independently of the sender. |
The OpenAPI schemas include every nested party, option, attachment, custom-field, reminder and template member. Defaults are field-specific: some settings inherit account or platform configuration, while others have fixed defaults such as DisableSenderHeader=false. Do not assume that every omitted field inherits the site setting.
For a typical signer, supply Name, Address, AddressType, Role and SigningMethod. Address is the notification destination; it is distinct from the address used to verify a PIN. Roles include Signer, Reviewer and Interested. Submit uses WebClick when SigningMethod is omitted or null. Set the intended method explicitly for each signing party. Use international phone numbers, such as +34600000000, for a mobile notification Address or a PhoneNumber used for verification.
SigningMethod | Additional configuration |
|---|---|
WebClick | Web confirmation. |
MobilePin | Supply PhoneNumber for PIN delivery. |
EmailPin | Supply EmailAddress for PIN delivery. |
Challenge | Supply SignatureChallenge and SignatureChallengeResponse. |
Handwriting | Handwritten input; appearance and signed-document settings depend on the workflow. |
ExternalHandwriting | Requires the corresponding external handwriting integration. |
UserCertificate | Requires a compatible user-certificate signing configuration. |
Party options also control signing order (SigningOrder), required participation (Required), waiting time in minutes (TimeToWait), signing step (SignStep), geolocation (SignerGeoLocationPolicy), captcha, notification suppression and templates, delivery subdomains, WebView, Lite Flow, identity fields and delegated-signature settings. WhatsApp policies and custom delivery settings require the corresponding account configuration.
SignatureAppearances is a JSON descriptor carried as a string, rather than a nested JSON object. See Generated signed document for positioning and related options.
| Settings | Behavior |
|---|---|
TimeToLive | Lifetime in minutes. Minimum 60; the request-level ceiling is 86400 minutes and the configured deployment maximum can be lower. |
CertificationLevel | Choose a supported certification level for the jurisdiction and account. |
CommitmentOptions | Accept, Reject or AcceptOrReject. |
CommitmentCommentsAllowed, RequireRejectReason, RejectReasons | Rejection reasons require comments to be enabled and a mode that allows rejection. |
GenerateSignedDocument, GenerateSignedDocumentOptions | Control the additional signed PDF. Account and certification requirements apply. |
AffidavitKinds, AffidavitLanguage | Select evidence generation and its language. Include OnDemand at submission if later on-demand affidavits are needed. |
SummaryAffidavit | Document, attachment, event and masking settings for a summary affidavit. IncludedCommitments accepts None or Signers; the generation job uses None when omitted. |
PushNotificationUrl, PushNotificationFilter, PushNotificationExtraData | Configure asynchronous callbacks. Supported events include Processed, Sent, Delivered, Signed, Rejected, FullySigned, Closed, FullySent, FullyDelivered, AffidavitPublished. |
Notification text, templates, Reminders | Customize the signature request, reminders, progress and final notifications. Custom reminders can be disabled by platform configuration. Reminders.Max must be positive and is checked against the lifetime: at most 3 for a one-day TTL, at most the number of full TTL days for 2–20 days, and at most 20 for longer lifetimes. |
AttachToSignatureRequest, AttachToFinalNotification | Select main content and/or evidence attachments. Selecting attachments requires actual submitted attachments. Final-notification content settings must be consistent with enabled final notifications. |
EvidenceAccessControlMethod and challenge fields | Configure access to evidence in custody. |
OnlineRetentionPeriod, NotaryRetentionPeriod, NotaryProfile, LtaStorage | Retention and custody options. A nonzero notary period is mapped to five years and requires a profile. A profile without a nonzero period is rejected. LTA requires site enablement. See Archiving and retention. |
Language, SignedRedirectUrl, CustomLayoutLogoUrl | User-facing language, redirect and branding. The custom logo URL must be absolute. |
CustomFields, AdditionalCommitments, SecurityTags, CostCentre | Additional form content, commitments and metadata. At most one security tag is accepted; see the schema for the full structures. |
Every attachment must have nonempty Data. An attachment marked with the RequireContentCommitment attribute must be a valid PDF with compatible file metadata. Other supporting attachments can use other supported content types. Document validation continues asynchronously; for example, encrypted PDFs can fail processing after Submit was accepted.
Create submit.json using the following structure. Replace the document placeholder with Base64-encoded bytes from your actual document; configure the callback endpoint to receive HTTPS requests.
{
"LookupKey": "CONTRACT-001",
"Subject": "Contract for signature",
"Document": "<base64-encoded-pdf>",
"SigningParties": [
{
"Name": "Alex Example",
"Address": "signer@example.com",
"AddressType": "Email",
"SigningMethod": "WebClick",
"Role": "Signer"
}
],
"Options": {
"TimeToLive": 1440,
"CommitmentOptions": "AcceptOrReject",
"PushNotificationUrl": "https://integrator.example.com/callbacks/evisign",
"PushNotificationFilter": ["Processed", "FullySigned", "Closed", "AffidavitPublished"],
"AffidavitKinds": ["Submitted", "PartyCommitted", "Main", "OnDemand"]
}
}The interactive reference supplies a complete Base64 example containing a small PDF. Adjust the parties, enabled options and callback URL before sending a request.
curl --user "$EVISIGN_USER:$EVISIGN_PASSWORD" \
--header 'Content-Type: application/json' \
--header 'X-Evi-IdempotencyToken: 550e8400-e29b-41d4-a716-446655440000' \
--data-binary @submit.json \
'https://api.ecertia.com/v1/evisign/submit'Success (200 OK):
{ "uniqueId": "d11caec270bd4739afd5aa7600920538" }Supply X-Evi-IdempotencyToken with a unique value per logical submission. Tokens are scoped to the authenticated user. Retry that same submission with the same token. The X-Evi-IdempotencyStatus response header reports New for a first request, Replay for a cached successful result (202 Accepted) or Conflict when a request with that token is already in progress (409 Conflict). A replay returns the original submission result without issuing another EviSign. Use a new token for a different submission.
GET /v1/evisign/query| Parameter | Description |
|---|---|
WithUniqueIds | Filter by EviSign UUIDs; comma-separated values are supported. |
WithLookupKeys | Filter by client lookup keys; comma-separated values are supported. A lookup key containing a comma cannot be represented as one value in this form. |
OnState | Draft, Submitted, Processed, Sent, Closed, Forwarded, Received. |
WithOutcome | None, Signed, Rejected, Failed, Expired, Cancelled. |
OrderResultsBy | Supported value: CreationDate. |
Offset | Entries to skip; defaults to 0. |
Limit | Maximum entries to return, up to 100, subject to the inclusion rules below. |
IncludeAffidavitsOnResult | Include affidavit entries. Defaults to false. |
IncludeEventsOnResult | Include event metadata; defaults to false. |
IncludeAttachmentsOnResult | Include attachment entries. Defaults to true in ASP.NET. The legacy service uses its configured default, which is true unless changed. |
IncludeAttachmentBlobsOnResult | Compatibility flag for attachment file contents. Set false for metadata only when attachment entries are included. |
IncludeAffidavitBlobsOnResult | Compatibility flag for affidavit file contents. Set false for metadata only when affidavit entries are included. |
IncludeDocumentsOnResult | Include generated-document metadata; defaults to false. |
The response uses state for workflow progress and outcome for the result. Forwarded and Received are accepted state filters and can be returned for records stored with those states. The normal workflow progresses through Draft, Submitted, Processed, Sent and Closed, with some paths closing before Sent. Omit the state and outcome parameters when you want unfiltered results. Cancelled is an outcome filter and can be returned with state set to Closed after the cancellation is processed. See the EviSign lifecycle.
The ASP.NET API defaults both file-content flags to false. The legacy service uses deployment settings whose declared defaults enable attachment and affidavit bytes. With those legacy defaults and the flags omitted, Query can include attachment bytes and defaults to one result. Affidavit entries are included only if you enable them. When either family is included with file bytes, the maximum Limit is 1.
For metadata-only pages on either stack, explicitly set IncludeAttachmentBlobsOnResult=false and IncludeAffidavitBlobsOnResult=false. Enable the attachment or affidavit entries you need and set Limit up to 25. Explicitly disable both entry flags for lightweight pages up to 100. Use Bundle to retrieve the available files.
curl --get --user "$EVISIGN_USER:$EVISIGN_PASSWORD" \
--data-urlencode 'WithUniqueIds=d11caec2-70bd-4739-afd5-aa7600920538' \
--data-urlencode 'IncludeAttachmentsOnResult=false' \
--data-urlencode 'IncludeAffidavitsOnResult=false' \
--data-urlencode 'Limit=100' \
'https://api.ecertia.com/v1/evisign/query'The response envelope contains results and totalMatches. Each result exposes the EviSign's evidenceId, lookup key, state, outcome, timestamps, parties and the metadata selected by the inclusion flags. Consult the response schema for the complete structure and nullable fields. An empty query can return:
{ "results": [], "totalMatches": 0 }Advance Offset by the number of results consumed until the result page is exhausted. Compatibility settings can affect optional/default result values; do not interpret a default timestamp or a signature's accepted value in results[].signatures[] as proof of completion without the corresponding state or event.
POST /v1/evisign/cancel| Field | Description |
|---|---|
UniqueId | Required EviSign UUID; the empty UUID is invalid. |
Comments | Required, nonblank cancellation reason; maximum 2048 characters. |
Quietly | Optional boolean, default false. Suppress party notifications when true. |
The caller must own an EviSign that has reached Processed and is still open. A 200 response means the API accepted the cancellation request for processing. Confirm cancellation through Query when state is Closed and outcome is Cancelled. If subscribed, the Closed callback carries AdditionalData.OutCome set to Cancelled.
{
"UniqueId": "d11caec2-70bd-4739-afd5-aa7600920538",
"Comments": "Contract superseded by a revised version.",
"Quietly": false
}Success (200 OK):
{ "uniqueId": "d11caec270bd4739afd5aa7600920538" }Invalid comments return 400; a missing EviSign returns 404; a non-owner returns 401; an ineligible state returns 409.
POST /v1/evisign/resendSupply the EviSign UniqueId and the party's existing NotificationAddress. This operation resends access to that party; it does not change the address or create another signer.
{
"UniqueId": "d11caec2-70bd-4739-afd5-aa7600920538",
"NotificationAddress": "signer@example.com"
}Success (200 OK):
{
"uniqueId": "d11caec270bd4739afd5aa7600920538",
"notificationAddress": "signer@example.com"
}The caller must own the EviSign and the address must match exactly one party. Address matching is exact and case-sensitive; reuse the stored notification address. The party must still be eligible to receive a signature request: requests cannot be resent after that party has signed or rejected, or when signature requests are disabled. Email and SMS resends have configured cooldowns. SMS also requires site enablement, uses the configured resend limit and requires the SmsOnly signature-request policy.
Validation and ineligible-party failures return 400; a missing EviSign returns 404; a non-owner returns 401; zero or multiple address matches return 409. A cooldown or resend limit returns 429; honor Retry-After when supplied. Disabled SMS resend can surface as 500, so confirm enablement before repeatedly retrying that failure.
POST /v1/evisign/affidavitrequestThe original submission must enable OnDemand in Options.AffidavitKinds and use a compatible affidavit profile. The caller must own the EviSign; it must be neither Draft nor Closed, and the configured maximum number of requests must not have been reached.
| Field | Description |
|---|---|
UniqueId | Required, nonempty EviSign UUID. |
IncludeDocument | Optional boolean; include the main document. |
IncludeAttachments | Optional boolean; include only attachments submitted with RequireContentCommitment enabled. |
IncludeEvents | Optional boolean; include event details. |
IncludedCommitments | Optional None or Signers. The generation job uses None when omitted. Reviewers and All are unsupported for rendering. |
Masking | Optional array of supported field-mask directives or permitted text masks. Empty strings and $ alone are invalid; arbitrary field paths are not accepted. |
{
"UniqueId": "d11caec2-70bd-4739-afd5-aa7600920538",
"IncludeDocument": true,
"IncludeAttachments": false,
"IncludeEvents": true,
"IncludedCommitments": "Signers"
}Success (200 OK):
{ "requestId": "90bb86a552b64eaa9cdf97caea9b617c" }Generation is asynchronous. An accepted request can go unfulfilled if the EviSign closes or earlier requests reach the limit before generation. Track the request with requestId and look for that ID in AdditionalData.RequestId in the AffidavitPublished callback. To retrieve a generated file, use Bundle or pass its affidavit ID to the shared affidavit download API. Query with IncludeAffidavitsOnResult=true shows available affidavit metadata. Compare UUIDs by value because the callback and Query can format the same ID differently.
Missing or non-owned entries, invalid state, unavailable on-demand generation, exhausted request limits and unsupported commitment or masking values return 400.
GET /v2/evisign/{Id}/bundleId is the EviSign UUID. The ZIP always includes the original document. The following optional query flags default to false and add the available files when true:
| Flag | Files |
|---|---|
IncludeAffidavits | Generated affidavits. |
IncludeAttachments | Stored supporting attachments. |
IncludeNotifications | Stored notification EML files. |
IncludeAdditionalDocuments | Available generated documents, including the signed document when the workflow produced it. |
curl --fail-with-body --user "$EVISIGN_USER:$EVISIGN_PASSWORD" \
--output evisign-bundle.zip \
'https://api.ecertia.com/v2/evisign/d11caec2-70bd-4739-afd5-aa7600920538/bundle?IncludeAffidavits=true&IncludeAttachments=true&IncludeNotifications=true&IncludeAdditionalDocuments=true'Success is 200 OK with Content-Type: application/zip, containing file bytes. It is not a JSON object or Base64 wrapper. Check the HTTP status and content type before treating the saved response as an archive: an error body can otherwise be saved under the .zip filename.
Access is scoped to the authenticated site; a missing or inaccessible EviSign returns 404. The operation does not require the EviSign to be closed. File availability depends on processing, workflow and retention. Errors use the v2 Problem Details format, documented in the interactive reference.
Send POST /EviSign/SignLink to the application host. Supply UniqueIds and Party for the signer or reviewer; the service returns a one-hour URL plus per-item validation results. The EviSigns must already be processed, owned by the caller and eligible for signing.
SignLink has its own single/multiple-document restrictions, discarded-item threshold, Lite Flow settings, response casing and XML contracts. Use the dedicated SignLink API guide for the full request, response and error examples.
The v1 issuer operations accept the PascalCase request fields shown above and emit camelCase success fields such as uniqueId, results and requestId. V1 UUID responses use 32 hexadecimal characters without dashes; UUID inputs accept the usual dashed form. Default-valued response members can be omitted. Their JSON errors contain the lower-case responseStatus envelope, with errorCode, message, optional errors and diagnostic details. SignLink success uses camelCase (uniqueId, url, expiresAt, results); an authentication failure has an empty body. Bundle success is binary ZIP and its errors use Problem Details with PascalCase standard fields (Type, Title, Status, Detail, Instance).
| Status | Typical issuer API meaning |
|---|---|
200 | Operation succeeded or its asynchronous request was accepted. |
202 | Submit idempotent replay; original result returned. |
400 | Invalid input or business-rule failure; see each operation's prerequisites. |
401 | Authentication failed, or Cancel/Resend was requested by a non-owner. |
403 | Required service, API or operation permissions are missing. |
404 | Cancel/Resend target missing, or Bundle target missing or outside the caller's site. |
409 | Submit token in progress, invalid cancellation state, or ambiguous/missing resend party. |
429 | Resend limit or cooldown reached. |
500 | Unexpected failure; inspect the response and correlate it with your request before retrying. |
SignLink's status meanings are listed in its error reference. For SignLink, branch on the HTTP status; its errorCode and message can be localized diagnostic text. For the issuer operations, use the HTTP status and any documented structured error details rather than matching messages. See Error handling for retry guidance, taking account of each operation's format and Submit idempotency.