# EviSMS API

The EviSMS API lets you submit certified SMS and RCS messages, query the status of previously submitted messages, and manage SMS batches. Single-message and batch operations share HTTP Basic authentication and are documented together in the [interactive EviSMS reference](/it/products/namirialnotify/apis/oas/evisms-api).

- [Single-message operations](#endpoints): Submit and Query.
- [Batch operations](#batch-operations): create, query, configure, and delete batches; manage recipients.


## Environments

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


For the public Namirial Notify API environments, single-message operations use `/v1/EviSms/Submit` and `/v1/EviSms/Query`. Batch operations use `/v2/EviSms/Batches` and its child routes.

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](/it/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](/it/products/namirialnotify/dev/security-best-practices#credential-handling), [callback endpoint hardening](/it/products/namirialnotify/dev/security-best-practices#callback-endpoint-hardening), and [operational security checks](/it/products/namirialnotify/dev/security-best-practices#operational-security-checks-before-go-live).

## Idempotency

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

If the same token is submitted again after the original request completed with `200 OK`, the server returns `202 Accepted` with the original response body — the message 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

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

```json
{
  "responseStatus": {
    "errorCode": "ArgumentException",
    "message": "Text is required and cannot be empty.",
    "errors": [
      {
        "errorCode": "NotEmpty",
        "fieldName": "Text",
        "message": "Text is required and cannot be empty."
      }
    ]
  }
}
```

| 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 phone number format, or invalid field value |
| `401 Unauthorized` | Incorrect credentials or missing `Authorization` header |
| `403 Forbidden` | Account not provisioned for EviSMS |


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

## Endpoints

### Submit a certified SMS

```
POST /v1/EviSms/Submit
```

Submits a new certified SMS or RCS message. On success, returns an `eviId` that uniquely identifies the submitted message and can be used to query its status later.

**Required fields:** `Text`, `Recipient` (with `PhoneNumber`).

Optional fields include `IssuerName`, `LookupKey`, and `Options`. All fields within `Options` — including `CertificationLevel`, `DeliveryChannels`, and `TimeToLive` — are optional. `Recipient.LegalName` is also optional.

| Response | Description |
|  --- | --- |
| `200 OK` | Message accepted. Body contains `{ "eviId": "..." }`. |
| `202 Accepted` | Returned when an idempotent replay matches a previously `200 OK` submission. The original response body is returned unchanged. See [Idempotency](#idempotency) above. |
| `400 Bad Request` | Invalid request. The OpenAPI specification defines a `responseStatus` object with `errorCode`, `message`, and optional `errors`. |
| `401 Unauthorized` | Authentication failed. |
| `403 Forbidden` | The authenticated account lacks the required API permission for EviSMS. |


**Example request:**

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

{
  "LookupKey": "NOTIFICATION-67890",
  "Text": "You have a pending certified notification. Please confirm receipt.",
  "IssuerName": "Acme Corp",
  "Recipient": {
    "LegalName": "Alice Martin",
    "PhoneNumber": "+34612345678"
  },
  "Options": {
    "CertificationLevel": "Advanced_EU",
    "TimeToLive": 1440,
    "DeliveryChannels": ["SMS"],
    "PushNotificationUrl": "https://your-endpoint.example.com/callbacks/evisms",
    "PushNotificationFilter": ["Delivered", "Closed", "AffidavitPublished"],
    "AffidavitKinds": ["Submitted", "TransmissionResult", "DeliveryResult", "Closed"]
  }
}
```

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

```json
{
  "eviId": "87ffa214-e773-4bd5-9b8d-a8ef00fd80f8"
}
```

### Query certified SMS messages

```
GET /v1/EviSms/Query
```

Returns a list of certified SMS messages 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). |
| `WithLinkedId` | string (UUID) | Filter by linked ID. Leave affidavit and attachment data disabled. The legacy implementation uses deployment settings for omitted blob flags, with both defaults declared enabled. On legacy deployments, explicitly send `IncludeAffidavitBlobs=false` and `IncludeAttachmentBlobs=false`. The attachment flag applies only to legacy Query. |
| `OnState` | string | Filter by current state: `Draft`, `New`, `Ready`, `Sent`, `Dispatched`, `Delivered`, `Read`, `Closed`, or `Failed`. |
| `WithOutcome` | string | Filter by outcome. |
| `OrderResultsBy` | string | Sort field for results. Supported value: `CreationDate`. |
| `Limit` | integer | Maximum number of results to return. |
| `Offset` | integer | Number of results to skip. |
| `IncludeAffidavits` | boolean | Include affidavit entries. Set `IncludeAffidavitBlobs=false` to request metadata only. |
| `IncludeAffidavitBlobs` | boolean | Deprecated. When `true` with `IncludeAffidavits=true`, include each affidavit PDF as Base64 in `affidavits[].bytes`; blob queries are limited to one message. Set this to `false` for metadata-only results and use `/AffidavitsDownload` for new integrations. |


The current public EviSMS contract does not expose a `Replied` state or a
`RepliedOn` timestamp. EviSMS has no accept/reject commitment flow; use
[EviNotice](/it/products/namirialnotify/services/evinotice) when recipients must formally accept or
reject content. Some older technical artifacts retain reply-related members for
legacy compatibility; these members are not part of the current Query schema.

| Response | Description |
|  --- | --- |
| `200 OK` | Returns `{ "totalMatches": N, "results": [...] }`. |
| `401 Unauthorized` | Authentication failed. |


The default and maximum `Limit` are 100 for message results, 25 when including affidavit metadata without blobs, and 1 when including affidavit blobs. ASP.NET defaults `IncludeAffidavitBlobs` to `false`; legacy uses a deployment setting whose declared default is `true`. For metadata only, always send `IncludeAffidavits=true&IncludeAffidavitBlobs=false`.

This metadata-only request returns affidavit IDs without embedding PDFs. Pass the
returned affidavit `uniqueId` values to the shared
[`/AffidavitsDownload`](/it/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.

## Batch operations

Batch operations let you send the same certified SMS to many recipients as a single managed job.

:::note Base path
The batch endpoints are part of the **v2** API and live under the `/v2/EviSms/Batches` base path — not under the `/v1` base path used by the rest of the EviSMS API.
:::

The typical workflow is:

1. **Create** an empty batch with a `Description` — you receive a `BatchId`.
2. **Configure** the message and options (`PATCH .../{BatchId}`) — the SMS `Text`, certification level, callbacks, scheduling, and so on. EviSMS has no separate body or attachment endpoints; the message content is the `Text` field.
3. **Upload the recipient list** (`POST .../Recipients`) as a `text/csv` file. Each upload replaces the previous list.
4. **Submit the batch** via `PATCH` with `State: Submitted` and a future `ScheduledDate` in UTC.


Poll `GET .../{BatchId}` to follow progress (`SentCount`, `FailedCount`, `ProgressPercentage`). `SentCount` counts items submitted as individual EviSMS messages. Query those messages for carrier transmission or delivery. Batches use SMS; use single-message Submit for RCS and the `Read` affidavit. Batch lifecycle states are `Draft`, `Submitted`, `Scheduled`, `Processing`, `Processed`, `Invalid`, and `Failed`.

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

### Create an SMS batch

```
POST /v2/EviSms/Batches
```

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

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


| Response | Description |
|  --- | --- |
| `201 Created` | Returns `{ "BatchId": "<uuid>" }`. |
| `202 Accepted` | On ASP.NET, an idempotent replay returns the previously stored batch result. |
| `401 Unauthorized` | Authentication failed. |
| `403 Forbidden` | The site does not use by-submission billing or the account lacks the batch sender role. |


### Query SMS batches

```
QUERY /v2/EviSms/Batches
```

Lists SMS batches owned by the caller (or the caller's site), with cursor pagination. Filters are sent in a JSON request body: `States` (array), `Cursor`, `Limit` (required, 1–100), `SortBy` (`LastUpdated`/`ScheduledFor`/`StartedOn`), `SortOrder` (`Ascending`/`Descending`), `Direction` (`Forward`/`Backward`), `TextSearch`.

| Response | Description |
|  --- | --- |
| `200 OK` | Returns `{ "Cursor": "...", "HasMoreResults": bool, "Results": [...] }`. |
| `400 Bad Request` | Malformed request. |
| `401 Unauthorized` | Authentication failed. |


### Get an SMS batch

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

Retrieves the full state of a batch, including its configured message template (nested `EviSms`) and processing progress.

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


### Update an SMS batch

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

Updates supplied batch metadata and message template options, including the SMS `Text`. Blank values for text fields are ignored. To schedule a batch, send both the state transition and the scheduled date.

To submit a Draft or Invalid batch, supply a future UTC `ScheduledDate` with `State: Submitted`. The batch must have text, at least one recipient, a positive TTL, online retention between 1 and 20 years, and a valid certification level. API-created batches have no defaults for `TimeToLive`, `OnlineRetentionPeriod`, or `CertificationLevel`. Set them before submitting or in the same PATCH request. A Submitted or Scheduled batch can be returned to Draft before processing starts.

**Request fields:** `IssuerName`, `ScheduledDate`, `State`, `Description`, `Text`, `TimeToLive`, `CostCentre`, `CertificationLevel`, `AffidavitKinds`, `Language`, `AffidavitLanguage`, `OnlineRetentionPeriod`, `LtaStorage`, `PushNotificationUrl`, `PushNotificationFilter`, `PushNotificationExtraData`, `DeliveryAppearance`, `BatchPushNotificationUrl`, `OwnerNotificationTemplate`.

| Response | Description |
|  --- | --- |
| `200 OK` | Batch updated. |
| `400 Bad Request` | Invalid request. |
| `401 Unauthorized` | Authentication failed. |
| `403 Forbidden` | The site does not use by-submission billing. |
| `404 Not Found` | No batch with the given `BatchId` was found. |


### Delete an SMS batch

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

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


### Add batch recipients

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

Uploads the batch recipient list as a `text/csv` file (`Content-Type: text/csv`). Each upload replaces the previous list. Use `;` as the column separator. The upload supports up to 100,000 recipients.

- **Mandatory columns:** `phonenumber`, `legalname`
- **Optional columns:** `lookupkey`, `evidenceaccesscontrolchallenge`, `evidenceaccesscontrolchallengeresponse`
- **Custom fields:** add extra columns prefixed with `*` (for example, `*orderid`); they are surfaced per recipient as `ExtraFields`.


**Example request body:**

```
phonenumber;legalname;lookupkey;*orderid
+34600000000;Acme Corp;SMS-001;ORD-001
+34600000001;Beta Ltd;SMS-002;ORD-002
```

| Response | Description |
|  --- | --- |
| `200 OK` | Recipients accepted. No response body is returned. |
| `400 Bad Request` | The CSV is empty, invalid (for example, missing mandatory columns), or exceeds the recipient limit, or the batch cannot be edited. |
| `401 Unauthorized` | Authentication failed. |
| `404 Not Found` | No batch with the given `BatchId` was found. |


### Query batch recipients

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

Lists the recipients of a batch, with cursor pagination. Filters are sent in a JSON request body: `Cursor`, `Limit` (1–1000), `SortDirection` (`Ascending`/`Descending`).

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


### Delete all batch recipients

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

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


## States and outcomes

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

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

| State | Description |
|  --- | --- |
| `Draft` | Message is being prepared. |
| `New` | Message has been accepted by the platform. |
| `Ready` | Message is ready for dispatch. |
| `Dispatched` | The system has completed local processing; the message is ready to be sent to the telecommunications operator. |
| `Sent` | The SMS or RCS operator accepted the message for routing. |
| `Delivered` | Message was delivered to the recipient's device. |
| `Read` | Recipient opened the message (RCS only, where supported). |
| `Closed` | Message lifecycle is complete. |
| `Failed` | A processing, transmission, or delivery failure was recorded. A failed attempt can be retried or can trigger channel fallback without setting this state. Wait for `Closed` and check `Outcome` for the final result. |


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

| Outcome | Description |
|  --- | --- |
| `None` | No outcome determined yet. |
| `Certified` | Message certified with the configured certification level. |
| `Sent` | Message was sent. |
| `Delivered` | Message was delivered. |
| `Read` | Recipient opened the message (RCS only, where supported). |
| `Failed` | Delivery failed permanently. |


## Key request fields

### `IssuerName`

The legal name or short identifier for the sending organisation, recorded in the certification evidence. This is not the sender shown in the recipient's inbox — that sender is configured at the account level, separately from `IssuerName`.

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

### `DeliveryChannels`

An array specifying the delivery channels to use. Supported values: `RCS`, `SMS`. Omit the array or pass an empty array to use SMS. RCS must be enabled for the site. List each channel at most once, in the order you want them attempted. SMS uses a configurable segment limit; RCS is limited to 3,072 UTF-16 code units. If you choose both channels, the text must meet both limits.

### `TimeToLive`

The tracking window in minutes. Single-message Submit accepts 1–86,400 minutes. The API applies the configured default when you omit this field.

### `PushNotificationFilter`

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

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

### `AffidavitKinds`

The set of evidence events for which affidavits should be generated. Supported values: `Submitted`, `SubmittedAdvanced`, `TransmissionResult`, `DeliveryResult`, `Read`, `Closed`, `ClosedAdvanced`, `Complete`, `CompleteAdvanced`, `Event`. Request `Read` only for single messages with RCS enabled in `DeliveryChannels`.

### `EvidenceAccessControlMethod`

Controls how recipients access the evidence record. Supported values: `Public`, `Challenge`, `AutoChallenge`. When omitted, the account's configured default method applies.

`Challenge` requires the corresponding `EvidenceAccessControlChallenge` and `EvidenceAccessControlChallengeResponse` fields to be present. `AutoChallenge` uses a platform-generated challenge based on known recipient data and does not require those fields.

## OpenAPI specification

The OpenAPI 3.0.3 specification for the EviSMS 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/EviSms/Submit`) — request and response schemas for SMS and RCS submissions, validation rules, and HTTP status codes
- **Query endpoint** (`GET /v1/EviSms/Query`) — pagination parameters, filtering options, state and outcome enums, and result structure
- **Batch endpoints** (`/v2/EviSms/Batches`) — all 8 operations for batch creation, queries, configuration, deletion, and recipients
- **Authentication** — HTTP Basic authentication requirements
- **Error handling** — error response structure with error codes and diagnostic information
- **Data types** — schema definitions for documented messages, recipients, delivery channels, and affidavits


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

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

## Related

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