# EviSMS API

REST API for submitting and querying certified SMS messages through Namirial Notify. EviSMS provides legally binding certified SMS delivery with configurable certification levels, delivery channels, and evidence collection options. For the public Namirial Notify API environments, this V1 service is exposed under the `/v1` base path. The `servers` entries below already include that public base path. Some lower-level technical artifacts may show the underlying route without the prefix. For customer integrations, use the public URLs produced by this specification.


Version: 1.0

## Servers

Production
```
https://api.evicertia.com/v1
```

Pre-production / QA
```
https://api.ecertia.com/v1
```

## Security

### basicAuth

Type: http
Scheme: basic

## Download OpenAPI description

[EviSMS API](https://docs.namirial.app/_bundle/products/namirialnotify/apis/oas/evisms-api.yaml)

## EviSMS

Certified SMS submission and query operations.

### Submit a certified SMS

 - [POST /EviSms/Submit](https://docs.namirial.app/products/namirialnotify/apis/oas/evisms-api/evisms/evismssubmit.md)

### Query certified SMS messages (GET)

 - [GET /EviSms/Query](https://docs.namirial.app/products/namirialnotify/apis/oas/evisms-api/evisms/evismsqueryget.md)

## EviSMS Batch

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

**Workflow:**
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. **Add recipients** (`POST .../Recipients`) — uploaded as a `text/csv` file.
4. **Start processing** by setting the batch `State` (via `PATCH`) once the batch is ready.

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

:::note Base path and HTTP QUERY method
Unlike the rest of the EviSMS v1 API, the batch endpoints are part of the **v2** API and live under the `/v2/EviSms/Batches` base path (not `/v1`).

The two list endpoints (`Batches` and `Batches/{BatchId}/Recipients`) use the HTTP `QUERY` method with their filters in a JSON request body. Because OpenAPI cannot express `QUERY`, they are documented as `GET` with the filter fields shown as query parameters — send the request with the HTTP `QUERY` verb and the fields in a JSON body.
:::


### Create an SMS batch

 - [POST /v2/EviSms/Batches](https://docs.namirial.app/products/namirialnotify/apis/oas/evisms-api/evisms-batch/evismsbatchcreate.md): Creates a new, empty SMS batch. Only a Description is required at creation; the message text, recipients, and options are set with the subsequent batch endpoints. Returns the BatchId used by all other batch operations.

### Query SMS batches (HTTP QUERY method)

 - [GET /v2/EviSms/Batches](https://docs.namirial.app/products/namirialnotify/apis/oas/evisms-api/evisms-batch/evismsbatchesquery.md): Lists SMS batches owned by the caller (or the caller's site), with cursor pagination.

This endpoint uses the HTTP QUERY method, not GET. OpenAPI cannot express the QUERY method, so it is shown here as a GET with the filter fields as query parameters. In practice, send an HTTP QUERY request with the fields in a JSON body (States, Cursor, Limit, SortBy, SortOrder, Direction, TextSearch).

### Get an SMS batch

 - [GET /v2/EviSms/Batches/{BatchId}](https://docs.namirial.app/products/namirialnotify/apis/oas/evisms-api/evisms-batch/evismsbatchget.md): Retrieves the full state of a batch, including its configured message template and processing progress.

### Update an SMS batch

 - [PATCH /v2/EviSms/Batches/{BatchId}](https://docs.namirial.app/products/namirialnotify/apis/oas/evisms-api/evisms-batch/evismsbatchpatch.md): Updates batch metadata and the message template options, including the SMS Text. All fields are optional; only the fields supplied are changed. Setting State transitions the batch (for example, to start processing). Setting ScheduledDate schedules the batch.

### Delete an SMS batch

 - [DELETE /v2/EviSms/Batches/{BatchId}](https://docs.namirial.app/products/namirialnotify/apis/oas/evisms-api/evisms-batch/evismsbatchdelete.md): Removes a previously created batch.

### Add batch recipients (CSV)

 - [POST /v2/EviSms/Batches/{BatchId}/Recipients](https://docs.namirial.app/products/namirialnotify/apis/oas/evisms-api/evisms-batch/evismsbatchrecipientspost.md): Adds recipients to the batch by uploading a text/csv file. The CSV uses ; as the column separator. Mandatory columns: phonenumber, legalname. Optional columns: lookupkey, evidenceaccesscontrolchallenge, evidenceaccesscontrolchallengeresponse. Custom per-recipient fields are added as extra columns prefixed with  (for example, orderid).

### Query batch recipients (HTTP QUERY method)

 - [GET /v2/EviSms/Batches/{BatchId}/Recipients](https://docs.namirial.app/products/namirialnotify/apis/oas/evisms-api/evisms-batch/evismsbatchrecipientsquery.md): Lists the recipients of a batch, with cursor pagination.

This endpoint uses the HTTP QUERY method, not GET. OpenAPI cannot express the QUERY method, so it is shown here as a GET with the filter fields as query parameters. In practice, send an HTTP QUERY request with the fields (Cursor, Limit, SortDirection) in a JSON body.

### Delete all batch recipients

 - [DELETE /v2/EviSms/Batches/{BatchId}/Recipients](https://docs.namirial.app/products/namirialnotify/apis/oas/evisms-api/evisms-batch/evismsbatchrecipientsdelete.md): Removes all recipients from the batch.