# EviSign SignLink API

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.

See the [EviSign API guide](/fr/products/namirialnotify/apis/evisign-api) for submission, tracking and evidence retrieval, and the [interactive reference](/fr/products/namirialnotify/apis/oas/evisign-api) for the JSON schemas.

## Overview

The SignLink operation generates a temporary URL that allows one party to access the signing flow for one or more previously issued EviSigns. It is intended for integrations that need to present the signing flow directly, without relying on the signature-request notification sent by the platform.

The generated URL is valid for **one hour**. Always use the URL returned by the service as an opaque value; do not build, modify or shorten it, and do not assume its host: the host is taken from the brand configured for your account and is not necessarily the host you sent the request to.

```text
POST /EviSign/SignLink
```

> **Security note.** The returned URL grants access to the signing flow for the specified party until it expires. Treat it as sensitive: share it only with the intended party, transmit it over a protected channel, and avoid logging it.


SignLink replaces the former BulkSign endpoint. See the **Migrating from BulkSign** section before reusing an existing BulkSign integration, especially if it sends `DiscardedThreshold`.

## Environments

| Environment | Endpoint |
|  --- | --- |
| Production | `https://app.evicertia.com/EviSign/SignLink` |
| Pre-production / QA | `https://app.ecertia.com/EviSign/SignLink` |


Use the documented path `/EviSign/SignLink` in new integrations. Do not append an action segment.

## Authentication

The request must use HTTP Basic authentication with an account that has both API access and the EviSign service enabled.

```http
Authorization: Basic <base64(username:password)>
```

The authenticated account must own every EviSign included in the generated link. An EviSign that belongs to another account is discarded from the request.

If authentication is missing or invalid, the service answers `401 Unauthorized` with an empty body. If the account exists but the EviSign service or API access is disabled, the service answers `500 Internal Server Error`; contact support to have the service enabled.

## Content formats

SignLink accepts JSON and XML request bodies.

| Header | Supported values | Behaviour |
|  --- | --- | --- |
| `Content-Type` | `application/json`, `application/xml`, `text/xml` | Selects the request-body format. XML bodies are read with the data-contract names described in the **XML compatibility** section. |
| `Accept` | `application/json`, `text/json`, `application/xml`, `text/xml` | Selects the response format. JSON is returned when the header is omitted or contains only `*/*`. When several media types are listed, the **first supported** one wins; `q` values are ignored. |


Successful XML responses are served with `Content-Type: application/xml`, even when requested with `text/xml`. XML error responses can use `text/xml` when that media type is selected through `Accept`.

Request and response formats are independent: a JSON request may ask for an XML response and vice versa.

The examples below use JSON.

## Request parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `UniqueIds` | Array of UUIDs | Yes | Identifiers of the EviSigns to include. The array must contain at least one identifier and cannot exceed a configured maximum number of items per signing operation (25 by default). Duplicated identifiers count towards that maximum. |
| `Party` | String | Yes | E-mail address or telephone number of the party that will access the signing flow. The value is lower-cased and trimmed before it is matched. The party must occur exactly once as a signer or reviewer in every included EviSign; an interested party is not valid. |
| `Attributes` | Array of key/value objects | No | Additional SignLink attributes. Only `ReturnUrl` is supported — see the **Return URL** section. Do not send any other key. |
| `DiscardedThreshold` | Integer | No | Maximum **number of EviSigns** that may be discarded while still generating a link. The default is `0`, meaning a single discarded item fails the request. This value is a count, not a percentage, and must not be negative. At least one valid EviSign must always remain. |
| `LiteFlow` | Boolean | No | Controls the simplified signing flow. It applies only when the link ends up containing a single valid EviSign; it is ignored, without error, when the link contains several. `true` requests Lite Flow, `false` forces the standard flow, and omission lets the delivery-channel configuration decide when the party has a delivery subdomain. See the **Lite Flow compatibility** section. |
| `Language` | String | No | Language used in the signing flow when the link contains **several** EviSigns. Supported values are `ca`, `de`, `en`, `es`, `fr`, `it`, `pt`, `pt-BR`, `ro` and `el`, and they are case-sensitive. For a link that ends up containing a single EviSign the value is validated but not applied: that flow uses the language configured in the EviSign or in its party. |


In JSON, parameter names are matched case-insensitively. In XML they are case- and order-sensitive.

An item in `Attributes` has the following structure:

```json
{
  "Key": "ReturnUrl",
  "Value": "https://client.example.com/signing/completed"
}
```

The `Values` member accepted by the XML contract has no effect and should be omitted. Send each key at most once; duplicate keys cause the request to fail.

### Return URL

`ReturnUrl` must be an absolute HTTP or HTTPS URL. It takes precedence over the `SignedRedirectUrl` configured in the EviSign, for both single- and multiple-EviSign links.

When the party finishes the flow, they are redirected to that URL with two query parameters appended:

| Parameter | Value |
|  --- | --- |
| `uniqueId` | Identifier of the EviSign the party has just resolved. |
| `accepted` | `true` when the EviSign was signed/accepted, `false` when it was rejected. |


Existing query parameters in `ReturnUrl` are preserved; parameters with these two names are overwritten.

## EviSign requirements

Each EviSign included in the generated link must meet all of the following conditions:

- It exists and belongs to the authenticated account.
- It has been processed (`processedOn` is set) and is not closed, expired or cancelled.
- `Party` occurs exactly once as a signer or reviewer.
- The party uses a supported signing method.


The signing method is set when the EviSign is issued. See [Submit an EviSign](/fr/products/namirialnotify/apis/evisign-api#submit-an-evisign) for the corresponding `SigningMethod` configuration.

For a single EviSign, the supported signing methods are:

- `MobilePin`
- `EmailPin`
- `Handwriting`
- `WebClick`


An EviSign that fails one of these checks is marked as discarded in `results`; the rest of the request continues.

### Additional rules for several EviSigns

The following rules apply as soon as **more than one of the requested identifiers exists**, even if some of those EviSigns are going to be discarded for another reason:

Rules that discard the individual EviSign:

- The supported signing methods are `MobilePin`, `EmailPin` and `WebClick`. `Handwriting` is only supported when the link contains one EviSign.
- Delivery subdomains are not supported.
- Reject reasons, required reject reasons and signature questions are not supported.


Rules that reject the **whole request** with `400 Bad Request`:

- The party must use the same signing method in every EviSign.
- All EviSigns must use the same commitment-option mode, and it must be `Accept`, `Reject` or `AcceptOrReject`. An EviSign whose commitment options are disabled cannot be included.
- Geolocation policies must be compatible: EviSigns with geolocation disabled cannot be combined with EviSigns where geolocation is enabled or required.


### Discarded items and the threshold

Items that fail an item-level check are marked as discarded. The service generates the link only when the number of discarded items does not exceed `DiscardedThreshold` **and** at least one valid item remains.

| Requested | Discarded | `DiscardedThreshold` | Result |
|  --- | --- | --- | --- |
| 3 | 0 | `0` | `200 OK`, link with 3 EviSigns |
| 3 | 1 | `0` | `409 Conflict` |
| 3 | 1 | `1` | `200 OK`, link with 2 EviSigns |
| 3 | 2 | `1` | `409 Conflict` |
| 3 | 3 | `10` | `409 Conflict` — a link is never generated when every item is discarded |


Identifiers that do not exist are reported as discarded items and count towards the threshold in exactly the same way.

## Lite Flow compatibility

The `LiteFlow` request parameter applies when the resulting SignLink contains a single valid EviSign. Requests that end up with several valid EviSigns use the multiple-document signing flow and ignore `LiteFlow`.

When the party has a delivery subdomain configured and `LiteFlow` is omitted, the delivery channel's own Lite Flow setting decides. When there is no delivery subdomain, Lite Flow is applied only if `LiteFlow` is `true`.

The delivery-channel `EviSignLiteFlow` setting is configured through a support ticket. See [Create an EviSign](/fr/products/namirialnotify/issuer/create-evisign) for further information about issuing EviSigns and Lite Flow.

Lite Flow is not compatible with an EviSign when any of the following applies:

- The signing method is `Handwriting` or `Challenge`.
- Geolocation is enabled or required.
- The signing step is `BeforeDoc` or `End`.
- `SignedRedirectUrl` is configured in the EviSign.


Requesting Lite Flow for an incompatible EviSign fails with `400 Bad Request`. Request the standard flow by setting `LiteFlow` to `false`.

## Example: one EviSign with Lite Flow

### Request

```http
POST https://app.ecertia.com/EviSign/SignLink HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic <base64(username:password)>
Host: app.ecertia.com

{
  "UniqueIds": [
    "d11caec2-70bd-4739-afd5-aa7600920538"
  ],
  "Party": "signer@example.com",
  "LiteFlow": true
}
```

### Response

```json
{
  "uniqueId": "c7451684-b831-46af-8417-28e378e9ddaa",
  "url": "https://app.ecertia.com/Public/EviSign/Delivery/Start?eid=ENCRYPTED_DATA&lf=true",
  "expiresAt": "2026-09-09T14:22:07.0010000Z",
  "results": [
    {
      "evidenceId": "d11caec2-70bd-4739-afd5-aa7600920538",
      "discarded": false,
      "discardReason": null,
      "lookupKey": "Contract-001",
      "state": "Processed",
      "outcome": "None",
      "creationDate": "2026-09-09T13:21:58.2650000Z",
      "lastStateChangeDate": "2026-09-09T13:22:02.0000000Z",
      "submittedOn": "2026-09-09T13:21:59.0000000Z",
      "processedOn": "2026-09-09T13:22:02.0000000Z",
      "sentOn": null,
      "closedOn": null,
      "signedOn": null,
      "rejectedOn": null,
      "failedOn": null,
      "expiredOn": null,
      "timeToLive": 1500
    }
  ]
}
```

## Example: several EviSigns with a return URL

```http
POST https://app.ecertia.com/EviSign/SignLink HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic <base64(username:password)>
Host: app.ecertia.com

{
  "UniqueIds": [
    "d11caec2-70bd-4739-afd5-aa7600920538",
    "a9e95c25-7aa2-4c66-9948-b7d17d601754"
  ],
  "Party": "signer@example.com",
  "Attributes": [
    {
      "Key": "ReturnUrl",
      "Value": "https://client.example.com/signing/completed"
    }
  ],
  "DiscardedThreshold": 0,
  "Language": "en"
}
```

The response has the same structure as the single-EviSign response. `results` contains the status of each requested EviSign, and `url` contains the multiple-document signing link.

## Response parameters

| Parameter | Type | Description |
|  --- | --- | --- |
| `uniqueId` | UUID | Identifier of the generated SignLink operation. It is not an EviSign identifier, and a new one is generated even when the link contains a single EviSign. |
| `url` | String | Temporary signing URL. Use it exactly as returned. |
| `expiresAt` | Date and time | UTC expiration date of the generated URL, one hour after it was created. |
| `results` | Array | Validation and state information for the requested EviSigns. |


Each item in `results` contains:

| Parameter | Type | Description |
|  --- | --- | --- |
| `evidenceId` | UUID | EviSign identifier. |
| `discarded` | Boolean | Indicates whether the EviSign was excluded from the generated link. |
| `discardReason` | String or null | Reason why the item was discarded. It is `null` for an accepted item. |
| `lookupKey` | String or null | Client-provided lookup key of the EviSign. |
| `state` | String or null | Current EviSign state: `Draft`, `Submitted`, `Processed`, `Forwarded`, `Received`, `Sent` or `Closed`. |
| `outcome` | String or null | Current EviSign outcome: `None`, `Signed`, `Rejected`, `Expired`, `Failed` or `Cancelled`. |
| `creationDate` | Date and time | Creation date of the EviSign. |
| `lastStateChangeDate` | Date and time or null | Date of its latest state change. |
| `submittedOn` | Date and time or null | Submission date. |
| `processedOn` | Date and time or null | Processing date. |
| `sentOn` | Date and time or null | Signature-request delivery date, when applicable. |
| `closedOn` | Date and time or null | Closure date. |
| `signedOn` | Date and time or null | Signature date. |
| `rejectedOn` | Date and time or null | Rejection date. |
| `failedOn` | Date and time or null | Failure date. |
| `expiredOn` | Date and time or null | Expiration date. |
| `timeToLive` | Integer | EviSign lifetime in minutes, counted from `submittedOn`. |


Notes on reading `results`:

- JSON property names are camelCase and null values are serialized explicitly rather than omitted.
- In JSON, dates are ISO-8601 round-trip values in UTC, with seven fractional digits and a trailing `Z`.
- In XML, `ExpiresAt` is UTC (`...Z`), but the EviSign timestamps carry the platform's local UTC offset instead (for example `2026-09-09T15:21:58.265+02:00`), and trailing zeros in the fractional part are trimmed. Parse them as offset-aware values and convert to UTC yourself.
- Metadata may be unavailable or contain default values for a discarded item, especially when its identifier does not exist. Do not interpret its state, dates, or lifetime; rely on `discarded` and `discardReason`.
- `results` reports every identifier that did not resolve to an EviSign, including repetitions. A repeated identifier that does resolve to an existing EviSign is reported once.
- The order of `results` does not necessarily match the order of `UniqueIds`.


## HTTP responses and errors

| HTTP status | Meaning |
|  --- | --- |
| `200 OK` | The link was generated. Check `results` for the items that were accepted or discarded. |
| `400 Bad Request` | The request is invalid: no identifiers, more identifiers than the configured maximum, an unsupported `Language`, an invalid `ReturnUrl`, repeated or reserved attribute keys, mixed signing methods, incompatible commitment options or geolocation policies, or an EviSign that is incompatible with Lite Flow. |
| `401 Unauthorized` | Authentication is missing or invalid. The body is empty. |
| `409 Conflict` | All items were discarded, or the number of discarded items exceeded `DiscardedThreshold`. |
| `500 Internal Server Error` | An unexpected error occurred, or the account does not have the EviSign service or API access enabled. |


Except for `401`, error responses use the legacy `responseStatus` structure and include an `X-Evi-Error-Id` response header. Provide this error identifier when contacting support.

`responseStatus` contains:

| Property | Type | Description |
|  --- | --- | --- |
| `errorCode` | String | Diagnostic classification, which may be an exception name such as `ArgumentException` or a localized status description. It is not a stable identifier for client logic. |
| `message` | String | Human-readable description. Its language is determined by the `_culture` cookie when present, then by the request's `Accept-Language` header, falling back to the platform default language. |
| `stackTrace` | String or null | `null` for normal API accounts. Do not rely on its absence, and do not surface its contents to end users. |
| `errors` | Array | Detail entries with `errorCode`, `fieldName`, `message` and `stackTrace`. Empty for the errors described above. |
| `errorId` | UUID | Same value as the `X-Evi-Error-Id` header. |
| `statusCode` | Integer | Repeats the HTTP status code. |


Branch on the HTTP status code. Treat `message` and `errorCode` as diagnostic text: either can be localized or change between responses. For example, `409` uses a localized status description rather than a fixed `Conflict` code. Authentication failures still return an empty `401` body.

### Error example

Request:

```json
{
  "UniqueIds": [],
  "Party": "signer@example.com"
}
```

Response (`400 Bad Request`):

```json
{
  "responseStatus": {
    "errorCode": "ArgumentException",
    "message": "No EviSigns specified. Specify some EviSign unique ids to store in basket",
    "stackTrace": null,
    "errors": [],
    "errorId": "04131c7e-e315-4fe0-b0ea-3d06a76019c8",
    "statusCode": 400
  }
}
```

## XML compatibility

When XML is used, the request and response retain the legacy `EviSignBulkSign` and `EviSignBulkSignResponse` data-contract names for backward compatibility. The endpoint is still `/EviSign/SignLink`.

All elements belong to the `http://schemas.servicestack.net/types` namespace and must appear in the order shown: `UniqueIds`, `Party`, `Attributes`, `DiscardedThreshold`, `LiteFlow`, `Language`. Optional elements may be omitted, but the elements that are present must keep that relative order.

Request:

```xml
<EviSignBulkSign xmlns="http://schemas.servicestack.net/types">
  <UniqueIds xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <a:guid>d11caec2-70bd-4739-afd5-aa7600920538</a:guid>
  </UniqueIds>
  <Party>signer@example.com</Party>
  <LiteFlow>true</LiteFlow>
</EviSignBulkSign>
```

Response:

```xml
<EviSignBulkSignResponse xmlns="http://schemas.servicestack.net/types">
  <UniqueId>c7451684-b831-46af-8417-28e378e9ddaa</UniqueId>
  <Url>https://app.ecertia.com/Public/EviSign/Delivery/Start?eid=ENCRYPTED_DATA&amp;lf=true</Url>
  <ExpiresAt>2026-09-09T14:22:07.001Z</ExpiresAt>
  <Results>
    <EviSignBulkResponseItem>
      <EvidenceId>d11caec2-70bd-4739-afd5-aa7600920538</EvidenceId>
      <Discarded>false</Discarded>
      <CreationDate>2026-09-09T15:21:58.265+02:00</CreationDate>
      <!-- remaining members, in the order of the response table above -->
    </EviSignBulkResponseItem>
  </Results>
</EviSignBulkSignResponse>
```

XML error responses reuse the `EviSignBulkSignResponse` root element and carry a single `ResponseStatus` child with the same members as the JSON `responseStatus` object.

An `Attributes` entry is expressed as:

```xml
<Attributes>
  <KeyValue>
    <Key>ReturnUrl</Key>
    <Value>https://client.example.com/signing/completed</Value>
  </KeyValue>
</Attributes>
```

## Migrating from BulkSign

| BulkSign | SignLink |
|  --- | --- |
| `POST /api/EviSign/BulkSign` | `POST /EviSign/SignLink` |
| `DiscardedThreshold` was described as a minimum **percentage** of EviSigns needed to generate the URL | `DiscardedThreshold` is interpreted as the maximum **number** of EviSigns that may be discarded, and defaults to `0` |
| JSON timestamps could carry the platform's local UTC offset, for example `2020-02-17T12:21:58.2659710+01:00` | JSON timestamps are normalized to UTC, with seven fractional digits and a trailing `Z`, for example `2026-09-09T13:21:58.2650000Z` |
| — | `Language` and `Attributes` (`ReturnUrl`) are available |


The legacy XML data-contract names (`EviSignBulkSign`, `EviSignBulkSignResponse`, `EviSignBulkResponseItem`) are preserved for compatibility. Nevertheless, integrations must update the endpoint and review the parameter semantics described above.

> **Check `DiscardedThreshold` before you migrate.** The legacy documentation presented a value such as `80` as meaning "80% must be ready". SignLink interprets `80` as "allow up to 80 discarded EviSigns". Set it to the number of discarded items you are willing to accept, or omit it to require that every EviSign is valid.