# EviPost API

The EviPost API lets you submit certified physical postal communications (equivalent to a burofax) and query the status of previously submitted items. It is a REST API that uses HTTP Basic authentication and returns JSON responses.

For end-to-end lifecycle, postal service types, and integration guidance, see the [EviPost service guide](/fr/products/namirialnotify/services/evipost).

## Environments

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


For the public Namirial Notify API environments, this V1 service is exposed under the `/v1` base path. Use public routes such as `/v1/EviPost/Submit`, `/v1/EviPost/Query`, and `/v1/EviPost/AffidavitRequest`.

Some lower-level technical artifacts may show these V1 routes without the `/v1` prefix. For customer integrations, use the public `/v1` base path shown in this documentation.

For shared environment guidance across services, see the [API reference overview](/fr/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)>
```

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

## Idempotency

EviPost Submit supports idempotent submission. Include the `X-Evi-IdempotencyToken` header with a unique value per logical operation (a GUID 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 communication is **not** resubmitted.

EviPost v1 JSON responses serialize UUIDs as 32 hexadecimal characters without dashes. Request UUIDs can include or omit dashes.

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

EviPost v1 uses a `responseStatus` object for error responses.

```json
{
  "responseStatus": {
    "errorCode": "ArgumentException",
    "message": "RecipientAddress.Country is required.",
    "errors": [
      {
        "errorCode": "NotEmpty",
        "fieldName": "RecipientAddress.Country",
        "message": "RecipientAddress.Country is required."
      }
    ]
  }
}
```

| Field | Description |
|  --- | --- |
| `errorCode` | Machine-readable error classifier |
| `message` | Human-readable summary of the error |
| `errors` | Array of field-level validation errors (present on `400` responses) |


Common status codes and their causes:

| Status | Typical cause |
|  --- | --- |
| `400 Bad Request` | Missing required field, invalid address, invalid certification level, document too large, or business rule failure |
| `401 Unauthorized` | Incorrect credentials or missing `Authorization` header |
| `403 Forbidden` | Account not provisioned for EviPost |
| `492` | Submit quota reached for this recipient or for this service type on your site |


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

## Endpoints

### Submit a certified postal communication

```
POST /v1/EviPost/Submit
```

Submits a new certified postal communication. On success, returns a `UniqueId` that identifies the submission and can be used to query its status later.

**Required fields:** `Document` (Base64-encoded PDF), `RecipientName` (non-blank), and `RecipientAddress`.

Optional fields include `RecipientLegalName`, `IssuerName`, `IssuerLegalName`, `IssuerAddress`, `Options`, `LookupKey`, `RecipientPhone`, `RecipientEmail`, `IssuerPhone`, `IssuerEmail`, and `IssuerComments`. Supply `IssuerName` and `IssuerLegalName` if you want them in the evidence; the API does not fill these fields from the account. For `RecipientPhone` and `IssuerPhone`, use `+` followed by the country code and phone number, with digits only (for example, `+34677888777`). Other formats return `400`.

| Response | Description |
|  --- | --- |
| `200 OK` | Postal communication accepted. Body contains `{ "uniqueId": "..." }` — the UUID of the submitted postal communication. (EviMail and EviSMS return the equivalent identifier as `eviId`.) |
| `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 or business rule failure. The response body contains a `responseStatus` object with `errorCode`, `message`, and an optional `errors` array of field-level details. |
| `401 Unauthorized` | Authentication failed. |
| `403 Forbidden` | The account is not provisioned for EviPost. Contact your Namirial Notify account manager to enable this service. |
| `492` | The submission quota for this recipient or for this service type on your site was reached. Avoid retrying immediately; contact support if it persists. |


See [Idempotency](#idempotency) above for retry safety guidance.

**Example request:**

```http
POST /v1/EviPost/Submit HTTP/1.1
Authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==
Content-Type: application/json

{
  "LookupKey": "a2R4S25kWiu79fsbubSXkw==",
  "Document": "<base64-encoded PDF>",
  "RecipientName": "Juan Valido",
  "RecipientLegalName": "Juan Valido",
  "RecipientAddress": {
    "StreetAddress": "Gran Via 74, 5 A",
    "PostalCode": "28014",
    "Locality": "Madrid",
    "Region": "Madrid",
    "Country": "ES"
  },
  "IssuerName": "Pedro Comprador",
  "IssuerLegalName": "Pedro Valido",
  "IssuerAddress": {
    "StreetAddress": "C/ Gran Via, 1, 1-A",
    "PostalCode": "28001",
    "Locality": "Madrid",
    "Region": "Madrid",
    "Country": "ES"
  },
  "IssuerPhone": "+34677888777",
  "IssuerEmail": "pedro.comprador@example.com",
  "IssuerComments": "Sending in March.",
  "Options": {
    "PostServiceType": "Registered",
    "CertificationLevel": "Advanced_EU",
    "EvidenceAccessControlMethod": "AutoChallenge",
    "OnlineRetentionPeriod": 1
  }
}
```

**Example response:**

```json
{
  "uniqueId": "69819c3e0c0e42b3a792a33b014a13a2"
}
```

### Query certified postal communications

```
GET /v1/EviPost/Query
```

Use GET for new integrations. The V1 service also accepts POST and HEAD for compatibility.

Returns a list of postal communications matching the specified filters. Results are paginated using `Limit` and `Offset`.

**Query parameters:**

| Parameter | Type | Description |
|  --- | --- | --- |
| `WithUniqueIds` | string | Filter by one or more unique IDs (comma-separated). |
| `WithLookupKeys` | string | Filter by one or more lookup keys (comma-separated). |
| `OnState` | string | Filter by current state. Contact support before using this parameter. |
| `WithOutcome` | string | Filter by outcome. Contact support before using this parameter. |
| `OrderResultsBy` | string | Sort field for results. Supported value: `CreationDate`. |
| `Offset` | integer | Number of results to skip. |
| `Limit` | integer | Maximum number of results to return. |
| `IncludeDocumentOnResult` | boolean | Include the original document (base64 PDF) in results. |
| `IncludeAffidavitsOnResult` | boolean | Include affidavit metadata in results. |
| `IncludeAffidavitBlobsOnResult` | boolean | Deprecated. When `true` with `IncludeAffidavitsOnResult=true`, include each affidavit PDF as Base64 in `affidavits[].bytes`; blob queries are limited to one postal communication. Set this to `false` for metadata-only results and use `/AffidavitsDownload` for new integrations. |


| Response | Description |
|  --- | --- |
| `200 OK` | Returns `{ "totalMatches": N, "results": [...] }`. |
| `400 Bad Request` | Invalid query, including a limit above the applicable maximum. |
| `401 Unauthorized` | Authentication failed. |
| `403 Forbidden` | The account is not provisioned for EviPost. Contact your Namirial Notify account manager to enable this service. |


Use at most 100 results without affidavits, 25 with affidavit metadata, or 1 when requesting embedded affidavit PDFs. These are also the defaults when `Limit` is omitted. Some deployments can embed PDFs when `IncludeAffidavitBlobsOnResult` is omitted. Send `IncludeAffidavitBlobsOnResult=false` explicitly for metadata only.

`stateDate` is the date of the recorded state, `lastStateChangeDate` reflects when the platform last updated the state or online retention expiry, and `outcomeDate` is the date assigned to the outcome. These can differ from each other and from individual milestone timestamps.

The tracking window is 35 days (50,400 minutes) for `Registered` and 15 days (21,600 minutes) for `Letter` and `LetterLite`. At timeout, the platform tries to close with the current outcome when that outcome supports closure; it does not assign `Expired`.

With the deprecated `IncludeAffidavitBlobsOnResult=false`,
`IncludeAffidavitsOnResult=true` adds affidavit metadata and IDs without
embedding the PDF files. Pass the returned affidavit IDs to the shared
[`/AffidavitsDownload`](/fr/products/namirialnotify/apis/downloads-api#download-affidavit-pdfs-by-id) endpoint
to retrieve the signed PDFs in a ZIP archive. This is the recommended retrieval
flow for new integrations.

**Example request:**

```
GET /v1/EviPost/Query?WithUniqueIds=3977d143-a6cb-4642-abc6-a33b016cbec2&IncludeAffidavitsOnResult=true&IncludeAffidavitBlobsOnResult=false HTTP/1.1
Authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==
```

**Example response:**

```json
{
  "results": [
    {
      "evidenceId": "3977d143a6cb4642abc6a33b016cbec2",
      "lookupKey": "a2R4S25kWiu79fsbubSXkw==",
      "recipientName": "Juan Valido",
      "address": {
        "streetAddress": "Gran Via 74, 5 A",
        "postalCode": "28014",
        "locality": "Madrid",
        "region": "Madrid",
        "country": "ES"
      },
      "state": "Sent",
      "stateDate": "2026-01-15T10:00:07Z",
      "lastStateChangeDate": "2026-01-15T10:00:11Z",
      "outcome": "Sent",
      "outcomeDate": "2026-01-15T10:00:07Z",
      "creationDate": "2026-01-15T10:00:00Z",
      "submittedOn": "2026-01-15T10:00:00Z",
      "processedOn": "2026-01-15T10:00:03Z",
      "sentOn": "2026-01-15T10:00:07Z",
      "timeToLive": 50400,
      "costCentre": "dept-legal",
      "affidavits": [
        {
          "uniqueId": "000c1f7042aca3ea149f943879726a87",
          "date": "2026-01-15T10:00:12Z",
          "evidenceUniqueId": "3977d143a6cb4642abc6a33b016cbec2",
          "description": "Certification of postal communication"
        }
      ]
    }
  ],
  "totalMatches": 1
}
```

### Request an on-demand affidavit

```
POST /v1/EviPost/AffidavitRequest
```

Only the account that submitted a `Letter` or `LetterLite` can request an affidavit while the communication is open (after submission and before `Closed`). At Submit, set `AffidavitsOnDemandEnabled: true` and use an advanced `AffidavitProfile`: `AdvancedContentOnSubmit`, `AdvancedContentOnClose`, or `AdvancedContentOnSubmitAndOnClose`. A configurable limit applies per communication. `Registered` accepts the flag at Submit but does not support this operation.

A `200 OK` confirms that the request was queued. If the communication closes or earlier requests reach the limit before processing, the platform skips this request without sending a failure response or an `AffidavitPublished` callback for it. Use Query to check which affidavits were generated.

**Request body:**

| Field | Type | Description |
|  --- | --- | --- |
| `UniqueId` | string (UUID) | Required. Unique ID of the EviPost to generate an affidavit for. |
| `IncludeDocument` | boolean | Optional. Include the original document in the affidavit. |
| `IncludeEvents` | boolean | Optional. Include detailed event information in the affidavit. |


| Response | Description |
|  --- | --- |
| `200 OK` | Accepts the request for asynchronous generation and returns `{ "requestId": "..." }`. |
| `400 Bad Request` | Business rule or validation failure. The response body contains a `responseStatus` object with `errorCode`, `message`, and an optional `errors` array. |
| `401 Unauthorized` | Authentication failed. |
| `403 Forbidden` | The authenticated account lacks the required API or EviPost permissions. |


**Example request:**

```http
POST /v1/EviPost/AffidavitRequest HTTP/1.1
Authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==
Content-Type: application/json

{
  "UniqueId": "87ffa214-e773-4bd5-9b8d-a8ef00fd80f8",
  "IncludeDocument": true,
  "IncludeEvents": true
}
```

**Example response:**

```json
{
  "requestId": "79726a87000c1f7042aca3ea149f9438"
}
```

### Cancel a postal communication

```
POST /v1/EviPost/Cancel
```

Requests cancellation of a previously submitted EviPost. Only the account that originally submitted the postal communication can request cancellation.

Use this operation for `Letter` with at least one tracking option enabled: a delivery receipt, delivery attempts, or disposal. The communication must not be `Draft` or `Closed`, and the request must be within the configured cancellation window (30 minutes from creation by default).

Requests that fail an eligibility check are rejected. A non-2xx response means the request was not accepted. A successful response confirms that the platform accepted the request for asynchronous processing. It does not confirm that the postal operator has cancelled the communication.

To confirm cancellation, check that Query reports the `Cancelled` state, or the `Closed` state with the `Cancelled` outcome. If you use callbacks, a `Cancelled` callback confirms cancellation only when `AdditionalData.Success` is `true`; `false` reports an unsuccessful attempt.

**LetterLite cancellation limitation**

The API can accept a cancellation request for `LetterLite`, but the current cancellation processor does not support that service type. Do not rely on a successful API response as confirmation that a `LetterLite` shipment has been stopped; contact support if cancellation is needed.

**Permission required**

This endpoint requires the `CanUseCancel` permission in addition to the standard EviPost API permission. Contact your Namirial Notify account manager if you need this permission enabled.

**Request body:**

| Field | Type | Description |
|  --- | --- | --- |
| `UniqueId` | string (UUID) | Required. Unique ID of the EviPost to cancel, as returned at submission. |


| Response | Description |
|  --- | --- |
| `200 OK` | Returns `{ "uniqueId": "..." }` — the ID of the communication whose cancellation request was accepted. Cancellation is not yet confirmed. |
| `400 Bad Request` | Invalid request, such as a malformed UUID. Supply a non-empty `UniqueId`. |
| `401 Unauthorized` | Authentication failed, or the authenticated account is not the owner of the postal communication. |
| `403 Forbidden` | The account lacks the `CanUseCancel` permission, or EviPost is not enabled for this account. |
| `404 Not Found` | No postal communication with the given UniqueId was found. |


**Example request:**

```http
POST /v1/EviPost/Cancel HTTP/1.1
Authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==
Content-Type: application/json

{
  "UniqueId": "69819c3e-0c0e-42b3-a792-a33b014a13a2"
}
```

**Example response:**

```json
{
  "uniqueId": "69819c3e0c0e42b3a792a33b014a13a2"
}
```

## States and outcomes

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

**States** represent the current step in the postal communication lifecycle.

| State | Description |
|  --- | --- |
| `Draft` | Communication prepared but not yet submitted. |
| `Submitted` | Accepted by the platform, pending processing. |
| `Processed` | Locally processed and queued for the postal operator. |
| `Dispatched` | Dispatched to the postal communication system. |
| `Issued` | Item issued by the postal operator (operator-specific intermediate state). |
| `Sent` | Handed off to the postal operator or messaging service. |
| `Failed` | A processing or delivery failure occurred. |
| `Undelivered` | The operator reported non-delivery. This does not itself close tracking or identify a collection or return-to-sender action. |
| `Missing` | Value exposed by the API contract; no normal transition into this state is defined by the current lifecycle implementation. Contact support if it appears. |
| `Delivered` | Delivered to the final recipient. |
| `Disposed` | The provider reported destruction of the undelivered item under a service configured for disposal. |
| `Cancelled` | Communication was cancelled. |
| `Closed` | Postal tracking is complete and the outcome is final. Affidavit publication can still follow. |


**Outcomes** represent the result recorded so far and can change while the communication remains open. Use the outcome at `Closed` as the final result.

When delivery receipt tracking is off, a report without proof of delivery can set the state and outcome to `Failed` while still setting `deliveredOn`. Use the state and outcome to confirm delivery.

An individual delivery-attempt event does not itself change the state to `Undelivered`. For `Registered` and `Letter` with delivery tracking enabled, the platform accepts a later valid delivery report before closure; whether an operator emits that sequence is unconfirmed. `LetterLite` cannot complete normal closure with `Delivered` once non-delivery has been recorded. A `Letter` workflow configured for disposal can continue to `Disposed`; a later failure report for `Letter` can instead lead to `Failed` before closure. `Registered` and `LetterLite` can close with a final `Undelivered` outcome. See [Delivery attempts and non-delivery](/fr/products/namirialnotify/services/evipost#delivery-attempts-and-non-delivery) for operator details and callback guidance.

| Outcome | Description |
|  --- | --- |
| `None` | No outcome determined yet. |
| `Dispatched` | Item dispatched to the postal operator (intermediate outcome, may be superseded). |
| `Sent` | Item sent. This can be the final outcome for plain `Letter` without delivery receipt, attempt tracking, or disposal. |
| `Declined` | Defined in the API contract and domain, but not emitted by the current postal event handlers. Recipient refusal is reported as `Rejected`. |
| `Rejected` | Recipient rejected the postal communication. |
| `Acknowledged` | Value exposed by the API contract but not produced by the current lifecycle implementation. Contact support if it appears. |
| `Hindered` | Value exposed by the API contract but not produced by the current lifecycle implementation. Contact support if it appears. |
| `Undelivered` | Non-delivery was reported. Final only when the communication is `Closed`. |
| `Failed` | A processing error prevented normal delivery. |
| `Delivered` | Successfully delivered to the recipient. |
| `Disposed` | Destruction of the undelivered item was reported for a service configured for disposal. |
| `Cancelled` | The postal operator confirmed the issuer's cancellation request. |
| `Expired` | Listed in the API contract, but not supported as the outcome of normal postal closure. A tracking timeout does not automatically assign this outcome. If it appears, check the current state with Query and contact support. |


## Key request fields

### `Document`

Use a valid PDF smaller than 2,097,152 bytes before Base64 encoding. It must have no password protection, password encryption, JavaScript, or embedded files, and every page must have a non-zero width and height. The page limit depends on the service type and is currently 150 pages by default. A file can pass the initial Submit checks and fail these later checks. In that case Query can show `Closed` with outcome `Failed`; the same outcome can result from postal-service rejection. A plan that bills per submission can also reject the initial page estimate or fail the communication later if the actual page count exceeds the charged tier.

The document or letter to be sent, provided as a base64-encoded PDF string.

### `RecipientAddress` / `IssuerAddress`

Both address objects share the same shape:

| Field | Required | Description |
|  --- | --- | --- |
| `StreetAddress` | Yes | Street name and number. Maximum 100 characters for the recipient and 255 for the issuer. |
| `PostalCode` | Yes | Postal code. |
| `Locality` | Yes | City or town. |
| `Region` | Conditional | Province or region. Required in `RecipientAddress` for `Registered`. The issuer region must also be present, either supplied in `IssuerAddress` or filled from the site address. |
| `Country` | Yes | ISO 3166-1 alpha-2 country code (e.g. `ES`). |
| `PostOfficeBoxAddress` | No | Post office box address, if applicable. |


### `Options`

The `Options` object groups all processing and certification settings.

Send `CertificationLevel` and `EvidenceAccessControlMethod` explicitly. The API does not use the Web form’s account defaults for these fields.

| Field | Description |
|  --- | --- |
| `PostServiceType` | `Registered` (default), `Letter`, or `LetterLite`. Defaults to `Registered` if omitted. See details below. |
| `PostServiceProfile` | Optional provider profile for `Letter`. Omit it unless support has given you a profile identifier. |
| `CertificationLevel` | Legal framework for certification. Supported values include `Standard`, `Advanced`, and regional variants such as `Standard_EU` or `Advanced_EU`. Availability depends on the account. EviPost does not support QERDS levels. |
| `AffidavitProfile` | Controls which affidavits are generated. If omitted, it is inferred from `CertificationLevel`; if set, it must be consistent with the certification level. See details below. |
| `AffidavitsOnDemandEnabled` | Set at Submit for an advanced content profile. See [eligibility and limits](#request-an-on-demand-affidavit). |
| `OnlineRetentionPeriod` | Online retention in years, from 1 to 20. Currently 1 year by default. |
| `NotaryRetentionPeriod` | Use `5` for five years of notarial custody or `0` to disable it. The API treats any non-zero value as five years. |
| `NotaryProfile` | Required when `NotaryRetentionPeriod > 0`; omit it otherwise. Use a provisioned profile identifier with up to 50 characters total, made of alphanumeric segments separated by colons (for example, `notary:profile`). |
| `EvidenceAccessControlMethod` | Controls how recipients access the evidence: `Public`, `Challenge`, `AutoChallenge` (defaults to `Public`, with no access challenge). When `Challenge`, also supply `EvidenceAccessControlChallenge` and `EvidenceAccessControlChallengeResponse`. |
| `EvidenceAccessControlChallenge` / `EvidenceAccessControlChallengeResponse` | Challenge question and expected answer. Both required when `EvidenceAccessControlMethod` is `Challenge`. |
| `CostCentre` | Optional. Groups submissions for billing/reporting purposes. |
| `CustomFields` | Optional. Array of custom key-value fields (see `CustomFields` below). |
| `PushNotificationUrl` | Optional. URL to receive state-change callbacks. |
| `PushNotificationFilter` | Optional. Array of states that trigger a callback. |
| `Language` | Optional. Language for the evidence record and generated affidavits (e.g. `en`, `es`). Defaults to your site's configured language if omitted. |
| `EnableDeliveryReceipt` | Optional. For `Letter` type: request a delivery receipt from the provider. |
| `EnableDeliveryAttempts` | For `Letter`: set to `true` with a positive `DeliveryAttemptsNumber`. |
| `DeliveryAttemptsNumber` | For `Letter`: number of attempts. A positive value requires `EnableDeliveryAttempts: true`. The maximum is currently 2 by default. |
| `EnableDisposal` | For `Letter`: set to `true` to use a non-zero `DisposalDaysAmmount`. |
| `DisposalDaysAmmount` | For `Letter`: days before disposal if undelivered. Use 0 for no disposal or 1 to 15 with `EnableDisposal: true`. |
| `PushNotificationExtraData` | Optional. Free-text passed through in every callback payload. |


### `PostServiceType`

Controls the type of postal delivery. EviPost physical delivery is currently available for destinations within **Spain**; availability of each type depends on your account provisioning.

- `Registered` — Default. Sends a certified postal communication equivalent to a burofax, delivered through the national postal operator (Correos). Delivery attempts are handled by the operator. Omit the `Letter` receipt, attempt and disposal options: enabling those options or sending non-zero values for attempts or disposal returns `400`.
- `Letter` — Sends to a printing and enveloping provider (MRW). Supports optional delivery receipt, delivery attempts and disposal.
- `LetterLite` — A lower-cost single-attempt printed certified letter (MRW). Available **only within mainland Spain** (the islands, Ceuta, Melilla, Portugal, Andorra, and Gibraltar are excluded). Omit the delivery-attempt and disposal options. This service is unavailable on sites billed per submission.


### `CertificationLevel`

Defines the legal framework and geographic variant for certification. The API accepts `Standard`, `Advanced`, and regional values such as `Standard_EU`, `Advanced_EU`, `Standard_CO`, or `Advanced_MX`. Availability depends on the account. EviPost does not support QERDS certification levels.

### `AffidavitProfile`

Controls what affidavits are generated during the process:

| Value | Description |
|  --- | --- |
| `None` | No affidavits generated. |
| `Basic` | A single receipt affidavit when tracking is complete. Default for `Standard` certification. |
| `AdvancedContentOnSubmit` | One affidavit per event, plus a timestamped content affidavit at submission. Default for `Advanced` certification. |
| `AdvancedContentOnClose` | One affidavit per event, plus a receipt showing the document body when tracking is complete. |
| `AdvancedContentOnSubmitAndOnClose` | Combination of the above two. |


### `PushNotificationFilter`

An array of event names that trigger a callback to `PushNotificationUrl`. Set both `PushNotificationUrl` and a non-empty `PushNotificationFilter`, or omit both. Submit returns `400 Bad Request` if only one is set or if the filter repeats a value. Valid values for EviPost: `Processed`, `Dispatched`, `Sent`, `Delivered`, `Closed`, `Cancelled`, `Issued`, `Disposed`, `AffidavitPublished`.

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

### `PushNotificationExtraData`

A free-text field for additional data to be included in every push notification sent to `PushNotificationUrl`. Available in the `AdditionalData.ExtraData` field of the callback payload.

### `CustomFields`

An array of custom key-value fields attached to the submission. Each field requires `Key`, `Label`, `Value`, and a non-blank `TypeName`. Do not combine a field marked `IsLookupKey: true` with a top-level `LookupKey`; Submit returns `400`. Fields marked with `IsLookupKey: true` are indexed and surfaced in query results under `LookupKey`, concatenated with `::` if multiple values are present.

## Push notification payload

For an event selected in `PushNotificationFilter`, Namirial Notify sends a POST to `PushNotificationUrl` with the following JSON payload:

**Common fields:**

| Field | Description |
|  --- | --- |
| `Identifier` | Lifecycle event ID or, for `AffidavitPublished`, the affidavit ID used by the publisher. Retries retain it. |
| `Kind` | The state or event that triggered the callback. A `Cancelled` event can report an unsuccessful attempt; check `AdditionalData.Success`. |
| `Date` | Timestamp of the event. |
| `EvidenceId` | Unique identifier of the EviPost. |
| `EvidenceType` | Always `eviPost`. |
| `Site` | Name of the issuer's site. |
| `Owner` | Not populated; accept an absent or null value. |
| `OwnerEmail` | Email of the site user. |
| `AdditionalData` | Object containing event-specific fields (see below). |


**`AdditionalData` fields:**

| Field | Description |
|  --- | --- |
| `Sender` | Issuer name, combining the legal and display names in that order when both are supplied. |
| `Recipient` | Recipient name, combining the legal and display names in that order when both are supplied. |
| `LookupKey` | Lookup key set at submission. |
| `State` | Current state name. |
| `CreationDate` | Submission date. |
| `ExtraData` | Value of `PushNotificationExtraData`, if set. |


See [EviPost event fields](/fr/products/namirialnotify/services/evipost#callback-event-fields) and [callback reliability](/fr/products/namirialnotify/services/evipost#callback-reliability), including the case of regenerated affidavits.

**Example payload (`Processed` event):**

```json
{
  "Identifier": "600a41fd-d96b-4c4b-abb2-a87000d7da3f",
  "EvidenceId": "bae409d127de4b18b97ca87000c75b1c",
  "EvidenceType": "eviPost",
  "Kind": "Processed",
  "Date": "2018-01-22T12:05:53.5875507Z",
  "Site": "pruebas",
  "Owner": null,
  "OwnerEmail": "pruebas@evicertia.com",
  "AdditionalData": {
    "Sender": "Pedro Comprador",
    "Recipient": "Juan Valido",
    "LookupKey": "push-notification-test",
    "State": "Processed",
    "CreationDate": "2018-01-22T13:05:49.9850990+01:00",
    "ExtraData": "{\"myId\": \"99cf386b-1590-4ddb-af68-607b3e7c1194\"}"
  }
}
```

### On-demand affidavit callback

When an affidavit requested via `AffidavitRequest` has been generated, Namirial Notify may send the normal `AffidavitPublished` push notification to the `PushNotificationUrl` configured on the original submission, when the original `PushNotificationFilter` includes `AffidavitPublished`. EviPost does not populate `AdditionalData.RequestId` for on-demand affidavits. Use `AdditionalData.AffidavitId` to locate or download the affidavit. Compare IDs as UUIDs: the callback uses dashes and Query omits them. The callback does not directly identify which request generated it.

**Example payload:**

```json
{
  "Identifier": "000c1f70-42ac-a3ea-149f-943879726a87",
  "EvidenceId": "87ffa214e7734bd59b8da8ef00fd80f8",
  "EvidenceType": "eviPost",
  "Kind": "AffidavitPublished",
  "Date": "2018-01-22T11:46:32.4830752Z",
  "Site": "pruebas",
  "Owner": null,
  "OwnerEmail": "pruebas@evicertia.com",
  "AdditionalData": {
    "Sender": "Acme Corporation",
    "Recipient": "Juan Valido",
    "LookupKey": "order-12345",
    "State": "Sent",
    "CreationDate": "2018-01-22T12:00:00Z",
    "AffidavitId": "000c1f70-42ac-a3ea-149f-943879726a87",
    "AffidavitName": "Certification of postal communication (upon request)"
  }
}
```

## OpenAPI specification

The OpenAPI 3.0.3 specification for the EviPost 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 /v1/EviPost/Submit`) — detailed request and response schemas, idempotency headers, validation rules, and HTTP status codes
- **Query endpoint** (`GET /v1/EviPost/Query`) — pagination parameters, filtering by ID or lookup key, state and outcome enums, and result structure
- **Affidavit request endpoint** (`POST /v1/EviPost/AffidavitRequest`) — on-demand affidavit generation
- **Cancel endpoint** (`POST /v1/EviPost/Cancel`) — asynchronous cancellation requests
- **Authentication** — HTTP Basic authentication requirements
- **Error handling** — V1 service-style error responses with `responseStatus` object containing `errorCode`, `message`, and `errors`
- **Data types** — schema definitions for documented addresses, postal options, certification levels, and evidence metadata


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

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

## Related

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