# 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.

Source: https://esigncomply.com/docs/guides/domains

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](https://esigncomply.com/docs/guides/test-mode.md).

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](https://esigncomply.com/docs/guides/test-mode.md#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`](https://esigncomply.com/docs/api/errors.md#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`](https://esigncomply.com/docs/api/errors.md#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`](https://esigncomply.com/docs/api/errors.md#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`](https://esigncomply.com/docs/api/errors.md#region_mismatch) with the correct host. An EU region does not mean that all processing stays in the EU. See [Compliance: Europe](https://esigncomply.com/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`](https://esigncomply.com/docs/api/errors.md#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.

```text
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:

```bash
dig +short TXT _esigncomply.example.com
```

```text
"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:

```text
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:

```text
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:

```ts
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`](https://esigncomply.com/docs/api/errors.md#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.

```json
{
  "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](https://esigncomply.com/docs/api/webhooks.md).

## 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`](https://esigncomply.com/docs/api/errors.md#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](https://esigncomply.com/docs/api/account.md).

| 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**

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

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

```json
{
  "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:

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

```json
{
  "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](https://esigncomply.com/docs/guides/test-mode.md).

```bash
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.
