# EviNotice API

The EviNotice API lets you submit certified hosted notices, query multiple notices, retrieve individual notices by ID, download their attachments and affidavits, and manage notice batches. Single-notice and batch operations share HTTP Basic authentication and are documented together in the [interactive EviNotice reference](/products/namirialnotify/apis/oas/evinotice-api).

- [Single-notice operations](#endpoints): submit, query, and retrieve notices; download attachments and affidavits; request on-demand affidavits.
- [Batch operations](#batch-operations): create, query, configure, and delete batches; set their body; manage recipients and attachments.


EviNotice v2 is the current version. For the public Namirial Notify API environments, use routes under the `/v2/` base path, such as `/v2/EviNotice/Submit` for individual notices and `/v2/EviNotice/Batches` for batches. The legacy `/api/v2/...` form is still accepted for backward compatibility.

For end-to-end lifecycle, callback semantics, and integration guidance, see the [EviNotice service guide](/products/namirialnotify/services/evinotice).

## Environments

| Environment | Base URL |
|  --- | --- |
| Production | `https://api.evicertia.com` |
| Pre-production / QA | `https://api.ecertia.com` |


For shared environment guidance across services, see the [API reference overview](/products/namirialnotify/apis/overview#environments).

## Authentication

All endpoints require **HTTP Basic authentication**. Pass your Namirial Notify credentials as the username and password in the `Authorization` header.

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

Submitting a notice with a qualified level (`QERDS_ES`, `QERDS_IT` or legacy `QERDS`) also requires client-certificate authentication. The certificate must be issued and provisioned for this API use, and its email must match the issuing account. See [Integrate QeRDS notices](/products/namirialnotify/dev/qerds-integration#use-the-correct-environment-and-authentication).

See [credential handling](/products/namirialnotify/dev/security-best-practices#credential-handling), [callback endpoint hardening](/products/namirialnotify/dev/security-best-practices#callback-endpoint-hardening), and [operational security checks](/products/namirialnotify/dev/security-best-practices#operational-security-checks-before-go-live).

## Idempotency

EviNotice Submit supports idempotent submission. Include the `X-Evi-IdempotencyToken` header with a unique value per logical operation (a UUID is recommended).

If the same token is submitted again after the original request completed with `200 OK`, the server returns `202 Accepted` with the original response body — the notice is **not** resubmitted.

The following response codes are **not** cached and will re-execute the request regardless of token: `400`, `401`, `408`, `409`, `429`, and `5xx` responses.

## Error responses

EviNotice v2 uses **Problem+JSON** for error responses (`Content-Type: application/problem+json`).

```json
{
  "Status": 400,
  "Type": "<problem-type-uri>",
  "Title": "Invalid data provided",
  "Detail": "Recipient should be a valid email or an E.164 phone number.",
  "RequestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

| Field | Description |
|  --- | --- |
| `Status` | HTTP status code |
| `Type` | URI identifying the error type |
| `Title` | Short human-readable summary |
| `Detail` | Specific description of the error for this request |
| `RequestId` | Correlation ID for support escalation |


The `Type` above is an illustrative placeholder for the URI that identifies the problem type.

Common status codes and their causes:

| Status | Typical cause |
|  --- | --- |
| `400 Bad Request` | Invalid Submit or Query field, owner email, field combination or attachment. |
| `401 Unauthorized` | Incorrect credentials or missing Authorization header. |
| `403 Forbidden` | Submit permission/credit failure; Query Owner not permitted; affidavit download access failure or on-demand limit. |
| `404 Not Found` | Notice or affidavit not found; AffidavitRequest is restricted to notices submitted by the calling user. |
| `405 Method Not Allowed` | WhatsApp notification/PIN service disabled on Submit, or on-demand affidavit unavailable for this notice. |
| `409 Conflict` | Another Submit with the same idempotency token is running; retry with that token. |


For shared error handling guidance, see [Error handling](/products/namirialnotify/dev/error-handling).

## Endpoints

### Submit a new EviNotice

```
POST /v2/EviNotice/Submit
```

Submits a new certified hosted notice. On success, returns an `Id` (UUID) that uniquely identifies the notice.

**Required fields:** `Subject`, `Body`, `RecipientAddress`.

Optional fields cover recipient and issuer identity (`RecipientDisplayName`, `RecipientLegalName`, `IssuerLegalName`), attachments, certification options, delivery sign method, commitment settings, notification channels, and more.

**Qualified submissions:** The generic three-field requirement is not sufficient for QeRDS. Set `RecipientLegalIdRequired: true` and `EvidenceAccessControlMethod: Public`, and include `SubmittedAdvanced` plus `Read`, or `CompleteAdvanced`, in `AffidavitKinds`. Apply the selected variant's legal-document and PIN-routing requirements. The identity/enrollment fields are `RecipientLegalIdKind`, `RecipientLegalIdValue`, `QERDSEnrollmentAllowed`, `QERDSEnrollmentProfile` and `QERDSIdentityTenant`. See [QeRDS request fields](/products/namirialnotify/dev/qerds-integration#qerds-request-fields) for their types and conditions, and the [variant routing table](/products/namirialnotify/dev/qerds-integration#choose-the-variant-and-recipient-path) for `DeliverySignMethod` and the fixed PIN destination. Qualified Submit also requires the [client-certificate setup](#authentication).

**Idempotency:** To prevent duplicate submissions on retry, include an `X-Evi-IdempotencyToken` header with a unique value (a UUID is recommended). A replay of a previously `200 OK` submission returns `202 Accepted`. Responses `400`, `401`, `408`, `409`, `429`, and `5xx` are not cached for replay.

| Response | Description |
|  --- | --- |
| `200 OK` | EviNotice accepted. Body contains `{ "Id": "<uuid>" }`. |
| `202 Accepted` | Returned when an idempotent replay matches a previously `200 OK` submission. The original response body is returned unchanged. |
| `400 Bad Request` | Invalid request. Body is a Problem+JSON object with `Status`, `Type`, `Title`, `Detail`, and `RequestId`. |
| `401 Unauthorized` | Authentication failed. |
| `403 Forbidden` | The authenticated account lacks the required API permission for EviNotice, or the account has insufficient credit balance to submit the notice. |
| `409 Conflict` | Another Submit with the same idempotency token is still running. |
| `405 Method Not Allowed` | Requested WhatsApp notification or PIN functionality is disabled. |


The EviNotice v2 API uses PascalCase field names in responses. The submission response returns `Id` — note this differs from the camelCase `eviId` returned by the EviMail and EviSMS v1 submit endpoints.

**Example request:**

```http
POST /v2/EviNotice/Submit HTTP/1.1
Authorization: Basic <base64(username:password)>
Content-Type: application/json
X-Evi-IdempotencyToken: 550e8400-e29b-41d4-a716-446655440002

{
  "LookupKey": "NOTICE-2026-001",
  "Subject": "Important legal notice",
  "Body": "<html><body><p>Please review and acknowledge this notice.</p></body></html>",
  "RecipientAddress": "alice@example.com",
  "RecipientDisplayName": "Alice Martin",
  "RecipientLegalName": "Alice Martin García",
  "IssuerLegalName": "Acme Corp S.L.",
  "CertificationLevel": "Advanced_EU",
  "TimeToLive": 4320,
  "CommitmentChoice": "AcceptOrReject",
  "DeliverySignMethod": "EmailPin",
  "PushNotificationUrl": "https://your-endpoint.example.com/callbacks/evinotice",
  "PushNotificationFilter": ["Delivered", "Read", "Replied", "Closed", "AffidavitPublished"],
  "AffidavitKinds": ["Submitted", "Dispatched", "DeliveryResult", "Read", "Committed", "Closed"]
}
```

**Example response (`200 OK`):**

```json
{
  "Id": "9f3e1a02-b74c-4d8e-91c5-f00012345678"
}
```

### Get a single EviNotice

```
GET /v2/EviNotice/{Id}
```

Retrieves the full details of a specific EviNotice by its UUID. Optionally includes affidavit and attachment metadata.

**Path parameters:**

| Parameter | Type | Description |
|  --- | --- | --- |
| `Id` | UUID | The unique ID returned at submission. |


**Query parameters:**

| Parameter | Type | Description |
|  --- | --- | --- |
| `IncludeAffidavits` | boolean | Include affidavit metadata in the response. |
| `IncludeAttachments` | boolean | Include attachment metadata in the response. |


| Response | Description |
|  --- | --- |
| `200 OK` | Returns the full EviNotice object, extending `EviNoticeSummary` with `SiteName`, `XmissionResult`, `XmissionSummary`, `CustomLayoutLogoUrl`, and the `Affidavits` and `Attachments` arrays (the latter two present when `IncludeAffidavits` / `IncludeAttachments` are set). |
| `400 Bad Request` | Invalid request. |
| `401 Unauthorized` | Authentication failed. |
| `404 Not Found` | EviNotice not found. |


### Query multiple EviNotices

```
POST /v2/EviNotice/Query
```

Returns a paginated list of EviNotices matching the specified filters. Unlike EviMail and EviSMS, this query endpoint uses a POST request body. Pagination uses a cursor returned in the response.

Without `Owner`, site-level users see their site's notices and other users see only their own. Drafts are not returned.

`Closed` is the only terminal state for a submitted notice. Use `Outcome` at closure to decide the final result. See the [complete list of outcomes at closure](#final-outcomes).

**Request body (all fields optional):**

| Field | Type | Description |
|  --- | --- | --- |
| `Limit` | integer | Maximum results to return (1–100, default 100). |
| `Owner` | string (email) | Site-level users may filter by a valid owner email (400 if invalid); other users receive 403 when supplying Owner. |
| `LookupKeys` | array | Filter by one or more lookup keys. |
| `LinkedId` | UUID | Filter by linked ID. |
| `State` | string | Filter by current state. |
| `Outcome` | string | Filter by outcome. Use `None` to find open notices or a final outcome value to find closed notices with that result. |
| `Cursor` | string | Cursor from a previous response, for pagination. |


| Response | Description |
|  --- | --- |
| `200 OK` | Returns `{ "Cursor": "...", "Results": [...] }`. Pass `Cursor` in the next request to retrieve the following page. |
| `401 Unauthorized` | Authentication failed. |
| `400 Bad Request` | Invalid Query field, Owner email or limit. |
| `403 Forbidden` | Owner filtering is not permitted for this user. |


The query response also uses PascalCase: `Cursor` and `Results` rather than the camelCase `totalMatches` and `results` returned by the EviMail and EviSMS v1 query endpoints. Deserialise accordingly if sharing response models across services.

**Example result after link access and closure (abbreviated)**

```json
{
  "Results": [
    {
      "Id": "550e8400-e29b-41d4-a716-446655440000",
      "State": "Closed",
      "Outcome": "Received",
      "ReceivedOn": "2026-01-15T10:00:00Z",
      "ExpiredOn": "2026-01-16T09:00:20Z"
    }
  ]
}
```

Here, the platform recorded access to the hosted notice link before tracking ended. Use `ReadOn` to determine whether the platform recorded the hosted content being shown.

### Download all attachments

```
GET /v2/EviNotice/{Id}/Attachments
```

Downloads all attachments of a specific EviNotice as a single ZIP file.

**Path parameters:**

| Parameter | Type | Description |
|  --- | --- | --- |
| `Id` | UUID | The unique ID of the EviNotice. |


| Response | Description |
|  --- | --- |
| `200 OK` | ZIP file (`application/zip`) containing all attachments. |
| `204 No Content` | The EviNotice exists but has no attachments. |
| `401 Unauthorized` | Authentication failed. |
| `404 Not Found` | EviNotice not found. |


### Download all affidavits

```
GET /v2/EviNotice/{Id}/Affidavits
```

Downloads all affidavits of a specific EviNotice as a single ZIP file.

**Path parameters:**

| Parameter | Type | Description |
|  --- | --- | --- |
| `Id` | UUID | The unique ID of the EviNotice. |


| Response | Description |
|  --- | --- |
| `200 OK` | ZIP file (`application/zip`) containing all affidavits. |
| `204 No Content` | The EviNotice exists but no affidavits have been generated yet. |
| `401 Unauthorized` | Authentication failed. |
| `403 Forbidden` | Notice not found or not accessible to this account. |


### Download one affidavit

```
GET /v2/EviNotice/Affidavits/{Id}
```

Downloads a single EviNotice affidavit PDF by affidavit ID.

**Path parameters:**

| Parameter | Type | Description |
|  --- | --- | --- |
| `Id` | UUID | The unique ID of the affidavit. |


| Response | Description |
|  --- | --- |
| `200 OK` | PDF file (`application/pdf`) for the requested affidavit. |
| `401 Unauthorized` | Authentication failed. |
| `404 Not Found` | Affidavit not found. |
| `403 Forbidden` | The affidavit belongs to a notice this account cannot access. |


### Request an on-demand affidavit

```
POST /v2/EviNotice/Affidavits/Request
```

Generates a custom affidavit for a previously submitted EviNotice. To use this endpoint, the original submit request must have included `AffidavitKinds` with the `OnDemand` value. The notice must still be eligible.

Requests are rejected when the notice is `Draft` or `Closed`, when `OnDemand` was not included in `AffidavitKinds` at submission, or when the configured per-notice on-demand affidavit limit has been reached.

**Request body:**

| Field | Type | Description |
|  --- | --- | --- |
| `Id` | string (UUID) | Required. The unique ID of the EviNotice returned at submission. |
| `IncludeBody` | boolean | Optional. Include the notice body in the affidavit. |
| `IncludeAttachments` | boolean | Optional. Include notice attachments in the affidavit. Attachments must have been submitted with `IncludeOnAffidavits: true`. |
| `IncludeEvents` | boolean | Optional. Include detailed event information in the affidavit. |


| Response | Description |
|  --- | --- |
| `200 OK` | Returns `{ "RequestId": "<uuid>" }`. The affidavit is generated asynchronously; you receive an `AffidavitPublished` callback when it is ready. |
| `401 Unauthorized` | Authentication failed. |
| `403 Forbidden` | The per-notice on-demand affidavit limit has been reached. |
| `405 Method Not Allowed` | `OnDemand` was not included in `AffidavitKinds` at submission, or the notice is in a state that does not support on-demand affidavit generation (`Draft` or `Closed`). |
| `404 Not Found` | Notice not found among those submitted by this user. |


## Batch operations

Batch operations let you send the same certified notice to many recipients as a single managed job. The typical workflow is:

1. **Create** an empty batch with a `Description` — you receive a `BatchId`.
2. **Set the body** (`PUT .../Body`) — the HTML notice content.
3. **Add recipients** (`POST .../Recipients`) — uploaded as a `text/csv` file.
4. *(Optional)* **Add attachments** (`POST .../Attachments`) — uploaded as `multipart/form-data`.
5. **Configure options** (`PATCH .../{BatchId}`) — certification level, commitment, callbacks, scheduling, and so on. Also set the `Subject` here.
6. **Start processing** by setting the batch `State` (via `PATCH`) once the batch is ready.


Poll `GET .../{BatchId}` to follow progress (`SentCount`, `FailedCount`, `ProgressPercentage`). Batch lifecycle states are `Draft`, `Submitted`, `Scheduled`, `Processing`, `Processed`, `Invalid`, and `Failed`.

:::note HTTP QUERY method
The two list endpoints (**Query batches** and **Query batch recipients**) are implemented with the HTTP `QUERY` method and accept their filters in a JSON request body. Because OpenAPI cannot express the `QUERY` method, they are documented as `GET` with the filter fields shown as query parameters. In practice, send the request with the HTTP `QUERY` verb and the fields in a JSON body.
:::

### Create a notice batch

```
POST /v2/EviNotice/Batches
```

Creates a new, empty batch. Only `Description` is required; the body, recipients, attachments, and options are set with the subsequent batch endpoints.

**Request body:**

| Field | Type | Description |
|  --- | --- | --- |
| `Description` | string | Required. Human-readable batch description (max 255 chars). |


| Response | Description |
|  --- | --- |
| `201 Created` | Returns `{ "BatchId": "<uuid>" }`. |
| `401 Unauthorized` | Authentication failed. |
| `403 Forbidden` | Batch sending is unavailable for this user or site. |


**Example response:**

```json
{
  "BatchId": "550e8400-e29b-41d4-a716-446655440000"
}
```

### Query notice batches

```
QUERY /v2/EviNotice/Batches
```

Lists notice batches owned by the caller (or the caller's site), with cursor pagination. Filters are sent in a JSON request body.

**Request body:**

| Field | Type | Description |
|  --- | --- | --- |
| `States` | array | Filter by one or more batch states. |
| `Cursor` | string | Cursor from a previous response, for pagination. |
| `Limit` | integer | Required. Maximum batches to return (1–100). |
| `SortBy` | string | `LastUpdated` (default), `ScheduledFor`, or `StartedOn`. |
| `SortOrder` | string | `Ascending` (default) or `Descending`. |
| `Direction` | string | `Forward` (default) or `Backward`. |
| `TextSearch` | string | Free-text search over batch descriptions. |


| Response | Description |
|  --- | --- |
| `200 OK` | Returns `{ "Cursor": "...", "HasMoreResults": bool, "Results": [...] }`. |
| `400 Bad Request` | Malformed request (invalid state, sort, or direction value). |
| `401 Unauthorized` | Authentication failed. |


### Get a notice batch

```
GET /v2/EviNotice/Batches/{BatchId}
```

Retrieves the full state of a batch, including its configured notice template and processing progress (`SentCount`, `FailedCount`, `ProgressPercentage`).

**Path parameters:**

| Parameter | Type | Description |
|  --- | --- | --- |
| `BatchId` | UUID | The unique ID returned at batch creation. |


| Response | Description |
|  --- | --- |
| `200 OK` | Returns the full batch object, including the nested `EviNotice` template. |
| `400 Bad Request` | `BatchId` is missing or a default (empty) UUID. |
| `401 Unauthorized` | Authentication failed. |
| `404 Not Found` | No batch with the given `BatchId` was found. |


### Update a notice batch

```
PATCH /v2/EviNotice/Batches/{BatchId}
```

Updates batch metadata and the notice template options. All fields are optional; only the fields supplied are changed. Setting `State` transitions the batch (for example, to `Submitted` to start processing). Setting `ScheduledDate` schedules the batch for later dispatch.

Batch scheduling uses **UTC**. Specify `ScheduledDate` in UTC when scheduling a batch.

**Request body (all fields optional):** `IssuerName`, `Subject`, `ScheduledDate`, `State`, `Description`, `From`, `DisableSenderHeader`, `ReplyTo`, `TimeToLive`, `CostCentre`, `CertificationLevel`, `AffidavitKinds`, `Language`, `AffidavitLanguage`, `OnlineRetentionPeriod`, `LtaStorage`, `PushNotificationUrl`, `PushNotificationFilter`, `PushNotificationExtraData`, `CommitmentOptions`, `CommitmentCommentsAllowed`, `RejectReasons`, `AcceptReasons`, `RequireRejectReason`, `RequireAcceptReason`, `DeliveryAppearance`, `BatchPushNotificationUrl`, `AllowRefusal`, `OwnerNotificationTemplate`, `Channel`.

| Response | Description |
|  --- | --- |
| `200 OK` | Batch updated. |
| `400 Bad Request` | Invalid request. |
| `401 Unauthorized` | Authentication failed. |
| `404 Not Found` | No batch with the given `BatchId` was found. |


**Example request:**

```json
{
  "Subject": "Important notice regarding your account",
  "IssuerName": "Sender Co.",
  "CertificationLevel": "Advanced_EU",
  "Language": "en",
  "State": "Submitted"
}
```

### Delete a notice batch

```
DELETE /v2/EviNotice/Batches/{BatchId}
```

Removes a previously created batch.

| Response | Description |
|  --- | --- |
| `204 No Content` | Batch deleted. |
| `401 Unauthorized` | Authentication failed. |
| `404 Not Found` | No batch with the given `BatchId` was found. |


### Set the batch body

```
PUT /v2/EviNotice/Batches/{BatchId}/Body
```

Sets the HTML body of the notice for this batch. The body is sent as the raw request payload with `Content-Type: text/html`, not as a JSON field. Set the `Subject` with `PATCH .../{BatchId}`.

| Response | Description |
|  --- | --- |
| `202 Accepted` | Body accepted and queued for update. Poll `GET .../{BatchId}` to check status. |
| `400 Bad Request` | The request has no valid body. |
| `401 Unauthorized` | Authentication failed. |
| `404 Not Found` | No batch with the given `BatchId` was found. |


### Add batch recipients

```
POST /v2/EviNotice/Batches/{BatchId}/Recipients
```

Adds recipients by uploading a `text/csv` file (`Content-Type: text/csv`). The CSV uses `;` as the column separator.

- **Mandatory columns:** `address`, `legalname`
- **Optional columns:** `lookupkey`, `displayname`, `custodychallenge`, `custodychallengeresponse`, `deliverychallenge`, `deliverychallengeresponse`, `deliveryotpchannel`, `deliveryotpaddress`
- **Custom fields:** add extra columns prefixed with `*` (for example, `*orderid`); they are surfaced per recipient as `ExtraFields`.


**Example request body:**

```
address;legalname;displayname;*orderid
jane@example.com;Acme Corp;Jane Doe;ORD-001
john@example.com;Beta Ltd;John Roe;ORD-002
```

| Response | Description |
|  --- | --- |
| `200 OK` | Recipients accepted. No response body is returned. |
| `400 Bad Request` | Invalid CSV (duplicated columns, missing mandatory columns, invalid custom-column names, empty file or too many recipients), missing body, incorrect `Content-Type` or `Content-Encoding`, or a batch that can no longer be modified. |
| `401 Unauthorized` | Authentication failed. |
| `404 Not Found` | No batch with the given `BatchId` was found. |


### Query batch recipients

```
QUERY /v2/EviNotice/Batches/{BatchId}/Recipients
```

Lists the recipients of a batch, with cursor pagination. Filters are sent in a JSON request body.

**Request body:**

| Field | Type | Description |
|  --- | --- | --- |
| `Cursor` | string | Cursor from a previous response, for pagination. |
| `Limit` | integer | Maximum recipients to return (1–1000). |
| `SortDirection` | string | `Ascending` or `Descending`. |


| Response | Description |
|  --- | --- |
| `200 OK` | Returns `{ "Cursor": "...", "Results": [...] }`. Each result includes the recipient fields and, once processed, the `EvidenceUniqueId` of the generated notice. |
| `400 Bad Request` | Malformed request. |
| `401 Unauthorized` | Authentication failed. |
| `404 Not Found` | No batch with the given `BatchId` was found. |


### Delete all batch recipients

```
DELETE /v2/EviNotice/Batches/{BatchId}/Recipients
```

Removes all recipients from the batch.

| Response | Description |
|  --- | --- |
| `204 No Content` | Recipients removed. |
| `401 Unauthorized` | Authentication failed. |
| `404 Not Found` | No batch with the given `BatchId` was found. |


### Add a batch attachment

```
POST /v2/EviNotice/Batches/{BatchId}/Attachments
```

Adds a single attachment as `multipart/form-data`. The attachment is included in every notice generated from the batch. Send the file in the `Content` part; the remaining metadata fields (`DisplayName`, `Filename`, `ContentId`, `MimeType`, `ContentDescription`, `ContentDisposition`, `ContentLocation`, `ContentEncoding`, `IncludeOnAffidavits`) are optional form fields.

| Response | Description |
|  --- | --- |
| `200 OK` | Returns `{ "AttachmentId": "<uuid>" }`. |
| `400 Bad Request` | No file was supplied, or more than one file was supplied. |
| `401 Unauthorized` | Authentication failed. |
| `404 Not Found` | No batch with the given `BatchId` was found. |


### List batch attachments

```
GET /v2/EviNotice/Batches/{BatchId}/Attachments
```

Returns metadata for all attachments configured on the batch.

| Response | Description |
|  --- | --- |
| `200 OK` | Returns an array of attachment metadata (`Id`, `DisplayName`, `FileName`, `MimeType`, `Size`, `ContentEncoding`, `ContentId`). |
| `401 Unauthorized` | Authentication failed. |
| `404 Not Found` | No batch with the given `BatchId` was found. |


### Delete all batch attachments

```
DELETE /v2/EviNotice/Batches/{BatchId}/Attachments
```

Removes all attachments from the batch.

| Response | Description |
|  --- | --- |
| `204 No Content` | Attachments removed. |
| `401 Unauthorized` | Authentication failed. |
| `404 Not Found` | No batch with the given `BatchId` was found. |


### Download a batch attachment

```
GET /v2/EviNotice/Batches/{BatchId}/Attachments/{AttachmentId}
```

Downloads the binary content of a single batch attachment.

| Response | Description |
|  --- | --- |
| `200 OK` | Attachment content (`application/octet-stream`). |
| `401 Unauthorized` | Authentication failed. |
| `404 Not Found` | No attachment or batch with the given IDs was found. |


### Delete a batch attachment

```
DELETE /v2/EviNotice/Batches/{BatchId}/Attachments/{AttachmentId}
```

Removes a single attachment from the batch.

| Response | Description |
|  --- | --- |
| `204 No Content` | Attachment removed. |
| `401 Unauthorized` | Authentication failed. |
| `404 Not Found` | No attachment or batch with the given IDs was found. |


## States and outcomes

For a cross-service explanation of lifecycle terminology, see [States and outcomes](/products/namirialnotify/user-guides/states-outcomes). For a visual lifecycle reference, see the [EviNotice evidence lifecycle](/products/namirialnotify/user-guides/states-outcomes#evinotice-evidence-lifecycle).

**States** represent the current step in the notice lifecycle.

| State | Description |
|  --- | --- |
| `Draft` | Notice has been staged but not yet submitted. |
| `Submitted` | Notice has been accepted by the platform. |
| `Processed` | Initial processing and content certification completed; the notification is ready for a send request. |
| `Dispatched` | The platform completed its initial checks, accepted responsibility for the communication and issued the notification send request; successful transmission has not yet been confirmed. |
| `Sent` | The selected sending channel reported successful transmission of the notification. |
| `Delivered` | A best-effort delivery signal was received for the notification; this does not establish that the hosted content was opened. |
| `Received` | Recipient followed the hosted notice link (before reading the content). |
| `Read` | Recipient opened and read the hosted notice. |
| `Replied` | Recipient accepted or rejected the notice. |
| `Closed` | The only terminal state. Use `Outcome` for the final result. Callbacks for requested affidavits can still arrive afterwards. |
| `Failed` | A processing, transmission or delivery failure occurred. It is not final by itself: wait for `Closed` and inspect `Outcome`. Initial processing failures close immediately; other failures can recover while the notice remains open. |


### Final outcomes 

At closure, the platform selects the first outcome in the table whose milestone is recorded. An unrecovered failure takes priority over all other milestones.

| Outcome | Meaning at closure |
|  --- | --- |
| `Failed` | A processing, transmission, or delivery failure remained recorded at closure. An administrative forced closure also records `Failed`. |
| `Rejected` | The recipient explicitly rejected the hosted notice in the commitment step. |
| `Accepted` | The recipient explicitly accepted the hosted notice in the commitment step. |
| `Refused` | The recipient explicitly refused the notice from the hosted landing page before opening the content. |
| `Read` | The platform recorded that the recipient opened the hosted content, after any required identification or validation. |
| `Received` | The platform recorded access to the hosted notice link. The content opening milestone is `Read`. |
| `Delivered` | The platform recorded a delivery signal for the notification. The hosted notice link and content have their own milestones. |
| `Sent` | The sending channel reported successful transmission of the notification. |
| `Certified` | Initial processing completed, and this was the highest-priority milestone recorded at closure. |


While the notice is open, `Outcome` is `None`. The API response enum also includes `Cancelled` for compatibility. The current EviNotice lifecycle does not produce it, and Query rejects it as an outcome filter. If you encounter an unexpected outcome on a closed notice, keep the value and contact support. Closing when `TimeToLive` elapses uses the same outcome rules.

The recipient can refuse on the hosted landing page after following the secure link, without opening the content. The landing-page visit normally records `Received` before refusal. The events are processed asynchronously: `ReceivedOn` and the `Received` callback can be missing if refusal is processed first, and callback arrival order is not guaranteed. Refusal closes the notice; inspect the final `Outcome` in `Closed`. It is normally `Refused`, but an unrecovered failure takes precedence and can produce `Outcome: Failed`. `Refused` is an outcome and a `RefusedOn` timestamp, rather than a separate lifecycle state.

## Key request fields

### API defaults and WebUI preferences

Site and user **WebDefaults** prefill the WebUI send form. API submissions use the defaults defined for each API field instead of inheriting those form preferences. Supply explicit values for settings your integration depends on, so a user changing WebUI preferences does not change its submissions.

| Omitted API field | Default |
|  --- | --- |
| `Language` | `en` |
| `AffidavitLanguage` | `en` |
| `TimeToLive` | Platform-configured TTL default |
| `OnlineRetentionPeriod` | Platform-configured online-retention default |
| `DeliverySignMethod` | Platform-configured delivery-sign default |
| `EvidenceAccessControlMethod` | Platform-configured custody-access default |
| `NotificationLayout` | `Certified` |
| `CommitmentChoice` | `Disabled` |
| `CommitmentCommentsAllowed` | `false` |
| `CertificationLevel` | Determined by platform configuration: either `Advanced` or the default configured for your account (not the WebUI site or user default). Set it explicitly when your integration requires a specific level. |


Account permissions and platform configuration still apply; certification-level availability can depend on service configuration.

### `RecipientAddress`

The recipient's email address or mobile phone number in E.164 format. The delivery notification is sent to this address. The certified content is hosted on Namirial Notify.

### `CertificationLevel`

Defines the legal framework and geographic variant for certification. The API accepts `Standard`, `Advanced`, `QERDS`, their regional `Standard_*` and `Advanced_*` variants, and QeRDS country variants such as `QERDS_ES` and `QERDS_IT`. Availability depends on the account. See [Certification levels](/products/namirialnotify/user-guides/certification-levels) for the full list.

### `TimeToLive`

The time in minutes during which the platform will attempt delivery before the notice expires. Range: 60–86,400 (1 hour to 60 days). When omitted, the platform's configured TTL default applies, independently of the WebUI send-form default.

### `EnforceTrackingUntilTimeToLive`

When `true`, the platform keeps tracking recipient attachment downloads until `TimeToLive` elapses. This option must be used together with the `ContentDownload` affidavit kind. Submitting `ContentDownload` without `EnforceTrackingUntilTimeToLive: true`, or enabling `EnforceTrackingUntilTimeToLive` without `ContentDownload`, returns a validation error.

### `DeliverySignMethod`

Controls how the recipient accesses the hosted notice. Supported values: `WebClick`, `Challenge`, `MobilePin`, `EmailPin`.

### `CommitmentChoice`

Controls whether the recipient can accept or reject the notice. Supported values: `Disabled`, `Accept`, `Reject`, `AcceptOrReject`. EviMail exposes the same behaviour through a field named `CommitmentOptions`.

For QeRDS, keep `CommitmentCommentsAllowed` disabled when acceptance is available (`Accept` or `AcceptOrReject`). To collect recipient comments or rejection reasons, use `CommitmentChoice: Reject` with `CommitmentCommentsAllowed: true`. Do not configure `AcceptReasons` or enable `RequireAcceptReason` for QeRDS acceptance.

### `PushNotificationFilter`

An array of state names that trigger a callback to `PushNotificationUrl`. Valid values for EviNotice: `Processed`, `Dispatched`, `Sent`, `Delivered`, `Received`, `Read`, `Replied`, `Failed`, `Closed`, `AffidavitPublished`.

Note that `Received` is specific to EviNotice — it fires when the recipient follows the hosted notice link, before they read the content.

`AffidavitPublished` is not a lifecycle state — it is a platform meta-event that fires when affidavit generation for this notice completes.

Supply `PushNotificationUrl` and `PushNotificationFilter` together. `PushNotificationExtraData` (up to 1,024 characters) is allowed only with both; otherwise Submit returns `400`.

### `AffidavitKinds`

Selects the kinds of affidavits to generate when the corresponding events occur: `Submitted`, `SubmittedAdvanced`, `Dispatched`, `TransmissionResult`, `DeliveryResult`, `Received`, `Read`, `Committed`, `CommittedAdvanced`, `Refused`, `Closed`, `ClosedAdvanced`, `Event`, `Complete`, `CompleteAdvanced`, `OnDemand`, `ContentDownload`.

A failure before processing completes closes the notice without generating affidavits. Later transmission and delivery failures can be certified by `TransmissionResult` and `DeliveryResult` when requested. The request contract also accepts `Failed`, but the notice lifecycle does not generate a separate `Failed` affidavit. See [generation conditions](/products/namirialnotify/services/evinotice#when-each-affidavit-is-generated).

For every qualified notice, `AffidavitKinds` must include both `SubmittedAdvanced` and `Read`, or include `CompleteAdvanced`. Other kinds may be added; the ordinary `Submitted` kind does not satisfy this qualified requirement.

`ContentDownload` must be paired with `EnforceTrackingUntilTimeToLive: true`; see [`EnforceTrackingUntilTimeToLive`](#enforcetrackinguntiltimetolive).

### `EvidenceAccessControlMethod`

Controls access to the notice and its evidence once the recipient has accepted or rejected it, or the notice has closed. This is separate from `DeliverySignMethod`, which protects first access. `Public` allows anyone with the link; `Challenge` asks the issuer's question; `AutoChallenge` asks the visitor to enter the recipient's email address or phone number.

Supply both `EvidenceAccessControlChallenge` and `EvidenceAccessControlChallengeResponse` only with `Challenge`; they are required for that method and rejected with other methods.

Unlike EviMail and EviSMS, `Default` is not a supported value for EviNotice. Omitting this field uses the platform-configured custody-access default; specify a supported value explicitly when your integration requires a particular method. For QeRDS, set `EvidenceAccessControlMethod: Public` explicitly rather than relying on that default. This evidence-access rule is separate from the recipient identification required to read the hosted notice.

### `NotificationLayout`

Controls the visual layout of the hosted notice. Supported values: `Certified`, `AsIs`. EviMail exposes the same concept through a field named `DeliveryAppearance`.

### `Attachments`

An array of files included in the hosted notice. `Data` is required and is always base64-encoded in JSON. Supply `MimeType`, or a `Filename` whose extension lets the platform derive the MIME type. If `MimeType` is omitted, it is derived from the `Filename` extension. Use `ContentId` to reference an attachment inline in the `Body` HTML, and `IncludeOnAffidavits` to control whether the attachment is referenced in generated affidavits. Setting it to `true` requires a PDF attachment (`MimeType` `application/pdf`, supplied or derived from `Filename`), version 1.7 or earlier, that passes PDF validation, and a non-empty `AffidavitKinds`; otherwise Submit returns `400`.

For `POST /v2/EviNotice/Submit`, the current API accepts at most **14 attachments**. Each file must be **smaller than 8 MiB** (8,388,608 bytes); the combined decoded file size must be **at most 25 MiB** (26,214,400 bytes). These limits apply to file bytes before base64 encoding. The complete base64-encoded JSON request must also fit within the API host's request-size limit. A request approaching the combined decoded-file limit can be rejected before attachment validation.

## OpenAPI specification

The OpenAPI 3.0.3 specification for the EviNotice API provides a machine-readable definition of the service endpoints, request and response schemas, authentication method, and error responses.

**Covered in the specification:**

- **Submit endpoint** (`POST /v2/EviNotice/Submit`) — detailed request and response schemas, certification options, delivery methods, commitment workflows, and HTTP status codes
- **Get endpoint** (`GET /v2/EviNotice/{Id}`) — retrieval of individual notices with optional affidavit and attachment metadata
- **Query endpoint** (`POST /v2/EviNotice/Query`) — cursor-based pagination, filtering by state or outcome, and result structure
- **Attachments endpoint** (`GET /v2/EviNotice/{Id}/Attachments`) — bulk download of notice attachments as ZIP
- **Affidavits endpoint** (`GET /v2/EviNotice/{Id}/Affidavits`) — bulk download of generated affidavits as ZIP
- **Single affidavit endpoint** (`GET /v2/EviNotice/Affidavits/{Id}`) — download one generated affidavit as PDF
- **Batch endpoints** (`/v2/EviNotice/Batches`) — all 14 operations for batch creation, queries, configuration, deletion, body, recipients, and attachments
- **Authentication** — HTTP Basic authentication requirements
- **Error handling** — Problem+JSON error responses with detailed diagnostic information
- **Data types** — schema definitions for documented notices, recipients, attachments, affidavits, and lifecycle states


The OpenAPI spec can be used to generate client libraries, integration tests, or interactive API documentation.

[View OpenAPI spec →](/products/namirialnotify/apis/oas/evinotice-api)

## Related

- [EviNotice](/products/namirialnotify/services/evinotice)
- [EviMail API](/products/namirialnotify/apis/evimail-api)
- [EviSMS API](/products/namirialnotify/apis/evisms-api)
- [EviPost API](/products/namirialnotify/apis/evipost-api)
- [API reference overview](/products/namirialnotify/apis/overview)
- [Callbacks and webhooks](/products/namirialnotify/dev/callbacks)
- [Error handling](/products/namirialnotify/dev/error-handling)
- [Integration workflows](/products/namirialnotify/dev/integration-patterns)
- [Security and authentication](/products/namirialnotify/dev/security-best-practices)
- [States and outcomes](/products/namirialnotify/user-guides/states-outcomes)
- [Evidence and affidavits](/products/namirialnotify/user-guides/evidences-affidavits)