# EviSign API

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](/fr/products/namirialnotify/apis/oas/evisign-api) 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](/fr/products/namirialnotify/services/evisign).

## Environments

| 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](#submit-an-evisign) | `POST /v1/evisign/submit` | Submit a document and parties. |
| [Query](#query-evisigns) | `GET /v1/evisign/query` | Read status and selected metadata. |
| [Cancel](#cancel-an-evisign) | `POST /v1/evisign/cancel` | Request cancellation. |
| [Resend](#resend-a-signature-request) | `POST /v1/evisign/resend` | Resend a party's signature request. |
| [Affidavit Request](#request-an-on-demand-affidavit) | `POST /v1/evisign/affidavitrequest` | Request an affidavit asynchronously. |
| [Bundle](#download-an-evisign-bundle) | `GET /v2/evisign/{Id}/bundle` | Download a ZIP of evidence files. |
| [SignLink](/fr/products/namirialnotify/apis/evisign-signlink) | `POST /EviSign/SignLink` | Generate a temporary signing URL. |


## Authentication and permissions

All seven operations require HTTP Basic authentication over HTTPS:

```http
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](/fr/products/namirialnotify/dev/security-best-practices#credential-handling) for storing credentials and protecting callback endpoints.

## Workflow

1. Submit the main document, parties and options. Save the returned `uniqueId` and your own `LookupKey`.
2. 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.
3. Deliver the signing experience through the platform's signature-request notification or generate a [SignLink](/fr/products/namirialnotify/apis/evisign-signlink) after the EviSign has been processed. Treat that returned URL as sensitive.
4. Track party commitments and the overall outcome. A party's signature and the whole EviSign reaching its final outcome are distinct events.
5. 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](/fr/products/namirialnotify/user-guides/states-outcomes) and the [service lifecycle](/fr/products/namirialnotify/services/evisign) when interpreting progress. Optional files become available as the workflow generates them; requesting a bundle does not create missing evidence.

## Submit an EviSign

```text
POST /v1/evisign/submit
```

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

### Request fields

| 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](/fr/products/namirialnotify/apis/oas/evisign-api) 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.

### Parties and signing methods

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](/fr/products/namirialnotify/services/evisign#generated-signed-document-gsd) for positioning and related options.

### Options and conditional rules

| 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](/fr/products/namirialnotify/user-guides/archiving). |
| `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.

### Example

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.

```json
{
  "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.

```bash
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`):

```json
{ "uniqueId": "d11caec270bd4739afd5aa7600920538" }
```

### Idempotent retries

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.

## Query EviSigns

```text
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](/fr/products/namirialnotify/services/evisign#lifecycle-overview).

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](#download-an-evisign-bundle) to retrieve the available files.

```bash
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](/fr/products/namirialnotify/apis/oas/evisign-api) for the complete structure and nullable fields. An empty query can return:

```json
{ "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.

## Cancel an EviSign

```text
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`.

```json
{
  "UniqueId": "d11caec2-70bd-4739-afd5-aa7600920538",
  "Comments": "Contract superseded by a revised version.",
  "Quietly": false
}
```

Success (`200 OK`):

```json
{ "uniqueId": "d11caec270bd4739afd5aa7600920538" }
```

Invalid comments return `400`; a missing EviSign returns `404`; a non-owner returns `401`; an ineligible state returns `409`.

## Resend a signature request

```text
POST /v1/evisign/resend
```

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

```json
{
  "UniqueId": "d11caec2-70bd-4739-afd5-aa7600920538",
  "NotificationAddress": "signer@example.com"
}
```

Success (`200 OK`):

```json
{
  "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.

## Request an on-demand affidavit

```text
POST /v1/evisign/affidavitrequest
```

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


```json
{
  "UniqueId": "d11caec2-70bd-4739-afd5-aa7600920538",
  "IncludeDocument": true,
  "IncludeAttachments": false,
  "IncludeEvents": true,
  "IncludedCommitments": "Signers"
}
```

Success (`200 OK`):

```json
{ "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](/fr/products/namirialnotify/apis/downloads-api#download-affidavit-pdfs-by-id). 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`.

## Download an EviSign bundle

```text
GET /v2/evisign/{Id}/bundle
```

`Id` 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. |


```bash
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](/fr/products/namirialnotify/apis/oas/evisign-api).

## Generate a signing link

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](/fr/products/namirialnotify/apis/evisign-signlink) for the full request, response and error examples.

## Response formats and errors

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](/fr/products/namirialnotify/apis/evisign-signlink#http-responses-and-errors). 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](/fr/products/namirialnotify/dev/error-handling) for retry guidance, taking account of each operation's format and Submit idempotency.

## Related documentation

- [Interactive EviSign reference](/fr/products/namirialnotify/apis/oas/evisign-api)
- [SignLink API](/fr/products/namirialnotify/apis/evisign-signlink)
- [EviSign workflow, signing appearance and callbacks](/fr/products/namirialnotify/services/evisign)
- [Shared affidavit and attachment downloads](/fr/products/namirialnotify/apis/downloads-api)
- [API reference overview](/fr/products/namirialnotify/apis/overview)