# 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](/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 [API documentation](/products/namirialnotify/dev/api-documentation#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)>
```

For credential handling, callback hardening, and production security checks, see [Security and authentication](/products/namirialnotify/dev/security-best-practices).

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

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 |


For shared error handling guidance, see [Error handling](/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), `RecipientAddress`.

Optional fields include `RecipientName`, `RecipientLegalName`, `IssuerName`, `IssuerLegalName`, `IssuerAddress`, `Options`, `LookupKey`, `RecipientPhone`, `RecipientEmail`, `IssuerPhone`, `IssuerEmail`, and `IssuerComments`.

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


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

**Example request:**


```json
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",
    "NotaryRetentionPeriod": 5,
    "OnlineRetentionPeriod": 1
  }
}
```

**Example response:**


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

### Query certified postal communications


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

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


| Response | Description |
|  --- | --- |
| `200 OK` | Returns `{ "totalMatches": N, "results": [...] }`. |
| `401 Unauthorized` | Authentication failed. |
| `403 Forbidden` | The account is not provisioned for EviPost. Contact your Namirial Notify account manager to enable this service. |


If `Limit` is omitted, the API uses a default of `100`. The default drops to `25` when `IncludeAffidavitsOnResult` is true.

**Example request:**


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

**Example response:**


```json
{
  "results": [
    {
      "evidenceId": "3977d143-a6cb-4642-abc6-a33b016cbec2",
      "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": "None",
      "outcomeDate": "2026-01-15T10:00:00Z",
      "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": 43200,
      "costCentre": "dept-legal"
    }
  ],
  "totalMatches": 1
}
```

### Request an on-demand affidavit


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

Generates a custom affidavit for a previously submitted EviPost. To use this endpoint, `AffidavitsOnDemandEnabled: true` must have been set in the original Submit request.

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


**Example request:**


```json
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
```

Cancels a previously submitted EviPost that has not yet been dispatched to the postal carrier. Only the account that originally submitted the postal communication can cancel it.

:::warning 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 cancelled postal communication. |
| `400 Bad Request` | Invalid request. The UniqueId is missing or not a valid UUID. |
| `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:**


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

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

**Example response:**


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

## 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 [EviPost evidence lifecycle](/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` | Delivery was not possible; item returned or held. |
| `Missing` | Item cannot be located by the postal operator (operator-specific intermediate state). |
| `Delivered` | Delivered to the final recipient. |
| `Disposed` | Item disposed of following an undelivered or returned status. |
| `Cancelled` | Communication was cancelled. |
| `Closed` | Lifecycle complete; no further events expected. |


**Outcomes** represent the overall result of the postal process.

| Outcome | Description |
|  --- | --- |
| `None` | No outcome determined yet. |
| `Dispatched` | Item dispatched to the postal operator (intermediate outcome, may be superseded). |
| `Sent` | Item sent; awaiting final delivery confirmation. |
| `Declined` | Recipient refused acceptance of the postal communication. |
| `Rejected` | Recipient rejected the postal communication. |
| `Acknowledged` | Postal operator acknowledged receipt of the item (operator-specific intermediate outcome). |
| `Hindered` | Delivery was hindered by an external circumstance (operator-specific intermediate outcome). |
| `Undelivered` | Delivery was not possible. |
| `Failed` | A processing error prevented normal delivery. |
| `Delivered` | Successfully delivered to the recipient. |
| `Disposed` | Item disposed of after an undelivered or returned outcome. |
| `Cancelled` | Cancelled by the issuer. |
| `Expired` | Delivery could not be completed within the postal deadline. |


## Key request fields

### `Document`

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. |
| `PostalCode` | Yes | Postal code. |
| `Locality` | Yes | City or town. |
| `Region` | No | Province or region. |
| `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.

All `Options` fields are optional at the API level: omit one and the platform applies a default (`PostServiceType` → `Registered`, `Language` → your site's configured language, `AffidavitProfile` → inferred from `CertificationLevel`, `EvidenceAccessControlMethod` → the account's configured default method). The web submission form pre-selects these same defaults, which is why they can appear mandatory in the portal — but the API does not require them. The only conditional requirements are `PostServiceProfile` (when `PostServiceType` is `Letter`) and the challenge fields (when `EvidenceAccessControlMethod` is `Challenge`).

| Field | Description |
|  --- | --- |
| `PostServiceType` | `Registered` (default), `Letter`, or `LetterLite`. Defaults to `Registered` if omitted. See details below. |
| `PostServiceProfile` | Profile identifier for the postal service. **Required when `PostServiceType` is `Letter`** (provisioned by support). Not used for `Registered` or `LetterLite`. |
| `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` | Boolean. Enables on-demand affidavit generation via `AffidavitRequest`. Requires an advanced content profile (`AdvancedContentOnSubmit`, `AdvancedContentOnClose`, or `AdvancedContentOnSubmitAndOnClose`). |
| `OnlineRetentionPeriod` | Time in years for online evidence retention. Default: 1 year. |
| `NotaryRetentionPeriod` | If set, applies 5-year notarial custody. Set to `0` to disable. |
| `NotaryProfile` | Required when `NotaryRetentionPeriod > 0`. Identifier of the notary for custody. |
| `EvidenceAccessControlMethod` | Controls how recipients access the evidence: `Public`, `Challenge`, `AutoChallenge` (the account's configured default method applies when omitted). 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` | Optional. For `Letter` type: enable delivery attempt tracking. |
| `DeliveryAttemptsNumber` | Optional. For `Letter` type: number of delivery attempts to request from the provider. |
| `DisposalDaysAmmount` | Optional. For `Letter` type: number of days after which the item is disposed of if undelivered. |
| `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 and are not configured in the submit request.
- `Letter` — Sends to a printing and enveloping provider (MRW). Requires prior provisioning by support and a `PostServiceProfile`. Supports optional delivery receipt and delivery attempt tracking.
- `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). The delivery-attempt and disposal options cannot be used, and `PostServiceProfile` is not required.


### `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`. 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`, and `Value`. Fields marked with `IsLookupKey: true` are indexed and surfaced in query results under `LookupKey`, concatenated with `::` if multiple values are present.

## Push notification payload

When an EviPost changes state, Namirial Notify sends a POST to `PushNotificationUrl` with the following JSON payload:

**Common fields:**

| Field | Description |
|  --- | --- |
| `Identifier` | Unique identifier of the event. |
| `Kind` | Event type (matches the state that triggered the notification). |
| `Date` | Timestamp of the event. |
| `EvidenceId` | Unique identifier of the EviPost. |
| `EvidenceType` | Always `eviPost`. |
| `Site` | Name of the issuer's site. |
| `Owner` | Name of the site user. |
| `OwnerEmail` | Email of the site user. |
| `AdditionalData` | Object containing event-specific fields (see below). |


**`AdditionalData` fields:**

| Field | Description |
|  --- | --- |
| `Sender` | Name of the sender. |
| `Recipient` | Name of the recipient. |
| `LookupKey` | Lookup key set at submission. |
| `State` | Current state name. |
| `CreationDate` | Submission date. |
| `ExtraData` | Value of `PushNotificationExtraData`, if set. |


For `Dispatched` and `Sent` events, `AdditionalData` also includes `TransmissionDetails`. For `Delivered`, it includes `Details`. For `Closed`, it includes `Outcome`.

**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": "Pruebas evicertia",
  "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`. For on-demand affidavits, the payload can include the request identifier in `AdditionalData.RequestId`.

**Example payload:**


```json
{
  "Identifier": "1234",
  "EvidenceId": "2aca3ea149f943879726a87000c1f704",
  "EvidenceType": "eviPost",
  "Kind": "AffidavitPublished",
  "Date": "2018-01-22T12:46:32.4830752+01:00",
  "Site": "pruebas",
  "Owner": "Pruebas evicertia",
  "OwnerEmail": "pruebas@evicertia.com",
  "AdditionalData": {
    "RequestId": "79726a87000c1f7042aca3ea149f9438",
    "AffidavitId": "000c1f7042aca3ea149f943879726a87",
    "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
- **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 →](/products/namirialnotify/apis/oas/evipost-api)

## Related

- [EviPost](/products/namirialnotify/services/evipost)
- [EviMail API](/products/namirialnotify/apis/evimail-api)
- [EviNotice API](/products/namirialnotify/apis/evinotice-api)
- [EviSMS API](/products/namirialnotify/apis/evisms-api)
- [API documentation](/products/namirialnotify/dev/api-documentation)
- [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)