Skip to content

Register a domain

How the registered domain is computed, how to verify it by DNS or by file, what each status means, and what happens when verification lapses.

Live recording is tied to one verified domain. The record names your organization and the domain where the signing happened, and the API accepts live browser calls only from that domain. Test mode needs none of this: test keys work on localhost before you register anything. See Test mode.

Going live takes three steps:

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

There is no plan to choose and no checkout. The Free plan includes 10 live signature events per calendar month on one verified domain. See Free plan limits. A paid plan is optional: the account owner chooses Starter or Unlimited on the Go live page or under Settings, Billing.

You accepted the customer terms and the data-processing agreement once, at sign-up. 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.

One subscription, one domain

Rule What it means
One organization, one domain A subscription belongs to exactly one organization and one registered domain. The organization's legal name is printed on evidence reports and certificates.
Registrable domain "Domain" means the registrable domain under the Public Suffix List, for example example.com or example.co.uk.
Subdomains included app.example.com, www.example.com and every other subdomain are covered.
One active subscription per domain A second registration of the same domain returns domain_already_registered.
Several sites Websites on different registrable domains need one subscription each. An organization can hold several subscriptions. Each has its own keys, quota, ledger, region and invoice.
Platform hosts A host on a shared platform suffix, such as myapp.vercel.app, registers as its own domain and verifies by file.
Agencies An agency building for clients needs one subscription per client domain, owned by the client's organization.
Enterprise A contract may cover several domains of one legal entity and named affiliates, priced per domain.

Once the domain is verified:

  • Live keys work. Before that, a live key returns domain_not_verified.
  • Live browser calls are accepted only from origins within the registered domain.
  • Live session creation must declare a context.url within the registered domain. Anything else returns domain_mismatch.

What you enter and what is registered

Type a host or a URL. Esign Comply computes the registrable domain and shows it before you confirm.

You enter Registered Method
app.example.com example.com and every subdomain DNS
https://www.example.co.uk/signup example.co.uk and every subdomain DNS
myapp.vercel.app myapp.vercel.app on its own File
localhost, 127.0.0.1 Cannot be registered. Test keys already work there. None

A platform host is registered on its own because you do not control DNS for the suffix. If you later move to a custom domain, that is a domain change.

Choose the region

Choose the data region when you register the domain. It is fixed for that domain.

Region API base URL Key prefixes
US (us-east-1) https://esigncomply.com/v1 esc_test_us_, esc_live_us_
EU (eu-central-1) https://api.eu.esigncomply.com/v1 esc_test_eu_, esc_live_eu_

The region sets where evidence is stored and which API host the keys use. A key sent to the other region's host returns region_mismatch with the correct host. An EU region does not mean that all processing stays in the EU. See Compliance: Europe.

The Free plan records live in the US region only. A live session on Free for a domain in the EU region returns 403 plan_feature_unavailable. Live recording in the EU region needs a paid plan.

Verify by DNS

Add one TXT record at your DNS provider. The record goes on the registrable domain, whichever subdomain you entered. An AI agent that has no access to your DNS provider asks you to add this one record.

Type:   TXT
Name:   _esigncomply
Value:  esc-verify=<token>

The full record name is _esigncomply.example.com. Some providers want the short name _esigncomply, others the full name. The token is shown in the dashboard and returned by the API as verification.value.

Check it from a terminal:

dig +short TXT _esigncomply.example.com
"esc-verify=<token>"

Esign Comply queries two independent public resolvers and both must return the exact value. A record that one resolver has not picked up yet keeps the domain pending, so allow for propagation.

Keep the record in place after verification. It is re-checked every day.

Verify by file

Platform hosts verify with a file, because you cannot add DNS records under a shared suffix. This method is offered automatically for hosts under: vercel.app, lovable.app, netlify.app, replit.app, repl.co, bolt.host, pages.dev, workers.dev, web.app, firebaseapp.com, onrender.com, fly.dev, herokuapp.com, github.io, railway.app, v0.app, webcontainer.io and stackblitz.io.

Serve the token as plain text at:

https://myapp.vercel.app/.well-known/esigncomply.txt

The file contains the token shown in the dashboard and returned by the API as verification.content. The check fetches the URL over HTTPS, does not follow redirects, expects status 200, and looks for the token in the body.

In a Next.js application, add a static file:

public/.well-known/esigncomply.txt

or a route handler at app/.well-known/esigncomply.txt/route.ts, which keeps the token out of the repository:

export function GET() {
  return new Response(process.env.ESIGNCOMPLY_DOMAIN_TOKEN ?? "", {
    headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" },
  });
}

Make sure the path is not behind authentication and is not redirected, for example from the bare host to www.

Statuses

Status Meaning What to do
not_started No domain has been entered. Register a domain. Test mode works without one.
pending The record or file has not been found yet. Checks are running. Add the TXT record or the file, then wait or trigger a check.
verified The record or file was found. Add your organization's details under Go live and create a live key. Keep the record in place.
failed Nothing was found within 72 hours. Fix the record or file and trigger a check.
lapsed The domain was verified and the daily check has now failed three times in a row. Restore the record or file within 14 days.

When checks run

  • Every minute for the first hour after registration.
  • Every 15 minutes after that, up to 72 hours.
  • Once a day from then on, including after verification.

You do not have to wait for the schedule. Use "Check now" in the dashboard, or call POST /v1/domains/{id}/verify, to run a check at once.

When the status changes to verified, the organization's owners get an email and the domain.verified webhook is sent.

When verification lapses

A verified domain is re-checked every 24 hours. Three consecutive failures set the status to lapsed. From that moment:

  1. Owners are warned in the dashboard and by email, and the domain.verification_lapsed webhook is sent with live_recording_until.
  2. Live recording continues for 14 days. Sessions are created and records are sealed as before.
  3. After 14 days, POST /v1/sessions with a live key returns domain_not_verified until verification is restored.

Existing records are not affected at any point. To restore verification, put the TXT record or the file back. The next check sets the status to verified again.

{
  "object": "event",
  "id": "whe_8Rt4",
  "type": "domain.verification_lapsed",
  "api_version": "2026-11-21",
  "livemode": true,
  "created_at": "2027-02-03T04:17:09.220Z",
  "data": {
    "domain_id": "dom_4Kx9",
    "domain": "example.com",
    "live_recording_until": "2027-02-17T04:17:09.101Z"
  }
}

Domain events are live-mode events. Subscribe a live webhook endpoint to receive them. See Webhooks.

Change the domain

A subscription can change its registered domain once per 12 months without contacting support. Moving from a platform host to a custom domain counts as a change.

  • Registering the new domain issues a new token and sets the status to pending.
  • Live keys return domain_not_verified until the new domain is verified. Publish the new record first and trigger a check right after registering, so the gap is short.
  • Records already sealed stay bound to the domain that was registered when they were sealed.

If the domain is already registered

If another organization has registered the domain, registration returns domain_already_registered. If you own the domain, start a claim from the dashboard and publish the verification record shown there. A successful DNS challenge notifies the current owner, and the registration transfers after 7 days unless the current owner verifies again.

Use the API

Everything on the domain screen has an API call. All of them need a secret key with full_access. A key is bound to one domain, so these calls act on the key's own domain. Field details are in the Account API.

Method and path Purpose
GET /v1/domains Find the domain ID for this key
POST /v1/domains Register a domain and choose the region
GET /v1/domains/{id} Read the status and the verification instructions
POST /v1/domains/{id}/verify Run a verification check now
PATCH /v1/domains/{id} Set test_origins, the preview hosts on which test keys work

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-21T14:58:40.006Z"
}

For a platform host the verification object describes the file instead:

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

Then wait for the schedule, or trigger a check. The response is the domain object plus the outcome of that check:

curl -X POST https://esigncomply.com/v1/domains/dom_4Kx9/verify \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
{
  "object": "domain",
  "id": "dom_4Kx9",
  "domain": "example.com",
  "status": "pending",
  "check": {
    "ok": false,
    "method": "dns",
    "detail": {
      "name": "_esigncomply.example.com",
      "expected": "esc-verify=<token>",
      "cloudflare": ["esc-verify=<token>"],
      "google": [],
      "cloudflare_ok": true,
      "google_ok": false
    }
  }
}

The response is shortened here. In this example one resolver has the record and the other does not yet, so the domain stays pending.

To let test keys work on preview hosts in addition to localhost, list the hosts (25 at most). See Test mode.

curl -X PATCH https://esigncomply.com/v1/domains/dom_4Kx9 \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "test_origins": ["preview.example.dev", "myapp-git-main.vercel.app"] }'

One-click DNS setup (Planned)

Planned. One-click DNS setup through Domain Connect, for DNS hosts that support it, is not available yet. Add the TXT record by hand.

Mobile applications (Planned)

Planned. Native mobile applications will be covered when the registered domain publishes an association file that names the application (apple-app-site-association for iOS, assetlinks.json for Android). This is not available yet.