Skip to content

Test mode

What test keys can do, where they work, the reserved test signer addresses, how test records differ from live ones, and the limits of the Free and Starter plans.

Test mode runs the whole product without a registered domain, a card, or an approval step. A test key creates sessions on localhost, the browser SDK reports the ceremony, and the record goes through the same sealing pipeline as a live one, on a separate test ledger. Use it to build the integration, to run the conformance checker, and in continuous integration.

Test keys

Test keys start with esc_test_us_ or esc_test_eu_. Create one in the dashboard. The key is shown once: store it as a server environment variable.

ESIGNCOMPLY_API_KEY=esc_test_us_...

A test key and a live key use the same API host and the same endpoints. The key decides the environment. Objects are separate per environment: a document, profile or record created with a test key does not exist for a live key, and reading it with one returns not_found. Every object carries livemode: false or livemode: true.

Every plan includes test mode, the Free plan too. Live keys (esc_live_...) need a verified domain. They do not need a paid plan: the Free plan includes 10 live signature events per calendar month. See Register a domain, Free plan limits and Starter limits.

Where test keys work

Live keys accept browser calls only from the verified registered domain. Test keys accept them from:

Origin Notes
localhost and *.localhost Any port
127.0.0.1 and [::1] Any port
The registered domain and its subdomains Only if the organization has registered one
Preview hosts you list Up to 25 hosts, set under Domains in the dashboard or with PATCH /v1/domains/{id} (test_origins). An entry also covers its subdomains.

Two checks use this list:

  • context.url on POST /v1/sessions. In test mode it is optional. If you send it, it must be on the list, otherwise the call returns domain_mismatch.
  • The Origin header of every browser call made with a client token. An origin outside the list returns domain_mismatch.

A test-mode request with no Origin header is accepted, so scripts, curl and test runners can drive a ceremony with the client token. In live mode a browser endpoint refuses a request without an origin.

To use a hosted preview, for example a deployment URL of an AI app builder, add its host to the list first. See AI app builders.

What is the same and what differs

Test Live
Ceremony, required steps, events Full Full
Sealing Full pipeline on a separate test ledger, signed with a test key Production ledger and sealing key
Evidence reports and certificates Watermarked "TEST", with the statement that no attestation is given No watermark
Certificates Free on every plan; not anchored publicly Paid plans only, charged per plan
Verification A test receipt verifies only against the test key and is reported as a test record Live result
Conformance findings Reported, never block A failed blocking rule refuses the record
Rules evaluated The latest guidance release, with every record condition enforced The profile's adopted baseline; newer conditions run in advise
State packs awaiting counsel review Applied, labelled research draft Not applied
Receipts and email codes Delivered only to verified email addresses of your team Delivered to the signer
Signature events Not counted against plan quota Counted
Retention Deleted after 30 days Per plan and retention schedule

Test records are never copied to live. Test documents, profiles and webhook endpoints can be copied to live from the dashboard when you go live.

Findings never block

In live mode a failed blocking rule stops the record from being sealed. In test mode it does not. The API still evaluates every rule and reports every finding in three places, so that you or your AI coding tool can read the finding and repair the page:

  • In the API response to each ceremony event, under conformance.findings.
  • In the browser console, with the rule ID, a fix and a documentation link.
  • In the dashboard, on the test record.
{
  "object": "event",
  "id": "evt_91xA",
  "type": "document.presented",
  "tag": "observed",
  "server_time": "2026-11-21T15:03:01.377Z",
  "sequence": 3,
  "conformance": {
    "status": "warn",
    "rules_version": "2026.11.2",
    "findings": [
      {
        "rule": "CR-05",
        "status": "warn",
        "state": "enforce",
        "message": "Document link contrast against surrounding text is 1.5 to 1; at least 3 to 1 is expected, in addition to any underline.",
        "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.",
        "measurement": { "contrast_ratio": 1.5, "underlined": true, "font_px": 14, "link_visible": true },
        "maps_to": ["US-11"],
        "event_type": "document.presented",
        "version_id": "dv_3kT9"
      }
    ]
  },
  "remaining_steps": ["document.presented:dv_Lm02", "notice.captured", "intent.captured", "signature.applied"],
  "session_status": "in_progress"
}

In test mode the response lists passing findings as well. In live mode it lists only those that did not pass.

Required steps are a different matter. A missing step returns steps_incomplete in both environments, and a step sent too early returns step_out_of_order. Findings are advisory statements about measurable design facts. They are not a statement that a flow is lawful or enforceable. The rules are listed under Conformance.

Test mode runs the latest rules

A live profile enforces only the record conditions it has adopted. Conditions that arrive later run in advise until you adopt them, so a guidance release cannot stop a working integration. Test mode does the opposite on purpose: it evaluates the latest release with every condition enforced, including state-specific required steps. You see what adoption would require before it reaches live traffic. See Guidance and Compatibility.

State packs that have not yet been reviewed by counsel admitted in that state are research drafts. They apply in test mode only.

Reserved test signer addresses

Five signer addresses force an outcome so that you can test each path without waiting for a real person. They work only with a test key. Pass one as signer.email when you create the session.

signer.email What it forces Webhook
signer+ok@test.esigncomply.com Email verification accepts the code 000000. None beyond the normal ones
signer+wrongcode@test.esigncomply.com Email verification never succeeds, whatever code is entered. After 5 attempts the session ends. session.cancelled
signer+bounce@test.esigncomply.com The signer receipt bounces. record.copy_bounced
signer+dispute@test.esigncomply.com A dispute is filed 10 seconds after sealing. The record status becomes disputed. record.disputed
signer+withdraw@test.esigncomply.com Consent to electronic records is withdrawn 10 seconds after sealing. consent.withdrawn

No message is sent to a reserved address.

curl https://esigncomply.com/v1/sessions \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: nda-test-ok-1" \
  -d '{
    "profile": "prof_nda_9c2e",
    "signer": { "external_id": "user_7c1d", "email": "signer+ok@test.esigncomply.com", "name": "Dana Whitfield", "class": "business", "country": "US" },
    "documents": [{ "document": "doc_Nd55", "version": "current" }],
    "context": { "url": "http://localhost:3000/nda/test", "locale": "en-US", "purpose": "nda" }
  }'

Codes and receipts in test mode

Test receipts and one-time codes are delivered only to verified email addresses of members of your organization. Any other address receives nothing. So that automation can still finish an L2 ceremony, the API returns the code in the verification response when the message was not delivered:

{
  "object": "verification",
  "id": "ver_2bQd",
  "method": "email_otp",
  "destination": "d***@example.org",
  "status": "pending",
  "expires_at": "2026-11-21T15:13:01.000Z",
  "attempts_remaining": 5,
  "sends_remaining": 2,
  "delivered": false,
  "code": "418205",
  "test_note": "Test mode: the message was not delivered because the address is not a verified team address. The code is returned here for automation."
}

In the browser SDK the same value is verification.code on the result of ceremony.verify.start(). The field never appears in live mode. See L2 verification.

Test quotas and rate limits

Test records are not signature events and never count against the live quota. Each plan has a monthly allowance of test-mode events:

Plan Test-mode events per month API rate limit per key
Free 500 2 requests per second
Starter 5,000 10 requests per second
Unlimited 20,000 50 requests per second
Enterprise Contracted Contracted (100 requests per second by default)

When the month's allowance is used, POST /v1/sessions returns test_quota_exceeded with a Retry-After header. The Free plan includes assurance levels L1 and L2. A profile at L3 needs the Unlimited plan in both environments.

Space out calls in scripts on the Free plan: more than 2 requests per second per key returns rate_limit_exceeded. Ceremony calls from the browser are limited per session, not per key.

Deletion after 30 days

Test records, their events and their supplements are deleted 30 days after they are created. A deleted test record returns not_found. Do not store anything in test mode that you need to keep.

Going live

A test record never becomes live evidence. To record live, take three steps. There is no plan to choose and no checkout.

  1. Register and verify your domain.
  2. Add the organization's legal name, country and address under Go live in the dashboard.
  3. Create a live key and set it only in your production environment.

The customer terms and the data-processing agreement were accepted once, at sign-up, so there is no acceptance step here. An organization created before sign-up recorded the data-processing agreement is asked to accept it once on the Go live page, and that step needs the account owner in person.

A paid plan is optional. The account owner chooses Starter or Unlimited on the Go live page or under Settings, Billing.

Before you switch keys:

  • Create your documents and profiles in live mode, or copy them from test in the dashboard.
  • Make sure your server confirmation checks livemode, so a test record can never unlock production access.

Free plan limits

The Free plan records live. Its plan id in the API is sandbox. It needs no card.

Free plan
Live signature events 10 per calendar month (UTC)
Verified domains 1 per organization. A second live domain needs a paid plan.
Test mode Full: 500 test events per month, 2 requests per second per key
Assurance levels L1 and L2, with email codes
Seats 1
Webhook endpoints 1 per environment
Region US

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.

  • What counts. Live signature events completed in the UTC calendar month. Test records never count.
  • Under the limit. An organization that stays under 10 in a month is never locked. Its count starts again at 00:00 UTC on the first of the next month, with 10 again. GET /v1/usage gives that time as events.resets_at.
  • Emails. Owners and admins get an email at 5, 8, 9 and 10 live signatures: 50%, 80%, 90% and 100% of the limit, once per allowance period. The usage.threshold_reached webhook is sent at the same four points. One more email is sent if new live signatures start being refused.
  • The lock. At 10 the account locks. The dashboard then shows only the lock screen, the billing page and sign-out, in test mode too. The lock does not lift on its own, and a locked account gets no new allowance on the first of the month. Upgrading to a paid plan is the only thing that removes it. The lock is on the dashboard. It does not disable API keys.
  • Refusal. Past the limit, POST /v1/sessions in live mode can be refused with 402 quota_exhausted. A live deferred submission gets the same check. Sessions already created still complete.
  • What to do. Upgrade before you reach 10. Starter covers 2,000 live signature events a year. Unlimited has no limit.

Read events.used, events.remaining and events.locked from GET /v1/usage to see where you stand. Records sealed now are never locked: the evidence report and the evidence package of a sealed record stay available through the API.

Live records on Free are real records: an outside RFC 3161 timestamp, signed checkpoints, a public anchor, the public verification page, the signer copy by email, the evidence report and the evidence package. They are retained as on Starter. Test records on Free have a simulated timestamp, with no outside authority contacted, and the "TEST" watermark. They are deleted after 30 days.

These need a paid plan: certificates for live records, L3 (Unlimited and above), SMS codes, more than 1 seat, more than 1 webhook endpoint, the EU region, bulk export and custodian-signed certifications. On Free, a certificate request or quote for a live record returns 403 plan_feature_unavailable, and so does a live session for a domain in the EU region. Test certificates stay free and watermarked on every plan.

Starter limits

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.

  • What counts. Live signature events completed in the subscription year. A paid renewal starts a new year and a new count.
  • Event packs. A pack costs $100 and adds 1,000 events to the limit for the rest of the subscription year. The limit is 2,000 plus 1,000 for each pack bought that year. Add a pack under Settings, Billing in the dashboard. With automatic event packs switched on, a pack is bought when the limit is reached, so the account does not lock, and the emails then apply to the new limit. At 10 packs in a year the subscription converts to Unlimited for the rest of that year at no further charge.
  • Emails. Owners and admins get an email at 50%, 80%, 90% and 100% of the limit, once per allowance period: 1,000, 1,600, 1,800 and 2,000 events when no pack has been bought. The usage.threshold_reached webhook is sent at the same four points. One more email is sent if new live signatures start being refused.
  • The lock. At 100% the account locks. The dashboard then shows only the lock screen, the billing page and sign-out, in test mode too. The lock does not lift on its own. Paying removes it: upgrade to Unlimited, add an event pack, or pay for renewal. The lock is on the dashboard. It does not disable API keys.
  • Refusal. Past the limit, POST /v1/sessions in live mode can be refused with 402 quota_exhausted. A live deferred submission gets the same check. Sessions already created still complete.

Unlimited and Enterprise have no limit and never lock.