# EviNotice

EviNotice is the Namirial Notify certified hosted notice service. When you submit a notice, Namirial Notify sends a delivery notification to the recipient via email, SMS, RCS, or WhatsApp, and hosts the certified content on a secure platform page. Every step — delivery, access, reading, acceptance, rejection, or refusal — is recorded as evidence and optionally generates a signed affidavit.

For the API reference, see the [EviNotice API](/products/namirialnotify/apis/evinotice-api).

## When to use EviNotice

Use EviNotice when:

- **You need controlled access to the content** — the recipient must authenticate before reading, using a challenge question, a mobile PIN, or an email PIN.
- **You need acceptance or rejection on record** — the recipient can explicitly accept, reject, or refuse the notice, generating legally binding evidence of their decision.
- **You need to certify what the recipient saw** — the notice content is hosted on Namirial Notify and certified there, so the evidence covers both delivery of the notification and the recipient's interaction with the content.
- **You need recipient identity verification** — QERDS-level certifications can require government-issued identity verification before the recipient can read the notice.


Use [EviMail](/products/namirialnotify/services/evimail) instead when the certified content should arrive directly in the recipient's inbox without requiring them to follow a link. Use [EviSMS](/products/namirialnotify/services/evisms) when the certified communication is the SMS message itself rather than a hosted document.

## How the pieces fit together

An EviNotice involves two distinct layers:

1. **The notification channel** — how the platform alerts the recipient. This can be email, SMS, RCS, or WhatsApp. The notification contains a secure link to the hosted notice.
2. **The hosted notice** — the actual certified content, living on Namirial Notify. The recipient clicks through to read it, and all on-platform interactions are recorded as evidence.


This separation is why EviNotice has more lifecycle states than EviMail or EviSMS: `Delivered` refers to the notification reaching the recipient's device; `Received` refers to the recipient following the link; `Read` refers to the recipient opening the content on the platform.


```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#E4F2F2', 'primaryBorderColor': '#006660', 'primaryTextColor': '#0A1111', 'lineColor': '#047C76', 'secondaryColor': '#CDDBDB', 'tertiaryColor': '#f5fafa', 'edgeLabelBackground': '#f5fafa', 'transitionColor': '#047C76'}}}%%
flowchart LR
    A[Your system] -->|Submit| B[Namirial Notify]
    B -->|"Notification<br/>email / SMS / RCS / WhatsApp"| C[Recipient]
    C -->|Clicks secure link| D[Hosted notice page]
    D -->|Reads, accepts, rejects, or refuses| E[Evidence chain]
    E --> F[Affidavits]
```

## How EviNotice works

### Lifecycle overview


```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#E4F2F2', 'primaryBorderColor': '#006660', 'primaryTextColor': '#0A1111', 'lineColor': '#047C76', 'secondaryColor': '#CDDBDB', 'tertiaryColor': '#f5fafa', 'edgeLabelBackground': '#f5fafa', 'transitionColor': '#047C76'}}}%%
stateDiagram-v2
    [*] --> Submitted : Submit accepted
    Submitted --> Processed : Validation passed, content certified
    Submitted --> Failed : Invalid attachment
    Processed --> Dispatched : Notification queued for dispatch
    Dispatched --> Sent : Delivery channel accepted the notification
    Sent --> Delivered : Delivery confirmation received
    Delivered --> Received : Recipient follows hosted notice link
    Received --> Read : Recipient opens notice content
    Read --> Replied : Recipient accepts or rejects
    Read --> Closed : Lifecycle complete (no commitment configured)
    Replied --> Closed : Lifecycle complete
    Dispatched --> Closed : Refused without opening
    Sent --> Closed : Refused without opening
    Delivered --> Closed : Refused without opening
    Received --> Closed : Refused without opening
    Sent --> Closed : TimeToLive elapsed
    Failed --> Closed : Closed after failure
```

`State: Failed` is recoverable and does not make the notice final. Wait for `Closed` and inspect the final `Outcome`; permanent failure is represented by `Outcome: Failed`.

### Key state transitions

**Submitted → Processed** — Namirial Notify validates the attachments, certifies the content, and prepares the notice for dispatch. If an attachment is invalid (corrupted or password-protected), the notice transitions directly to `Failed` then `Closed` without being dispatched.

**Processed → Dispatched → Sent** — Once processing is complete, `Dispatched` marks the point where the platform has run all its checks and accepted responsibility for the communication; the notification is not yet sent, so `DispatchedOn` typically matches `ProcessedOn` to the second. `Sent` is recorded once transmission is confirmed by the remote system, so `SentOn` is always equal to or later than `DispatchedOn`.

**Sent → Delivered** — A delivery confirmation is received from the channel. For email this is a delivery notification from the recipient's mail server; for SMS, RCS, and WhatsApp this is an operator acknowledgement.

**Delivered → Received** — The recipient clicks the secure link in the notification. This fires before the recipient has authenticated or read the content. `Received` is specific to EviNotice — it does not exist in EviMail or EviSMS.

**Received → Read** — The recipient completes any required authentication and opens the notice content on the hosted page.

**Read → Replied** — If commitment is configured, the recipient accepts or rejects the notice. When the lifecycle closes, the final outcome is `Accepted` or `Rejected`.

**Any state ≥ Dispatched → Closed (Refused)** — When `AllowRefusal` is enabled, the recipient can refuse the notice without opening the hosted content. The lifecycle ends immediately with outcome `Refused`.

**Comparing lifecycle timestamps**

When recorded, the `*On` timestamps in the Query response follow the lifecycle order above: `SubmittedOn` → `ProcessedOn` → `DispatchedOn` → `SentOn` → `DeliveredOn` → `ReceivedOn` → `ReadOn`. A milestone can be absent when the corresponding external signal was not received; for example, `ReceivedOn` or `ReadOn` can be present while `DeliveredOn` is absent. Note that `DispatchedOn` precedes `SentOn` — dispatch is the hand-off to the sending process, not acceptance by the remote system. Timestamps recorded within the same second come from independent processing steps and should not be order-compared.

## Submit a certified notice


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

Returns `{ "Id": "<uuid>" }` on success. Note that `Id` is PascalCase, unlike the camelCase `eviId` returned by EviMail and EviSMS v1 endpoints.

### Required fields

| Field | Description |
|  --- | --- |
| `Subject` | Subject line of the certified notice. Shown to the recipient in the delivery notification. |
| `Body` | HTML content of the hosted notice. This is the certified content the recipient reads on the platform. |
| `RecipientAddress` | Recipient's email address or mobile phone number in E.164 format. Determines the primary notification channel. |


For Standard and Advanced notices, the API requires only `Subject`, `Body`, and `RecipientAddress`. When you omit other fields, the platform applies site or account defaults — for example `Language` and `AffidavitLanguage` follow your site's configured language, and `TimeToLive` uses the account-configured value. QERDS notices have additional mandatory conditions; see [QERDS recipient identity](#qerds-recipient-identity).

### Useful fields you should configure

- **`LookupKey`** — your own correlation key, filterable in Query. No uniqueness enforced server-side — make it unique within your domain.
- **`IssuerLegalName`** — the legal name of the sending organisation, recorded in the certification evidence.
- **`RecipientDisplayName`** — the display name shown to the recipient in the delivery notification.
- **`RecipientLegalName`** — the legal name of the recipient, recorded in the evidence.
- **`CertificationLevel`** — the legal framework applied. Supported values include `Standard`, `Advanced`, `QERDS`, and regional variants such as `Standard_EU`, `Advanced_EU`, `QERDS_ES`, or `QERDS_IT`. Available levels depend on your account subscription — submitting an unsupported level returns `400`. See [Certification levels](/products/namirialnotify/user-guides/certification-levels) for the full list and QERDS profile details.
- **`TimeToLive`** — minutes the platform will attempt delivery and keep the notice accessible. Range: 60–86,400 (1 hour to 60 days). Defaults to the account-configured value when omitted.
- **`Language`** — language for the delivery notification and hosted notice UI. Accepted values: `ca`, `de`, `en`, `es`, `fr`, `it`, `pt`, `pt-BR`, `ro`.
- **`AffidavitLanguage`** — language for generated affidavit PDFs. Accepts `el` (Greek) in addition to the `Language` values.
- **`NotificationLayout`** — visual layout of the hosted notice page: `Certified` (default, Namirial Notify branded) or `AsIs` (plain, without certification branding). EviMail exposes the same concept through `DeliveryAppearance`.
- **`OnlineRetentionPeriod`** — number of years the notice and its evidence remain accessible online. Valid values depend on your subscription.
- **`LandingPageInfoText`** — additional text shown on the EviNotice landing page before the recipient opens the hosted content.


### Notification channels

`NotificationChannels` controls which channels are used to alert the recipient. Supported values: `SMS`, `WhatsApp`, `RCS`, `Email`.

When `RecipientAddress` is an email address, `Email` is the default channel. When it is a mobile number, `SMS` is the default. Use `NotificationChannels` to add or override channels.

### Recipient authentication

`DeliverySignMethod` controls how the recipient authenticates before accessing the hosted notice content.

| Value | How the recipient accesses the notice |
|  --- | --- |
| `WebClick` | No authentication is required by the sign method itself. The recipient clicks the link and accesses the notice directly unless another step such as captcha or QERDS legal-ID verification also applies. Lowest friction. |
| `Challenge` | A challenge question is shown before access. The recipient must provide the correct answer. Requires `DeliverySignChallenge` and `DeliverySignChallengeResponse`. |
| `MobilePin` | A one-time PIN is sent via `MobilePinChannels`. The recipient enters the PIN to access the notice. Set `DeliverySignFixedMobile` if the PIN delivery number differs from `RecipientAddress`. |
| `EmailPin` | A one-time PIN is sent to an email address. Set `DeliverySignFixedEmail` if the PIN delivery address differs from `RecipientAddress`. |


**`MobilePinChannels`** configures PIN delivery attempts as an array of arrays. Each outer element is one attempt; all channels in the inner array are tried simultaneously for that attempt:


```json
"MobilePinChannels": [
  ["SMS", "RCS", "WhatsApp"],
  ["SMS", "RCS", "WhatsApp"],
  ["SMS", "RCS", "WhatsApp"]
]
```

Supported channel values: `SMS`, `RCS`, `WhatsApp`.

### QERDS recipient identity

For QERDS-certified EviNotices, recipient legal-ID verification is required before the hosted notice is shown. QERDS submissions also require the issuer account and site to be provisioned for the QERDS API flow, including the required client-certificate or two-factor authentication configuration. Send QERDS API calls to the Namirial Notify API host for the environment, not to the customer's site host.

- **`RecipientLegalIdRequired`** — must be `true` for QERDS notices.
- **`RecipientLegalIdKind`** / **`RecipientLegalIdValue`** — optionally predefine the legal document type and value the recipient must confirm.
- **`QERDSEnrollmentAllowed`** — when `true`, recipients without a registered identity can complete enrollment during the same notice flow.
- **`QERDSEnrollmentProfile`** — selects the enrollment profile to use for in-flow registration.
- **`QERDSIdentityTenant`** — identifies the tenant or identity context used by the QERDS verification flow.


For `QERDS_ES`, the delivery sign method must match the recipient address channel: email recipients use `EmailPin` and mobile recipients use `MobilePin`, with the fixed PIN destination matching `RecipientAddress`.

For `QERDS_IT`, the issuer must have the `QERDS_IT` identity-verification schema enabled. Email recipients must use a mobile PIN destination (`DeliverySignMethod: MobilePin` plus `DeliverySignFixedMobile`), while mobile recipients must use an email PIN destination (`DeliverySignMethod: EmailPin` plus `DeliverySignFixedEmail`). `RecipientLegalIdKind` and `RecipientLegalIdValue` are required and must validate together.

If the recipient is not yet registered, the platform redirects them to the enrollment flow only when `QERDSEnrollmentAllowed` is enabled and the supplied `QERDSEnrollmentProfile` is configured on the site. Otherwise, access is blocked until the issuer resolves the identity requirement.

### Commitment and refusal

**`CommitmentChoice`** controls whether the recipient can accept or reject the notice. **Cannot be changed after submission.**

| Value | Effect |
|  --- | --- |
| `Disabled` | No commitment action. The recipient reads the notice but cannot accept or reject. |
| `Accept` | The recipient can only accept. |
| `Reject` | The recipient can only reject. |
| `AcceptOrReject` | The recipient can accept or reject. |


Additional commitment fields:

- **`CommitmentCommentsAllowed`** — when `true`, the recipient can add a free-text comment with their decision.
- **`AcceptReasons`** / **`RejectReasons`** — predefined reasons the recipient can select from.
- **`RequireAcceptReason`** / **`RequireRejectReason`** — force the recipient to select or enter a reason before committing.


EviMail and EviSMS expose the same concept through a field named `CommitmentOptions`.

**`AllowRefusal`** is separate from commitment. When `true`, the recipient can refuse the notice without opening the hosted content after following the secure link. In standard non-QERDS flows, refusal is presented on the landing step before the content is shown. Refusal closes the notice immediately with outcome `Refused` and generates a `Refused` affidavit if `Refused` is included in `AffidavitKinds`.

### Affidavit configuration

`AffidavitKinds` selects which evidence events generate affidavits. For the full catalog and the lifecycle moment each kind is tied to, see [Evidence and affidavits](#evidence-and-affidavits).

### Callbacks

- **`PushNotificationUrl`** — HTTPS endpoint to receive state callbacks. Must be publicly reachable from Namirial Notify infrastructure.
- **`PushNotificationFilter`** — state transitions that trigger a callback. Valid values: `Processed`, `Dispatched`, `Sent`, `Delivered`, `Received`, `Read`, `Replied`, `Failed`, `Closed`, `AffidavitPublished`. `AffidavitPublished` is a platform meta-event that fires when affidavit generation completes — it is not a lifecycle state. `Received` is unique to EviNotice.
- **`PushNotificationExtraData`** — arbitrary string echoed back in every callback for this notice. Use it to embed a routing key or internal record ID so your callback handler can route the event without a separate lookup.


### Idempotency

Include `X-Evi-IdempotencyToken` on every Submit. Use a UUID and keep it constant across retries. A replay of a previously `200 OK` submission returns `202 Accepted`; the notice is not resubmitted.

### Attachments

Include files in the hosted notice via the `Attachments` array. Each attachment requires `Filename`, `MimeType`, and base64-encoded `Data`.

Limits: maximum 15 attachments per submission; maximum 8 MB per attachment; maximum 25 MB total across all attachments.

Use `ContentId` to reference an attachment inline in the `Body` HTML using `cid:` syntax. Set `IncludeOnAffidavits: true` to include the attachment reference in generated affidavits.

### Reminders

EviNotice supports automatic reminder notifications sent to the recipient if the notice has not been acted on. Configure via the `Reminders` object:

| Field | Description |
|  --- | --- |
| `Initial` | ISO 8601 duration after submission before the first reminder fires (e.g. `P2D` = 2 days). |
| `Repeat` | ISO 8601 duration between subsequent reminders (e.g. `P1D` = daily). |
| `Days` | Days of the week on which reminders may be sent. |
| `TimeRange` | Time-of-day windows: `FROM08TO10`, `FROM10TO12`, `FROM12TO15`, `FROM15TO19`. |
| `Max` | Maximum total reminders to send. |
| `Stop` | ISO 8601 duration after submission beyond which no further reminders fire (e.g. `P15D`). |
| `TimeZone` | IANA time zone identifier used to interpret `Days` and `TimeRange`. |


## What the recipient sees

The recipient's experience depends on the configured `DeliverySignMethod`.

### WebClick

The recipient receives a notification (email, SMS, RCS, or WhatsApp) containing a secure link. Clicking the link opens the hosted notice page directly when no additional access step is configured. Appropriate for non-sensitive communications where you need evidence of delivery and access but not identity verification.

### Challenge

After clicking the link, the recipient is presented with a challenge question configured in `DeliverySignChallenge`. They must provide the correct answer (configured in `DeliverySignChallengeResponse`) before the notice content is revealed. Use when you need to confirm the recipient's identity using information only they would know — a contract reference, last four digits of a document, or similar.

### MobilePin

After clicking the link, the recipient is prompted to enter a one-time PIN delivered to their mobile device via the channels configured in `MobilePinChannels`. If the mobile number for PIN delivery differs from `RecipientAddress`, configure it in `DeliverySignFixedMobile`. Each element of `MobilePinChannels` is one attempt; all channels in that element are tried simultaneously.

### EmailPin

After clicking the link, the recipient is prompted to enter a one-time PIN sent to an email address. If the PIN delivery address differs from `RecipientAddress`, configure it in `DeliverySignFixedEmail`.

### Captcha and QERDS-specific checks

Depending on tenant configuration, the recipient can also encounter a captcha step before the content is displayed.

For QERDS-certified notices with legal-ID verification, the recipient can be asked to confirm a government-issued document number before any other access step. If no verified identity is already registered and in-flow enrollment is enabled, the recipient is redirected to the identity provider and then returned to the notice.

### Commitment actions on the hosted page

When `CommitmentChoice` is not `Disabled`, the hosted notice page displays the configured action buttons after the recipient has opened the content. If `CommitmentCommentsAllowed` is `true`, a comment field is shown alongside the buttons. If `AcceptReasons` or `RejectReasons` are configured, the recipient selects from those predefined options rather than typing freely. `CommitmentChoiceButtonText` and `CommitmentChoiceButtonOnly` further customize how the commitment control is presented.

## Callbacks and what you receive

When a state in `PushNotificationFilter` is reached, Namirial Notify sends an HTTP POST to `PushNotificationUrl` with the following JSON payload.

### Base payload

| Field | Type | Description |
|  --- | --- | --- |
| `Identifier` | string | Unique ID of this callback delivery. Use it to deduplicate — the platform retries on non-2xx and on timeouts, so the same event may be delivered more than once. |
| `Kind` | string | The state or event that triggered this callback (e.g. `Sent`, `Delivered`, `Received`, `Read`, `Replied`, `Closed`, `AffidavitPublished`). |
| `Date` | datetime | Timestamp of the state transition that fired this callback. |
| `EvidenceId` | UUID | The `Id` of the EviNotice, as returned at submission. |
| `EvidenceType` | string | Always `eviNotice` for EviNotice callbacks. |
| `EvidenceState` | string | Current state of the notice at the time the callback was sent. |
| `Owner` | string | Identifier of the account that submitted the notice. |
| `OwnerEmail` | string | Email address of the submitting account. |
| `AdditionalData` | object | Event-specific fields. Always includes the fields listed below. |


### `AdditionalData` fields — always present

| Field | Description |
|  --- | --- |
| `Subject` | The subject of the notice. |
| `LookupKey` | The integrator-assigned lookup key set at submission. |
| `State` | Current lifecycle state. |
| `CreationDate` | Timestamp when the notice was submitted. |
| `From` | Notification sender address. |
| `To` | Recipient address the notification was sent to. |
| `ExtraData` | The `PushNotificationExtraData` value set at submission, if provided. |


### `AdditionalData` fields — per event

| Callback `Kind` | Extra fields |
|  --- | --- |
| `Replied` | `Comments` — the free-text comment left by the recipient, if `CommitmentCommentsAllowed` was `true`. |
| `Closed` | `Outcome` — the final outcome (`Accepted`, `Rejected`, `Refused`, `Failed`, etc.). `OutcomeDescription` — human-readable description of the outcome. |
| `AffidavitPublished` | `AffidavitId` — unique ID of the generated affidavit. `AffidavitKind` — the kind that was generated. `AffidavitName` — filename of the affidavit PDF. |


### Callback reliability

Make your callback handler idempotent, keyed on `Identifier` — duplicate deliveries will occur. Return `2xx` promptly; the platform interprets timeouts as failures and retries. Use `PushNotificationExtraData` to embed a routing key so your handler can correlate the callback to your internal records without a separate API call.

### Securing your callback endpoint

See [Security and authentication](/products/namirialnotify/dev/security-best-practices) for callback hardening guidance including signature verification and IP allowlisting.

## States reference

| State | Description |
|  --- | --- |
| `Draft` | Notice has been staged but not yet submitted. |
| `Submitted` | Notice has been accepted by the platform. |
| `Processed` | Attachments validated, content certified, notice ready for dispatch. |
| `Dispatched` | Notification queued; delivery to the recipient's channel is starting. |
| `Sent` | The selected delivery channel accepted the notification. |
| `Delivered` | Delivery confirmation received from the channel. |
| `Received` | Recipient followed the hosted notice link. The recipient has not yet read the content. Unique to EviNotice. |
| `Read` | Recipient opened and read the hosted notice content. |
| `Replied` | Recipient accepted or rejected the notice. When the lifecycle closes, the final outcome is `Accepted` or `Rejected`. |
| `Closed` | Notice lifecycle is complete. |
| `Failed` | A recoverable processing or delivery failure occurred. The platform may retry or advance to a later state. |


**On `Replied`:** by default, the notice closes immediately after the commitment is recorded. Some configurations keep tracking open until the TTL elapses. Subscribe to both `Replied` and `Closed` if you need to react to the recipient's answer and then mark the lifecycle as final.

**On `Received` vs `Read`:** `Received` fires when the recipient clicks the link; `Read` fires when they open the content. A recipient can click the link and abandon the page without reading — both events are recorded independently.

**On refusal:** when a notice is refused, the state moves directly to `Closed` with outcome `Refused`. `Refused` does not appear as a lifecycle state — it only surfaces as an outcome value.

## Evidence and affidavits

`AffidavitKinds` selects which evidence events generate signed affidavit PDFs. Generation is asynchronous; you receive an `AffidavitPublished` callback when each affidavit is ready (if `AffidavitPublished` is in `PushNotificationFilter`).

### When each affidavit is generated

| `AffidavitKinds` value | Triggers at | Notes |
|  --- | --- | --- |
| `Submitted` | `Processed` | Certifies the notice content at submission time. |
| `SubmittedAdvanced` | `Processed` | Advanced variant with extended content certification. |
| `Dispatched` | `Dispatched` | Certifies that the notification was queued for dispatch. |
| `TransmissionResult` | `Sent` | Certifies the outcome of the notification send attempt via the delivery channel. |
| `DeliveryResult` | `Delivered` | Certifies delivery confirmation from the channel. |
| `Received` | `Received` | Certifies that the recipient followed the hosted notice link. |
| `Read` | `Read` | Certifies that the recipient opened and read the hosted notice content. |
| `Committed` | `Replied` | Certifies the recipient's acceptance or rejection decision. |
| `CommittedAdvanced` | `Replied` | Advanced variant of the commitment affidavit. |
| `Refused` | `Closed` (outcome `Refused`) | Certifies that the recipient refused the notice without opening it. |
| `Closed` | `Closed` | Certifies the end of the notice lifecycle. |
| `ClosedAdvanced` | `Closed` | Advanced variant of the closure affidavit. |
| `Complete` | `Closed` | Certifies the full chain from submission to closure (only generated when the notice was processed). |
| `CompleteAdvanced` | `Closed` | Advanced variant of the complete lifecycle affidavit. |
| `Event` | Various technical events | Internal technical record for events without a more specific affidavit kind. |
| `OnDemand` | On request | Requires a separate `POST /v2/EviNotice/Affidavits/Request` call while the notice is still eligible. |
| `ContentDownload` | Content download | Certifies that the recipient downloaded the notice content or an attachment. Requires `EnforceTrackingUntilTimeToLive: true`. |
| `Failed` | Terminal failure | Certifies a permanent delivery failure. |


For the legal implications and cross-service comparison of each affidavit type, see [Evidence and affidavits](/products/namirialnotify/user-guides/evidences-affidavits).

## Querying status

Use the Query endpoint as a fallback when callbacks lag, for point-in-time snapshots, or for batch reconciliation.


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

EviNotice Query uses **cursor-based pagination**, unlike the offset-based pagination in EviMail and EviSMS. Pass `Cursor` from the previous response to retrieve the next page. When `Cursor` is absent from the response, there are no further results.

**Response field names are PascalCase** (`Cursor`, `Results`) rather than the camelCase used by EviMail and EviSMS v1 query endpoints. Deserialise accordingly if sharing response models across services.

Common filters:

- `LookupKeys: ["your-key"]` — fetch by your correlation key.
- `State: "Closed"` — fetch only closed notices.
- `Outcome: "Refused"` — fetch by final outcome.
- `Limit` — maximum results per page (1–100, default 100).


To retrieve affidavit or attachment metadata, use the Get endpoint (`GET /v2/EviNotice/{Id}`) with `IncludeAffidavits=true` or `IncludeAttachments=true`. To download all affidavits or attachments as a ZIP file, use the dedicated download endpoints.

## First-call walkthrough

### What you need

- Namirial Notify credentials (username and password)
- A recipient email address or mobile number for testing
- An HTTPS endpoint to receive callbacks (or use a tool like [Webhook.site](https://webhook.site) for initial testing)


### Step 1 — Submit your first notice


```http
POST /v2/EviNotice/Submit
Authorization: Basic <base64(username:password)>
Content-Type: application/json
X-Evi-IdempotencyToken: <uuid>

{
  "Subject": "Test certified notice",
  "Body": "<p>This is a test certified notice. Please read and acknowledge.</p>",
  "RecipientAddress": "recipient@example.com",
  "LookupKey": "test-001",
  "CertificationLevel": "Standard_EU",
  "DeliverySignMethod": "WebClick",
  "NotificationLayout": "Certified",
  "Language": "en",
  "AffidavitKinds": ["Submitted", "DeliveryResult", "Read", "Closed"],
  "PushNotificationUrl": "https://your-endpoint.example.com/callbacks",
  "PushNotificationFilter": ["Sent", "Delivered", "Received", "Read", "Closed", "AffidavitPublished"]
}
```

A `200 OK` response contains `{ "Id": "<uuid>" }`. Store the `Id` — you will use it to poll status and retrieve evidence.

### Step 2 — Verify the notice progresses

Query by `Id` to confirm the notice moves through `Submitted` → `Processed` → `Dispatched` → `Sent`:


```http
POST /v2/EviNotice/Query
Authorization: Basic <base64(username:password)>
Content-Type: application/json

{
  "LookupKeys": ["test-001"]
}
```

Or retrieve it directly:


```http
GET /v2/EviNotice/<Id>
Authorization: Basic <base64(username:password)>
```

### Step 3 — Follow the notice as the recipient

Open the delivery email in the recipient's inbox, click the secure link, and read the notice. Verify that:

- A `Received` callback fires when the link is clicked
- A `Read` callback fires when the notice is opened
- The notice state in Query advances to `Read`


### Step 4 — Confirm closure and download the affidavit

After the notice closes, retrieve the affidavit:


```http
GET /v2/EviNotice/<Id>/Affidavits
Authorization: Basic <base64(username:password)>
```

This returns a ZIP file containing all generated affidavit PDFs. Verify the affidavit content covers the lifecycle events you configured in `AffidavitKinds`.

### Step 5 — Test the failure path

Submit a notice with an invalid or encrypted PDF attachment and set `IncludeOnAffidavits` to `true` for that attachment. Confirm that:

- The notice reaches `Failed` then `Closed` with `Outcome: Failed`
- A `Failed` callback fires to your endpoint
- The `Closed` callback includes `Outcome: Failed` in `AdditionalData`


## Integration checklist

- Set `LookupKey` on every Submit and persist `Id` from the response.
- Send `X-Evi-IdempotencyToken` (UUIDv4) on every Submit. Treat `202 Accepted` as success.
- Choose `DeliverySignMethod` deliberately — `WebClick` for low-friction; `MobilePin` or `Challenge` for sensitive content.
- Subscribe only to the callback kinds you act on. `Received` and `Read` are unique to EviNotice — include them if your flow depends on distinguishing link-click from content-open.
- Make your callback handler idempotent, keyed on `Identifier`.
- Store the raw callback body before parsing.
- Include `AffidavitPublished` in `PushNotificationFilter` if you download affidavits programmatically — it tells you exactly when each affidavit is ready.
- If using `CommitmentChoice`, test both the accept and reject paths in pre-production.
- If using `AllowRefusal`, subscribe to `Closed` with outcome `Refused` and handle it as a terminal negative result.
- Include `OnDemand` in `AffidavitKinds` at submit time if you plan to call the affidavit request endpoint later — this cannot be added retroactively.
- Remember that EviNotice query responses use PascalCase field names (`Cursor`, `Results`, `Id`) — deserialise separately from EviMail/EviSMS if sharing models.
- Use the `GET /v2/EviNotice/{Id}/Affidavits` endpoint to download affidavit ZIPs rather than requesting them one at a time.


## Troubleshooting

| Symptom | Likely causes | What to check | What to do |
|  --- | --- | --- | --- |
| No callbacks received | `PushNotificationUrl` missing or HTTP (not HTTPS); `PushNotificationFilter` omits the `Kind` you expect; endpoint returned non-2xx and retries exhausted | Query the notice state directly; check your server access logs for the callback `Identifier` | Confirm filter and URL; switch to HTTPS; use Query polling as fallback |
| Notice stays in `Dispatched` or `Sent` | Notification channel slow or unavailable; recipient MTA greylisting (email); SMS operator delay | Timestamps in Query response: `DispatchedOn`, `SentOn`, `DeliveredOn` | Wait; do not resubmit |
| Recipient says they did not get the notification | Spam filter caught the email; wrong address or number; SMS delivery failure | `Delivered` callback and `DeliveredOn` timestamp; `TransmissionResult` affidavit if generated | Confirm address; check spam folder; resubmit with corrected address and a new idempotency token |
| `Received` callback fired but `Read` never fires | Recipient clicked the link but abandoned the page without opening the content | `ReceivedOn` timestamp present; `ReadOn` absent in Query | Normal — `Received` and `Read` are independent events; wait for TTL or contact the recipient |
| Notice closed with `Outcome: Failed` | A permanent processing or transmission failure was recorded before closure | `FailedOn`, callback payloads, and failure details | Correct the payload or address; resubmit with a new idempotency token only after the cause is fixed |
| Commitment callback not received | `CommitmentChoice` is `Disabled`; `Replied` not in `PushNotificationFilter` | Submit request at creation time | Cannot change `CommitmentChoice` after submission; resubmit with the correct setting and a new idempotency token |
| Affidavit not available | Generation is asynchronous; `AffidavitPublished` has not fired yet; the relevant kind was not included in `AffidavitKinds` at submission | Query with `IncludeAffidavits=true`; check `AffidavitKinds` on the Get response | Wait for `AffidavitPublished` callback; if the kind is missing, it cannot be added retroactively — resubmit |
| Submit → `400 Bad Request` | Missing required field (`Subject`, `Body`, or `RecipientAddress`); invalid `CertificationLevel` for your account; attachment too large or count exceeded | Problem+JSON body: `Detail` and `InvalidValues` | Fix the flagged field; retry with a new idempotency token |
| Submit → `401 Unauthorized` | Wrong environment base URL; credentials rotated | `Authorization` header; confirm target environment | Re-issue credentials through your Namirial Notify contact |
| Submit → `403 Forbidden` | Account not provisioned for EviNotice; insufficient credit balance | Account permissions and credit balance | Contact your Namirial Notify account manager |


## Related

- [EviNotice API](/products/namirialnotify/apis/evinotice-api)
- [How to create a new EviNotice](/products/namirialnotify/issuer/create-evinotice)
- [How a recipient receives an EviNotice](/products/namirialnotify/recipient/receive-evinotice)
- [EviMail](/products/namirialnotify/services/evimail)
- [EviSMS](/products/namirialnotify/services/evisms)
- [API documentation](/products/namirialnotify/dev/api-documentation)
- [Callbacks and webhooks](/products/namirialnotify/dev/callbacks)
- [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)