# Account

> Manage the registered domain, API keys and webhook endpoints, read usage, run conformance checks and generate integration prompts.

Source: https://esigncomply.com/docs/api/account

These endpoints manage the account side of an integration: the registered domain, the keys, the webhook endpoints, usage, conformance runs and generated prompts. Every checklist step in the dashboard has an equivalent call here, so an AI coding tool that holds a key can complete setup. You create the account and accept the terms once, with no card. After that your AI agent can do the rest: create keys, register documents, build the flow, verify the domain and go live.

A secret key is bound to one domain and one environment (test or live). Calls on this page act on that domain and that environment. Unless a section says otherwise, they need a `full_access` key.

An agent that holds no key yet starts with the [agent account API](https://esigncomply.com/docs/api/agent.md): with an agent token it reads the account state, creates its keys, registers and verifies the domain and goes live.

| Method and path | Key | Purpose |
|---|---|---|
| `POST /v1/domains` | Secret (`full_access`) | Register the domain for this subscription. |
| `GET /v1/domains` | Secret (`full_access`) | List the key's domain. |
| `GET /v1/domains/{id}` | Secret (`full_access`) | Read the domain and its verification instructions. |
| `POST /v1/domains/{id}/verify` | Secret (`full_access`) | Run a verification check now. |
| `PATCH /v1/domains/{id}` | Secret (`full_access`) | Set the certificate spend limit or the test origins. |
| `POST /v1/api-keys` | Secret (`full_access`) | Create a key. The secret is shown once. |
| `GET /v1/api-keys` | Secret (`full_access`) | List keys. |
| `DELETE /v1/api-keys/{id}` | Secret (`full_access`) | Revoke a key. |
| `POST /v1/webhooks` | Secret (`full_access`) | Add a webhook endpoint. The signing secret is shown once. |
| `GET /v1/webhooks` | Secret (`full_access`) | List endpoints. |
| `PATCH /v1/webhooks/{id}` | Secret (`full_access`) | Change or disable an endpoint. |
| `DELETE /v1/webhooks/{id}` | Secret (`full_access`) | Remove an endpoint. |
| `POST /v1/webhooks/{id}/test` | Secret (`full_access`) | Send a signed test event now. |
| `GET /v1/webhooks/deliveries` | Secret (`full_access`) | Delivery history with response codes. |
| `GET /v1/usage` | Secret (any permission) | Events, quota, certificates and storage for the current period. |
| `POST /v1/conformance/runs` | Secret (`full_access`, `recording_access`) | Gather the conformance findings of recent ceremonies into one report. |
| `GET /v1/conformance/runs` | Secret (any permission) | List recent conformance runs. |
| `GET /v1/conformance/runs/{id}` | Secret (any permission) | Read a conformance run. |
| `POST /v1/prompts/generate` | Secret (`full_access`) | Generate the integration prompt from wizard selections. |

## Register a domain

`POST /v1/domains`

Key: secret key with `full_access`.

Registers the domain for the key's subscription. One subscription covers one registered domain and every subdomain. You can enter a host or a URL: Esign Comply computes the registrable domain with the Public Suffix List, so `app.example.com` registers `example.com`. A host on a shared platform suffix, such as `myapp.vercel.app`, is registered on its own and verifies by a well-known file because DNS records cannot be added there. Moving later to a custom domain is a domain change.

Test keys work on `localhost`, `127.0.0.1` and listed preview hosts without a domain. You need a verified domain to go live. See the [domains guide](https://esigncomply.com/docs/guides/domains.md).

**Request fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `domain` | string | Yes | A host name or URL, for example `app.example.com`. Localhost and IP addresses cannot be registered. |
| `region` | string | No | `us` or `eu`. Sets where evidence is stored and which API host the keys use. Chosen here and fixed afterwards. The Free plan records live in `us` only: live recording in `eu` needs a paid plan. |

**Example request**

```bash
curl https://esigncomply.com/v1/domains \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "app.example.com", "region": "us" }'
```

**Example response**

`201 Created`

```json
{
  "object": "domain",
  "id": "dom_4Kx9",
  "domain": "example.com",
  "entered_host": "app.example.com",
  "region": "us",
  "status": "pending",
  "verification": {
    "method": "dns",
    "type": "TXT",
    "name": "_esigncomply.example.com",
    "host": "_esigncomply",
    "value": "esc-verify=<token>"
  },
  "registered_at": "2026-11-21T15:10:02.118Z",
  "verified_at": null,
  "last_checked_at": null,
  "lapsed_at": null,
  "test_origins": [],
  "api_url": "https://esigncomply.com/v1",
  "created_at": "2026-11-20T09:00:00.000Z"
}
```

Publish the record shown in `verification`, then wait for the automatic check or call the verify endpoint. For a platform host the `verification` object is:

```json
{
  "method": "file",
  "url": "https://myapp.vercel.app/.well-known/esigncomply.txt",
  "content": "<token>"
}
```

Serve `content` as the body of that URL over HTTPS, without a redirect to another host.

**Errors**

- [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request) `400`: the value is not a host name, is localhost or an IP address, the region is not available, or the registered domain was already changed within the last 12 months.
- [`domain_already_registered`](https://esigncomply.com/docs/api/errors.md#domain_already_registered) `409`: the domain is attached to another subscription.
- [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable) `403`: the region is not on the plan.

## The domain object

| Field | Type | Description |
|---|---|---|
| `id` | string | `dom_...` |
| `domain` | string or null | The registrable domain. `null` until a domain is registered (test mode works without one). |
| `entered_host` | string or null | The host as entered. |
| `region` | string | `us` or `eu`. Fixed after registration. |
| `status` | string | `not_started`, `pending`, `verified`, `failed` (not found within 72 hours) or `lapsed` (previously verified, now failing). |
| `verification` | object or null | DNS method: `method: "dns"`, `type: "TXT"`, `name`, `host`, `value`. File method: `method: "file"`, `url`, `content`. |
| `registered_at`, `verified_at`, `last_checked_at`, `lapsed_at` | timestamp or null | Verification history. |
| `test_origins` | string[] | Preview hosts on which test keys also work. |
| `api_url` | string | The base URL for this domain's region. |
| `certificate_spend_limit` | integer | Monthly certificate spend limit in cents. Returned by the retrieve and update calls. |
| `created_at` | timestamp | When the domain slot was created. |

Checks run every minute for the first hour, then every 15 minutes for 72 hours, then daily. The record must stay in place after verification: three consecutive failed daily checks set `lapsed`, live recording continues for 14 days with warnings, and then new live sessions are refused until verification is restored. Existing records are unaffected. The `domain.verified` and `domain.verification_lapsed` webhooks report status changes.

## List domains

`GET /v1/domains`

Key: secret key with `full_access`.

Returns a list with the one domain the key belongs to. Use it to find the domain ID.

**Example request**

```bash
curl https://esigncomply.com/v1/domains \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

**Example response**

`200 OK`

```json
{
  "object": "list",
  "data": [
    { "object": "domain", "id": "dom_4Kx9", "domain": "example.com", "region": "us", "status": "verified" }
  ],
  "has_more": false
}
```

The item is the full domain object. The example is shortened.

## Retrieve a domain

`GET /v1/domains/{id}`

Key: secret key with `full_access`. `{id}` must be the key's own domain.

**Example request**

```bash
curl https://esigncomply.com/v1/domains/dom_4Kx9 \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

**Example response**

`200 OK` with the [domain object](#the-domain-object), including `certificate_spend_limit`.

**Errors**

- [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found): `{id}` is not the key's own domain.

## Verify a domain

`POST /v1/domains/{id}/verify`

Key: secret key with `full_access`. No request body.

Runs one check now instead of waiting for the next automatic check, and moves the status. The DNS method looks up the TXT record on two public resolvers, and both must return the expected value. The file method fetches the well-known URL over HTTPS.

**Example request**

```bash
curl -X POST https://esigncomply.com/v1/domains/dom_4Kx9/verify \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

**Example response**

`200 OK`. The domain object plus `check`.

```json
{
  "object": "domain",
  "id": "dom_4Kx9",
  "domain": "example.com",
  "region": "us",
  "status": "verified",
  "verified_at": "2026-11-21T15:14:40.220Z",
  "last_checked_at": "2026-11-21T15:14:40.220Z",
  "check": {
    "ok": true,
    "method": "dns",
    "detail": {
      "name": "_esigncomply.example.com",
      "expected": "esc-verify=<token>",
      "cloudflare": ["esc-verify=<token>"],
      "google": ["esc-verify=<token>"],
      "cloudflare_ok": true,
      "google_ok": true
    }
  }
}
```

`check` is `null` when no domain is registered yet. When `check.ok` is `false`, `detail` shows what each resolver returned (or the HTTP status of the file URL), so you can see whether the record has not propagated or has the wrong value.

## Update a domain

`PATCH /v1/domains/{id}`

Key: secret key with `full_access`. `{id}` must be the key's own domain. Send at least one field.

**Request fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `certificate_spend_limit` | integer | No | Monthly limit for certificate charges, in cents, from `0` to `500000`. The default is `20000` ($200). `0` switches paid certificates off. Higher limits are set on request. |
| `test_origins` | string[] | No | Up to 25 preview hosts on which test keys also work, for example `myapp-git-main.vercel.app`. A listed host also covers its subdomains. Replaces the list. |

**Example request**

```bash
curl -X PATCH https://esigncomply.com/v1/domains/dom_4Kx9 \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "certificate_spend_limit": 50000 }'
```

**Example response**

`200 OK`

```json
{
  "object": "domain",
  "id": "dom_4Kx9",
  "domain": "example.com",
  "region": "us",
  "status": "verified",
  "test_origins": [],
  "certificate_spend_limit": 50000
}
```

The example is shortened. A certificate request that would pass the limit returns [`certificate_spend_limit_reached`](https://esigncomply.com/docs/api/errors.md#certificate_spend_limit_reached). See [certificates](https://esigncomply.com/docs/api/certificates.md).

**Errors**

- [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request): neither field was sent, the limit is out of range, or a test origin is not a host name.

## Create an API key

`POST /v1/api-keys`

Key: secret key with `full_access`.

Creates a key for the same domain. The secret is in the response once. Only a prefix and a SHA-256 hash are stored, so it cannot be shown again. This response is never kept for idempotent replay.

Key format: `esc_<test|live>_<us|eu>_<random>`. The mode and region are part of the key, so SDKs can choose the host. A key works only against the region of its domain: the other region returns [`region_mismatch`](https://esigncomply.com/docs/api/errors.md#region_mismatch) with the correct host. Each key is pinned to the API version that was current when it was created.

**Request fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | A label, up to 80 characters. |
| `permission` | string | No | `full_access`, `recording_access` (default) or `read_only`. |
| `mode` | string | No | `test` or `live`. Defaults to the mode of the calling key. A test key cannot create a live key. |

| Permission | What the key can do |
|---|---|
| `full_access` | Every endpoint. |
| `recording_access` | Create and read sessions; read record status, metadata and the receipt for server-side confirmation; register and read documents; read profiles; create supplements and files; read signer status; read guidance and usage; run conformance checks. No evidence report, evidence package, certificate or export access. |
| `read_only` | Read documents, profiles, sessions, full records, evidence reports and packages, certificates, supplements, signer status, guidance, usage and conformance runs. No writes. |

Use `recording_access` for the key your application runs with. A leaked application key then cannot export stored evidence or create a charge.

**Example request**

```bash
curl https://esigncomply.com/v1/api-keys \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Preview deployments", "permission": "recording_access" }'
```

**Example response**

`201 Created`

```json
{
  "object": "api_key",
  "id": "key_2bQ1",
  "name": "Preview deployments",
  "livemode": false,
  "permission": "recording_access",
  "prefix": "esc_test_us_4f2a9K…",
  "api_version": "2026-11-21",
  "last_used_at": null,
  "revoked_at": null,
  "created_at": "2026-11-21T15:20:11.004Z",
  "key": "esc_test_us_...",
  "note": "This key is shown once. Only a prefix and a SHA-256 hash are stored."
}
```

Store `key` as a server environment variable (`ESIGNCOMPLY_API_KEY`). Never print it, commit it or send it to a browser. See the [credential rules](https://esigncomply.com/auth.md).

**Errors**

- [`insufficient_permission`](https://esigncomply.com/docs/api/errors.md#insufficient_permission) `403`: a test key asked for a live key, or the calling key is not `full_access`.
- [`domain_not_verified`](https://esigncomply.com/docs/api/errors.md#domain_not_verified) `403`: a live key was requested before the domain is verified.

## List API keys

`GET /v1/api-keys`

Key: secret key with `full_access`.

Lists the keys of the domain in the calling key's mode, newest first, revoked keys included. The secret is never returned.

**Example request**

```bash
curl https://esigncomply.com/v1/api-keys \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

**Example response**

`200 OK`

```json
{
  "object": "list",
  "data": [
    {
      "object": "api_key",
      "id": "key_2bQ1",
      "name": "Preview deployments",
      "livemode": false,
      "permission": "recording_access",
      "prefix": "esc_test_us_4f2a9K…",
      "api_version": "2026-11-21",
      "last_used_at": "2026-11-21T16:02:44.000Z",
      "revoked_at": null,
      "created_at": "2026-11-21T15:20:11.004Z"
    }
  ],
  "has_more": false
}
```

## Revoke an API key

`DELETE /v1/api-keys/{id}`

Key: secret key with `full_access`.

Revokes the key. Requests with it then return [`invalid_api_key`](https://esigncomply.com/docs/api/errors.md#invalid_api_key). Rotate a key whenever it may have been exposed: create a new one, deploy it, then revoke the old one.

**Example request**

```bash
curl -X DELETE https://esigncomply.com/v1/api-keys/key_2bQ1 \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

**Example response**

`200 OK`

```json
{ "object": "api_key", "id": "key_2bQ1", "revoked": true }
```

**Errors**

- [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found): no such key on this domain, or it is already revoked.

## Create a webhook endpoint

`POST /v1/webhooks`

Key: secret key with `full_access`.

Adds an endpoint in the calling key's environment: a test key creates a test endpoint, a live key a live endpoint. The signing secret is in the response once. This response is never kept for idempotent replay. For event types, the delivery format and signature verification, read [webhooks](https://esigncomply.com/docs/api/webhooks.md).

**Request fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | string | Yes | Must use HTTPS. In test mode `http://localhost` and `http://127.0.0.1` are also accepted. A live endpoint must be reachable from the public internet. |
| `events` | string[] | No | Event types to receive. Defaults to `["*"]` (all events). An unknown type is refused so that typos do not go unnoticed. |
| `description` | string | No | Up to 200 characters. |

Endpoints per environment: Free 1, Starter 3, Unlimited 10, Enterprise not capped. Each endpoint is pinned to the API version in force when it was created. A new event type reaches an endpoint only if it subscribes to that type or to all events.

**Example request**

```bash
curl https://esigncomply.com/v1/webhooks \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/api/esigncomply/webhook",
    "events": ["record.completed", "record.disputed", "signer.reacceptance_required"],
    "description": "Production app"
  }'
```

**Example response**

`201 Created`

```json
{
  "object": "webhook_endpoint",
  "id": "wh_6Tn3",
  "livemode": false,
  "url": "https://app.example.com/api/esigncomply/webhook",
  "description": "Production app",
  "events": ["record.completed", "record.disputed", "signer.reacceptance_required"],
  "status": "enabled",
  "api_version": "2026-11-21",
  "failing_since": null,
  "created_at": "2026-11-21T15:30:00.512Z",
  "secret": "whsec_..."
}
```

Store `secret` as `ESIGNCOMPLY_WEBHOOK_SECRET` on your server.

**Errors**

- [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request) `400`: the URL is not valid or not HTTPS, a live URL points at a private address, or `events` names an unknown type.
- [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable) `403`: the plan's endpoint limit is reached.

## List webhook endpoints

`GET /v1/webhooks`

Key: secret key with `full_access`.

**Example request**

```bash
curl https://esigncomply.com/v1/webhooks \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

**Example response**

`200 OK`

```json
{
  "object": "list",
  "data": [
    {
      "object": "webhook_endpoint",
      "id": "wh_6Tn3",
      "livemode": false,
      "url": "https://app.example.com/api/esigncomply/webhook",
      "description": "Production app",
      "events": ["record.completed", "record.disputed", "signer.reacceptance_required"],
      "status": "enabled",
      "api_version": "2026-11-21",
      "failing_since": null,
      "created_at": "2026-11-21T15:30:00.512Z"
    }
  ],
  "has_more": false
}
```

`failing_since` is set while deliveries to the endpoint keep failing. An endpoint that fails continuously for 5 days is set to `disabled` and the owners are emailed.

## Update a webhook endpoint

`PATCH /v1/webhooks/{id}`

Key: secret key with `full_access`.

**Request fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | string | No | Same rules as on creation. |
| `events` | string[] | No | Replaces the subscription list. |
| `description` | string | No | Up to 200 characters. |
| `status` | string | No | `enabled` or `disabled`. Setting `enabled` clears `failing_since`. |

**Example request**

```bash
curl -X PATCH https://esigncomply.com/v1/webhooks/wh_6Tn3 \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["*"], "status": "enabled" }'
```

**Example response**

`200 OK` with the `webhook_endpoint` object, without `secret`.

**Errors**

- [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found): no such endpoint in this environment.
- [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request): the URL or an event type is not valid.

## Delete a webhook endpoint

`DELETE /v1/webhooks/{id}`

Key: secret key with `full_access`.

Removes the endpoint and its signing secret.

**Example request**

```bash
curl -X DELETE https://esigncomply.com/v1/webhooks/wh_6Tn3 \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

**Example response**

`200 OK`

```json
{ "object": "webhook_endpoint", "id": "wh_6Tn3", "deleted": true }
```

## Send a test event

`POST /v1/webhooks/{id}/test`

Key: secret key with `full_access`. No request body.

Sends one signed event of type `webhook.test` to the endpoint now and reports what it answered. Use it to check your signature verification before real events arrive. Handlers ignore event types they do not know and return `200`.

**Example request**

```bash
curl -X POST https://esigncomply.com/v1/webhooks/wh_6Tn3/test \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

**Example response**

`200 OK`

```json
{
  "object": "webhook_test",
  "endpoint_id": "wh_6Tn3",
  "webhook_id": "whe_3Fd8",
  "delivered": true,
  "response_status": 200,
  "response_excerpt": "ok"
}
```

`delivered` is `true` for a 2xx answer within 10 seconds. `response_excerpt` holds the first 300 characters of the response body, or the network error.

## List webhook deliveries

`GET /v1/webhooks/deliveries`

Key: secret key with `full_access`.

Delivery history for the key's environment, with response codes. The CLI's `webhooks listen` command uses it to forward test deliveries to localhost.

**Query parameters**

| Parameter | Description |
|---|---|
| `endpoint` | Only deliveries to this endpoint ID. |
| `status` | `pending`, `delivered` or `failed`. |
| `since` | RFC 3339 timestamp. Deliveries created after it, oldest first. Without it, newest first. |
| `include` | `payload` adds the delivered event body to each item. |
| `limit` | 1 to 100, default 20. |

**Example request**

```bash
curl "https://esigncomply.com/v1/webhooks/deliveries?endpoint=wh_6Tn3&status=failed" \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

**Example response**

`200 OK`

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "webhook_delivery",
      "id": "whd_7Qa1",
      "endpoint_id": "wh_6Tn3",
      "webhook_id": "whe_9Lm4",
      "type": "record.completed",
      "status": "failed",
      "attempts": 4,
      "response_status": 500,
      "response_excerpt": "Internal Server Error",
      "created_at": "2026-11-21T15:03:21.002Z",
      "delivered_at": null,
      "last_attempt_at": "2026-11-21T15:46:02.330Z"
    }
  ]
}
```

`webhook_id` is the value of the `webhook-id` header. It is the same for every retry of one event, so handlers can be idempotent on it.

## Get usage

`GET /v1/usage`

Key: secret key with any permission.

Returns what the subscription has used in the current period. Live events are counted per subscription year on paid plans and per UTC calendar month on the Free plan. The call is never metered, which also makes it the simplest way to check that a key works.

**Example request**

```bash
curl https://esigncomply.com/v1/usage \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

**Example response**

`200 OK`

```json
{
  "object": "usage",
  "plan": "starter",
  "plan_name": "Starter",
  "subscription_status": "active",
  "period": { "start": "2026-03-01T00:00:00.000Z", "end": "2027-03-01T00:00:00.000Z" },
  "events": {
    "period": "year",
    "period_start": "2026-03-01T00:00:00.000Z",
    "resets_at": "2027-03-01T00:00:00.000Z",
    "used": 1612,
    "open_sessions": 3,
    "quota": 2000,
    "event_packs": 0,
    "allowance": 2000,
    "remaining": 388,
    "locked": false,
    "locked_since": null,
    "level": "notice_80",
    "event_packs_enabled": false,
    "over_quota_since": null
  },
  "test_events": { "used_this_month": 214, "quota_per_month": 5000 },
  "certificates": {
    "included": 0,
    "used": 0,
    "remaining": 0,
    "charged_units": 2,
    "resets_at": "2027-03-01T00:00:00.000Z",
    "charged_month_to_date": 4000,
    "spend_limit": 20000,
    "unit_amount": 2000
  },
  "verifications": { "sms_used": 12, "sms_included": 500 },
  "supplements": { "count": 37, "storage_used_bytes": 1830400, "storage_allowance_bytes": 2147483648 }
}
```

| Field | Description |
|---|---|
| `plan`, `plan_name` | The plan id: `sandbox`, `starter`, `unlimited` or `enterprise`. `sandbox` is the id of the Free plan. `plan_name` is the name a person reads, for example `"Free"`. |
| `subscription_status` | `active`, `incomplete`, `past_due` or `canceled`. |
| `period` | The subscription year. Paid plans count live events, certificates and SMS verifications per subscription year. On Free, live events are counted per UTC month: see `events.period`. |
| `events.period`, `events.period_start`, `events.resets_at` | The period live events are counted in: `"month"` on Free, `"year"` on paid plans. Then the start of that period and the time the count starts again: the first of the next month (UTC) on Free, the end of the subscription period on paid plans. `resets_at` is `null` while the account is locked, because a locked account gets no new allowance on its own. It can also be `null` on a paid plan with no renewal date set. |
| `events.used` | Sealed live records in that period: this UTC month on Free, this subscription year on paid plans. One signer completing one ceremony is one event. Test records, verifications, downloads, supplements and certificates are not counted. This is the true count. It can be higher than `events.allowance`. |
| `events.open_sessions` | Live sessions that are open and not expired, on every plan. Informational: it is not part of `used` and is not subtracted from `remaining`. |
| `events.quota`, `events.event_packs`, `events.allowance` | The plan quota, the event packs bought this year, and the limit: quota plus 1,000 per pack. On Free, `quota` and `allowance` are `10`. On Unlimited and Enterprise, `quota` and `allowance` are `null`: there is no limit. |
| `events.remaining` | `allowance - used`, never below `0`. `null` on Unlimited and Enterprise. |
| `events.locked` | Boolean. `true` from the moment the account locks, when `used` reaches `allowance`, until payment. The lock does not lift on its own. On Free, upgrading to a paid plan removes it. On Starter, upgrading to Unlimited, adding an event pack or paying for renewal removes it. Always `false` on Unlimited and Enterprise. |
| `events.locked_since` | The time the lock was set, or `null` when the account is not locked. |
| `events.level` | `ok`, `notice_50`, `notice_80`, `notice_90` or `limit_reached`: the highest of 50%, 80%, 90% and 100% of the allowance that `used` has reached. The values are the same on Free and Starter. Always `ok` on Unlimited and Enterprise. |
| `events.event_packs_enabled` | Whether an event pack is bought automatically when the limit is reached. Starter only. |
| `events.over_quota_since` | Always `null`. Kept so that existing clients do not break. |
| `test_events` | Test-mode events this calendar month against the plan's monthly allowance. |
| `certificates.included`, `used`, `remaining`, `resets_at` | The certificate allowance for the subscription year. `null` means not capped. |
| `certificates.charged_units`, `charged_month_to_date`, `spend_limit`, `unit_amount` | Units charged this year, this month's certificate charges, the monthly limit and the unit price, in cents. |
| `certificates.live_available` | `false` on the Free plan, where certificates exist for test records only. `true` on paid plans. |
| `verifications` | SMS verifications used and included this year. Email verification is not limited. |
| `supplements` | Supplements on file, bytes of supplement files stored, and the storage allowance (`null` when contracted). |

On the Free plan live events are counted per UTC calendar month. The same call with a Free key, abbreviated to the fields that differ:

```json
{
  "object": "usage",
  "plan": "sandbox",
  "plan_name": "Free",
  "subscription_status": "active",
  "events": {
    "period": "month",
    "period_start": "2026-11-01T00:00:00.000Z",
    "resets_at": "2026-12-01T00:00:00.000Z",
    "used": 6,
    "open_sessions": 1,
    "quota": 10,
    "allowance": 10,
    "remaining": 4,
    "locked": false,
    "locked_since": null,
    "level": "notice_50"
  },
  "test_events": { "used_this_month": 42, "quota_per_month": 500 }
}
```

Six live events are complete this month, so four are left and `level` is `notice_50`. One live session is open. It is reported in `open_sessions` and is not subtracted from `remaining`. The account is not locked, so the count starts again at `resets_at`.

Free covers 10 live signatures a month. If you use all 10 in a month, the account locks until you upgrade to a paid plan. It does not unlock at the start of the next month. Past the limit, new live signatures can be refused, so upgrade before you get there.

Starter covers 2,000 live signature events a year. At 2,000 the account locks until you pay: upgrade to Unlimited, add an event pack, or renew. Past the limit, new live signatures can be refused, so upgrade before you get there.

While an account is locked, `locked` is `true`, `locked_since` holds the time of the lock, `level` is `limit_reached` and `resets_at` is `null`. A refused request returns `402` [`quota_exhausted`](https://esigncomply.com/docs/api/errors.md#quota_exhausted). See [Free plan limits](https://esigncomply.com/docs/guides/test-mode.md#free-plan-limits) and [Starter limits](https://esigncomply.com/docs/guides/test-mode.md#starter-limits).

On Unlimited and Enterprise there is no limit: `quota`, `allowance` and `remaining` are `null`, `locked` is `false` and `level` is `ok`.

The [`usage.threshold_reached`](https://esigncomply.com/docs/api/webhooks.md#usage-and-conformance) webhook is sent at 50%, 80%, 90% and 100% of the limit, on Free and Starter. Its `threshold` is `50`, `80`, `90` or `100`. Owners and admins get an email at the same four points. Sessions already created still complete. See the [pricing summary](https://esigncomply.com/pricing.md) for what counts as a signature event.

## Create a conformance run

`POST /v1/conformance/runs`

Key: secret key with `full_access` or `recording_access`.

Every ceremony is evaluated against the [conformance rules](https://esigncomply.com/docs/conformance.md) as its events arrive, and those findings come back on each event response. A run gathers the findings of recent ceremonies in the key's environment into one report: each rule, its status, what was measured, a plain-language fix and the pages it was seen on. Use it before go-live or in continuous integration. The run is computed in the request and returned with `status: "completed"`.

For each session, rule and slot only the latest result counts, so a later pass on a repaired page supersedes an earlier failure.

Findings are advisory and describe measurable design facts. They are not a statement that a flow is lawful or enforceable.

**Request fields**

All fields are optional. An empty body covers the last 24 hours.

| Field | Type | Required | Description |
|---|---|---|---|
| `session_ids` | string[] | No | Up to 200 session IDs to report on. When sent, `since` is ignored. |
| `since` | timestamp | No | Include results created after this time. Default: 24 hours ago. |
| `url` | string | No | Only results recorded on this exact page URL (the session's `context.url`). |
| `limit` | integer | No | Caps how many recent results are read, 1 to 500. Default 200. |

**Example request**

```bash
curl https://esigncomply.com/v1/conformance/runs \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "http://localhost:3000/signup", "since": "2026-11-21T00:00:00Z" }'
```

**Example response**

`201 Created`

```json
{
  "object": "conformance_run",
  "id": "cfr_5Jk2",
  "livemode": false,
  "status": "completed",
  "rules_version": "2026.11.2",
  "summary": {
    "sessions": 4,
    "rules_evaluated": 9,
    "block": 0,
    "warn": 1,
    "pass": 8,
    "status": "warn",
    "since": "2026-11-21T00:00:00.000Z"
  },
  "findings": [
    {
      "rule": "CR-05",
      "title": "Document link contrast",
      "status": "warn",
      "state": "enforce",
      "counts": { "pass": 3, "warn": 1, "block": 0 },
      "message": "Document link contrast against surrounding text is 1.5 to 1; at least 3 to 1 is expected, in addition to any underline.",
      "measurement": { "contrast_ratio": 1.5, "underlined": true, "font_px": 14, "link_visible": true },
      "fix": "Give document links a colour that differs from the surrounding text by a contrast ratio of at least 3 to 1, and keep them underlined.",
      "maps_to": ["US-11"],
      "pages": ["http://localhost:3000/signup"],
      "example_session": "ses_5nWq",
      "doc_url": "https://esigncomply.com/docs/conformance#cr-05"
    }
  ],
  "markdown": "# Esign Comply conformance run cfr_5Jk2\n\nFindings are advisory and describe measurable design facts. ...",
  "note": "Findings are advisory and describe measurable design facts. They are not a statement that a flow is lawful or enforceable.",
  "created_at": "2026-11-21T16:20:00.118Z"
}
```

The example shows one of the nine findings.

| Field | Description |
|---|---|
| `summary` | Sessions covered, rules evaluated, the number of rules at `block`, `warn` and `pass`, the overall `status` (the most severe) and the `since` bound used. |
| `findings[]` | One entry per rule, most severe first. `status` is the most severe result for the rule; `counts` splits the sessions by result. `state` is `enforce` (can refuse a live record) or `advise` (measured and stored only). `message`, `measurement` and `fix` come from a failing example when there is one. `maps_to` lists the pack rules behind the check. `pages` lists up to 10 page URLs. `doc_url` points at the rule in the conformance reference. |
| `markdown` | The failing findings as Markdown, ready to paste back into an AI coding tool. |
| `rules_version` | The rule-set version the results were evaluated under. |

Test mode never blocks on a finding: it reports every finding so the page can be repaired. In live mode a `block` finding in the `enforce` state stops sealing. The `conformance.run_completed` webhook is sent with `run_id`, `status`, `block` and `warn`.

For the active check that drives your pages in a headless browser at three viewport sizes and then asks for a run, use the CLI: `npx esigncomply check --url http://localhost:3000/signup`. See the [CLI reference](https://esigncomply.com/docs/sdk/cli.md).

**Errors**

- [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request): a field has the wrong type or is out of range.
- [`insufficient_permission`](https://esigncomply.com/docs/api/errors.md#insufficient_permission): a `read_only` key cannot create a run.

## List conformance runs

`GET /v1/conformance/runs`

Key: secret key with any permission.

Returns the 20 most recent runs in the key's environment, newest first. Each item is the full `conformance_run` object.

**Example request**

```bash
curl https://esigncomply.com/v1/conformance/runs \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

**Example response**

`200 OK`

```json
{
  "object": "list",
  "data": [
    { "object": "conformance_run", "id": "cfr_5Jk2", "livemode": false, "status": "completed", "rules_version": "2026.11.2", "created_at": "2026-11-21T16:20:00.118Z" }
  ],
  "has_more": false
}
```

The example is shortened.

## Retrieve a conformance run

`GET /v1/conformance/runs/{id}`

Key: secret key with any permission.

**Example request**

```bash
curl https://esigncomply.com/v1/conformance/runs/cfr_5Jk2 \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

**Example response**

`200 OK` with the `conformance_run` object shown above.

**Errors**

- [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found): no such run in this domain and environment.

## Generate a prompt

`POST /v1/prompts/generate`

Key: secret key with `full_access`.

Generates the integration prompt that the dashboard wizard produces, so prompts can be created in continuous integration or by an AI coding tool. Prompts are assembled from reviewed, versioned blocks. No language model writes prompt text at generation time, and the same selections always produce the same prompt.

Generating a prompt creates the ceremony profiles for the selected use cases, or reuses a profile whose name and settings already match (an existing profile is never changed), and writes their IDs, the document IDs and the API host for the domain's region into the prompt. The prompt never contains a key. It names the environment variables `ESIGNCOMPLY_API_KEY` and `ESIGNCOMPLY_WEBHOOK_SECRET`.

**Request fields**

The body carries the wizard selections. The jurisdiction fields have the same meaning as on a profile:

| Field | Type | Description |
|---|---|---|
| `jurisdictions` | string[] | Pack codes in any combination, for example `["US-FED", "US-CA", "US-NY"]`. Any state pack adds `US-FED`. |
| `jurisdiction_mode` | string | `auto` (default: by signer location), `strictest` (always apply every selected pack) or `explicit` (named on each session). |
| `on_unknown_region` | string | `strictest` (default), `base_only` or `reject`: what happens when a U.S. signer's state is unknown. |
| `governing_law` | string | A pack code or another jurisdiction named in your documents. |

The other selections mirror the wizard steps:

| Selection | Options |
|---|---|
| Use cases | Terms and privacy acceptance at signup, terms update re-acceptance, checkout, free trial, automatic renewal, NDA, contract or order form, consent to electronic records, marketing or data consent, policy acknowledgment, custom. |
| Signers | Consumers, businesses, employees and contractors, or mixed. |
| Per use case | Assurance level (L1, L2, L3), signature method (`click`, `checkbox`, `typed`, `drawn`, `passkey`), documents. |
| Consumer notices delivered electronically | Yes, no or not sure. Yes or not sure adds the consumer e-consent steps. |
| Failure mode | `fail_closed`, or `fail_open_deferred` for terms acceptances at L1. |
| Stack | Framework (Next.js App Router, Next.js Pages Router, Remix, SvelteKit, Nuxt, Astro, Express, Hono, other), hosting, database and auth, language. |
| AI tool | Cursor, Claude Code, Codex, GitHub Copilot, Windsurf, v0, Lovable, Bolt, Replit, other. |
| Options | Receipt email, webhook confirmation or server lookup, languages, an admin action to request certificates, reporting through supplements, guidance updates. |

**Example request**

```bash
curl https://esigncomply.com/v1/prompts/generate \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jurisdictions": ["US-FED", "US-CA", "US-NY"],
    "jurisdiction_mode": "auto",
    "on_unknown_region": "strictest",
    "governing_law": "US-NY"
  }'
```

**Example response**

The prompt as Markdown with its prompt ID (`esc_prompt_...`), a content hash, the block versions and the guidance release it was built from. The profile stores the prompt ID, so every record traces back to the instructions the builder was given. Every prompt uses four fixed headings, in this order: "Required for the record", "Your obligations", "Recommendations" and "What you can send us", and ends with the conformance command to run before reporting success.

Prompt IDs resolve permanently, and code built from any issued prompt keeps working against the API version it was written for. Changes are offered as update prompts, never as a required rebuild. See [guidance](https://esigncomply.com/docs/api/guidance.md) and the [prompt generator](https://esigncomply.com/product/prompt-generator).
