Account
Manage the registered domain, API keys and webhook endpoints, read usage, run conformance checks and generate integration prompts.
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: 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.
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
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
{
"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:
{
"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_request400: 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_registered409: the domain is attached to another subscription.plan_feature_unavailable403: 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
curl https://esigncomply.com/v1/domains \
-H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
Example response
200 OK
{
"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
curl https://esigncomply.com/v1/domains/dom_4Kx9 \
-H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
Example response
200 OK with the domain object, including certificate_spend_limit.
Errors
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
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.
{
"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
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
{
"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. See certificates.
Errors
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 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
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
{
"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.
Errors
insufficient_permission403: a test key asked for a live key, or the calling key is notfull_access.domain_not_verified403: 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
curl https://esigncomply.com/v1/api-keys \
-H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
Example response
200 OK
{
"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. Rotate a key whenever it may have been exposed: create a new one, deploy it, then revoke the old one.
Example request
curl -X DELETE https://esigncomply.com/v1/api-keys/key_2bQ1 \
-H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
Example response
200 OK
{ "object": "api_key", "id": "key_2bQ1", "revoked": true }
Errors
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.
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
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
{
"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_request400: the URL is not valid or not HTTPS, a live URL points at a private address, oreventsnames an unknown type.plan_feature_unavailable403: the plan's endpoint limit is reached.
List webhook endpoints
GET /v1/webhooks
Key: secret key with full_access.
Example request
curl https://esigncomply.com/v1/webhooks \
-H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
Example response
200 OK
{
"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
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: no such endpoint in this environment.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
curl -X DELETE https://esigncomply.com/v1/webhooks/wh_6Tn3 \
-H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
Example response
200 OK
{ "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
curl -X POST https://esigncomply.com/v1/webhooks/wh_6Tn3/test \
-H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
Example response
200 OK
{
"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
curl "https://esigncomply.com/v1/webhooks/deliveries?endpoint=wh_6Tn3&status=failed" \
-H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
Example response
200 OK
{
"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
curl https://esigncomply.com/v1/usage \
-H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
Example response
200 OK
{
"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:
{
"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. See Free plan limits and 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 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 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 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
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
{
"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.
Errors
invalid_request: a field has the wrong type or is out of range.insufficient_permission: aread_onlykey 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
curl https://esigncomply.com/v1/conformance/runs \
-H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
Example response
200 OK
{
"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
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: 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
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 and the prompt generator.