# Records

> Search and retrieve sealed records, download the evidence report, the evidence package and the receipt, and add annotations.

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

A record is the sealed outcome of a completed session: one signer completing one ceremony over a bundle of document versions. It is the billable unit in live mode. Records are immutable. Later facts are added as annotations, and material you send later is stored apart as supplements.

Records are created by [`POST /v1/sessions/{id}/complete`](https://esigncomply.com/docs/api/sessions.md), not by an endpoint on this page. Everything here needs a secret key and is called from your server.

| Method and path | Key | Purpose |
|---|---|---|
| `GET /v1/records` | Secret (`full_access`, `read_only`) | Search records. |
| `GET /v1/records/{id}` | Secret (any permission) | Retrieve one record. A `recording_access` key gets the reduced status view. |
| `GET /v1/records/{id}/receipt` | Secret (any permission) | The signed receipt (JWS). |
| `GET /v1/records/{id}/report` | Secret (`full_access`, `read_only`) | The evidence report (PDF). |
| `GET /v1/records/{id}/evidence` | Secret (`full_access`, `read_only`) | The evidence package (ZIP). |
| `POST /v1/records/{id}/annotations` | Secret (`full_access`) | Add an annotation: `superseded`, `legal_hold`, `legal_hold_released`, `note`, `paper_copy_requested`. |
| `POST /v1/records/{id}/certificates` | Secret (`full_access`) | Issue an on-request certificate for one record. |
| `POST /v1/records/deferred` | Secret (`full_access`, `recording_access`) | Submit a deferred acceptance under `fail_open_deferred`. |
| `POST /v1/records/import` | Planned | Import historical acceptances. |

The default `recording_access` permission is built for application servers: it can create sessions and confirm records, but it cannot list records or download evidence reports, evidence packages or certificates. A leaked application key cannot export stored evidence.

## Record statuses

| `status` | Meaning |
|---|---|
| `pending_seal` | The record is committed. The receipt is not signed yet. This happens only when the signing key service could not be reached at completion. The receipt follows within 60 seconds. |
| `recorded` | The receipt is signed. The record is complete evidence from this point. |
| `timestamped` | An external RFC 3161 timestamp token is attached. Target: within 60 seconds. |
| `anchored` | The record is included in a signed checkpoint and a public anchor. |
| `disputed` | The signer used "This was not me" from the receipt. Esign Comply records the dispute and does not adjudicate it. |
| `voided` | Test-record purge or completed erasure. Voided records return `404` when read by ID. |

For [server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md), accept `recorded`, `timestamped` or `anchored`.

## List records

`GET /v1/records`

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

Returns records newest first.

**Query parameters**

| Parameter | Type | Description |
|---|---|---|
| `signer_external_id` | string | Records for one signer. |
| `email` | string | Exact match on the signer email asserted at session creation. |
| `document_id` | string | Records that cover any version of this document. |
| `version_id` | string | Records that cover this exact version. |
| `created_after`, `created_before` | RFC 3339 timestamp | Bounds on `signed_at`, exclusive. |
| `status` | string | One of the statuses above. Without it, voided records are left out. |
| `purpose` | string | The session purpose, for example `account_signup`. |
| `pack` | string | Records on which this jurisdiction pack was applied, for example `US-CA`. |
| `assurance_level` | string | `L1`, `L2` or `L3`. |
| `query` | string | A record ID (exact) or part of a signer external ID. |
| `limit` | integer, 1 to 100 | Page size. Default 20. |
| `after`, `before` | record ID | Cursor. Send one, not both. |

**Example request**

```bash
curl "https://esigncomply.com/v1/records?signer_external_id=user_7c1d&limit=5" \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

**Example response**

`200 OK`

```json
{
  "object": "list",
  "data": [
    {
      "object": "record",
      "id": "rec_Z4m8",
      "livemode": false,
      "status": "timestamped",
      "signed_at": "2026-11-21T15:03:20.291Z",
      "signature_level": "simple",
      "assurance_level": "L1",
      "capture_mode": "direct",
      "signer": { "external_id": "user_7c1d", "region": "US-CA" },
      "documents": [
        { "document_id": "doc_8Hq2", "version_id": "dv_3kT9" },
        { "document_id": "doc_Pv71", "version_id": "dv_Lm02" }
      ],
      "jurisdictions": { "applied": ["US-FED", "US-CA"] },
      "purpose": "account_signup",
      "record_hash": "sha256:5be7...",
      "seal": { "status": "timestamped" },
      "warnings": 1,
      "advisories": 0,
      "annotations": [],
      "supplements": 0,
      "quota_locked": false,
      "verify_url": "https://esigncomply.com/verify/rec_Z4m8"
    }
  ],
  "has_more": false
}
```

List items are summaries. `warnings` and `advisories` are counts of conformance findings that did not pass. `annotations` lists the annotation types present. `supplements` is a count. `seal.status` is the seal state on its own, which stays `recorded`, `timestamped` or `anchored` even when `status` is `disputed`.

**Errors**

[`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request) for an unknown `status`, a timestamp that does not parse, a `limit` out of range, or a cursor that does not exist. [`insufficient_permission`](https://esigncomply.com/docs/api/errors.md#insufficient_permission) for a `recording_access` key.

## Retrieve a record

`GET /v1/records/{id}`

Key: secret key with any permission.

This is the call your server makes to confirm a record before granting access. What it returns depends on the key.

| Key permission | View |
|---|---|
| `recording_access` | Status view: enough to confirm the record, and nothing more. |
| `full_access`, `read_only` | Full record. |

**Example request**

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

**Example response: status view**

`200 OK`

```json
{
  "object": "record",
  "id": "rec_Z4m8",
  "livemode": false,
  "status": "recorded",
  "signed_at": "2026-11-21T15:03:20.291Z",
  "signature_level": "simple",
  "assurance_level": "L1",
  "capture_mode": "direct",
  "signer": { "external_id": "user_7c1d" },
  "documents": [
    { "document_id": "doc_8Hq2", "version_id": "dv_3kT9", "content_hash": "sha256:9f2c..." },
    { "document_id": "doc_Pv71", "version_id": "dv_Lm02", "content_hash": "sha256:c01e..." }
  ],
  "record_hash": "sha256:5be7...",
  "receipt": "eyJhbGciOiJFUzI1NiIs...",
  "verify_url": "https://esigncomply.com/verify/rec_Z4m8",
  "seal": { "timestamp": "pending", "anchor": "pending", "ledger_seq": 18244 },
  "metadata": { "plan": "pro" },
  "quota_locked": false
}
```

In the status view `seal.timestamp` is `pending` or `attached`, and `seal.anchor` is `pending` or `published`.

**What to check at confirmation**

```ts
const { data: record, error } = await esc.records.get(recordId);
if (error) throw new Error("Esign Comply confirmation failed");

const expected = [...expectedVersionIds].sort();
const actual = record.documents.map((d) => d.version_id).sort();

const ok =
  ["recorded", "timestamped", "anchored"].includes(record.status) &&
  record.signer.external_id === expectedSignerId &&
  record.livemode === expectedLivemode &&
  JSON.stringify(actual) === JSON.stringify(expected);

if (!ok) throw new Error("Unexpected record");
// Only now grant access.
```

`expectedSignerId`, `expectedLivemode` and `expectedVersionIds` come from state your server saved when it created the session, never from the browser.

**Example response: full record**

`200 OK`, shortened.

```json
{
  "object": "record",
  "id": "rec_Z4m8",
  "livemode": true,
  "status": "timestamped",
  "signed_at": "2026-11-21T15:03:20.291Z",
  "signature_level": "simple",
  "assurance_level": "L1",
  "capture_mode": "direct",
  "organization": { "legal_name": "Example, Inc.", "country": "US" },
  "domain": "example.com",
  "profile": { "id": "prof_signup_4f1a", "version": 1 },
  "jurisdictions": {
    "mode": "auto",
    "applied": [
      { "code": "US-FED", "version": "2026-11-21", "reason": "base" },
      { "code": "US-CA", "version": "2026-11-21", "reason": "signer_region" }
    ],
    "rule_set_version": "2026.11.21",
    "rules_fired": [{ "id": "US-08", "state": "enforce" }, { "id": "US-09", "state": "enforce" }],
    "governing_law": null,
    "warnings": []
  },
  "signer": {
    "external_id": "user_7c1d",
    "name": "Dana Whitfield",
    "email": "dana@example.org",
    "class": "consumer",
    "country": "US",
    "region": "US-CA",
    "actor_type": "human"
  },
  "documents": [
    {
      "document_id": "doc_8Hq2",
      "version_id": "dv_3kT9",
      "title": "Terms of Service",
      "type": "terms",
      "version_label": "2026-11-21",
      "language": "en",
      "format": "markdown",
      "content_hash": "sha256:9f2c...",
      "render_hash": "sha256:41ab...",
      "render_match": true,
      "presentation_mode": "hyperlink"
    }
  ],
  "events": [
    { "id": "evt_...", "sequence": 1, "type": "session.created", "tag": "asserted", "step": "session.created", "server_time": "2026-11-21T15:02:11.482Z", "client_time": null, "data": { "...": "..." }, "event_hash": "sha256:..." },
    { "id": "evt_91xA", "sequence": 3, "type": "document.presented", "tag": "observed", "step": "document.presented:dv_3kT9", "server_time": "2026-11-21T15:03:01.377Z", "client_time": "2026-11-21T10:03:01.120-05:00", "version_id": "dv_3kT9", "data": { "mode": "hyperlink", "link_text": "Terms of Service" }, "event_hash": "sha256:..." },
    { "id": "evt_...", "sequence": 7, "type": "signature.applied", "tag": "observed", "step": "signature.applied", "server_time": "2026-11-21T15:03:20.291Z", "client_time": "2026-11-21T10:03:20.004-05:00", "data": { "method": "checkbox", "label_text": "I agree to the Terms of Service and Privacy Notice", "button_text": "Create account" }, "event_hash": "sha256:..." }
  ],
  "network": { "ip": "203.0.113.24", "user_agent": "Mozilla/5.0 ...", "accept_language": "en-US", "origin": "https://app.example.com", "page_url": "https://app.example.com/signup" },
  "notice": { "source": "live_capture", "event_id": "evt_...", "text": "By checking the box and clicking Create account, you agree to the Terms of Service and acknowledge the Privacy Notice.", "text_hash": "sha256:...", "viewport": { "width": 390, "height": 844 } },
  "signature": { "method": "checkbox", "label_text": "I agree to the Terms of Service and Privacy Notice", "button_text": "Create account", "client_time": "2026-11-21T10:03:20.004-05:00" },
  "context": { "url": "https://app.example.com/signup", "locale": "en-US", "purpose": "account_signup", "facts": {}, "notes": "Signup A/B variant 7." },
  "metadata": { "plan": "pro" },
  "retention_floor": null,
  "guidance_release": "2026.11.3",
  "api_version": "2026-11-21",
  "conformance": {
    "advisory": true,
    "rules_version": "2026.11.2",
    "results": [{ "rule": "CR-05", "status": "warn", "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 } }]
  },
  "advisories": [],
  "copy_delivery": { "channel": "email", "status": "delivered", "time": "2026-11-21T15:03:41.090Z" },
  "record_hash": "sha256:5be7...",
  "receipt": "eyJhbGciOiJFUzI1NiIs...",
  "verify_url": "https://esigncomply.com/verify/rec_Z4m8",
  "seal": {
    "receipt": "eyJhbGciOiJFUzI1NiIs...",
    "kid": "esc-us-live-2026-11",
    "ledger_seq": 18244,
    "prev_hash": "sha256:a91c...",
    "entry_hash": "sha256:77e0...",
    "timestamp": { "authority": "tsa_primary", "time": "2026-11-21T15:03:22.000Z", "kind": "rfc3161" },
    "checkpoint": "pending",
    "anchor": "pending",
    "inclusion_proof": null,
    "receipt_signed_at": "2026-11-21T15:03:20.346Z",
    "committed_at": "2026-11-21T15:03:20.300Z"
  },
  "annotations": [],
  "supplements": [],
  "certificates": [],
  "quota_locked": false
}
```

**Record fields**

Every field is tagged by where it came from. Observed: seen by Esign Comply directly from the signer's device, or generated by Esign Comply. Asserted: supplied by you and not verified. See [Observed and asserted](https://esigncomply.com/docs/concepts/observed-and-asserted.md).

| Field | Tag | Description |
|---|---|---|
| `id`, `livemode` | Observed | Record identifier. Live or test. |
| `status` | Observed | See "Record statuses". |
| `signed_at` | Observed | Server receipt time of the final event. It is not an independently verified act time, and it is not the timestamp authority's time. |
| `signature_level` | Service classification | `simple` for L1 to L3 signing. `not_applicable` where signing intent is not evidenced. `advanced` and `qualified` are reserved values that the base product does not produce. |
| `assurance_level` | Observed | `L1`, `L2` or `L3`. |
| `capture_mode` | Observed | `direct` (browser channel), `server_only`, `deferred`, `imported`. |
| `organization` | Asserted at signup | Legal name and country of your organization. |
| `domain` | Observed | Registered domain. Null for test records made without a registered domain. |
| `profile` | Observed | Profile ID and version. |
| `jurisdictions` | Mixed | `mode`. `applied[]` with pack code, version and reason (observed). `rule_set_version`. `rules_fired[]` with each condition's `state` (`enforce`, `advise`, or null for a rule with no record condition). `governing_law` (asserted). `warnings[]` from session creation. |
| `signer.external_id`, `name`, `email`, `phone`, `class`, `country`, `region`, `locality`, `actor_type` | Asserted | Supplied by you. `region` is normalized to ISO 3166-2. |
| `signer.verified_email`, `signer.verified_phone`, `signer.verification[]` | Observed | Present when Esign Comply verified control of the channel: method, masked destination, time, attempts. |
| `signer.typed_name`, `signer.drawn_signature` | Observed | What the signer entered. |
| `documents[]` | Observed | Version ID, title, type, version label, language, format, `content_hash`, `render_hash`, `render_match` (true, false, or null when no comparison was reported) and `presentation_mode`. |
| `events[]` | Mixed | The ordered ceremony events, each with its own `tag`, `server_time`, `client_time`, `data` and `event_hash`. |
| `network` | Observed | IP address, user agent, accept-language, origin and page URL of the completing request. Absent under minimal capture and for `server_only` sessions. |
| `notice` | Mixed | The captured assent notice: `source` (`live_capture` or `registered_artifact`), text and its hash. Null when nothing was captured. |
| `signature` | Observed | Method, exact label text, exact button text. |
| `context.url`, `locale`, `purpose`, `facts`, `notes`, `extra` | Asserted | What you sent at session creation. |
| `metadata` | Asserted | Your key-value pairs. |
| `retention_floor` | Observed | The retention floor the applied packs recorded, or null. |
| `guidance_release`, `api_version` | Observed | The guidance release and dated API version in force. |
| `conformance` | Advisory | Rule-set version and result per rule. Stored beside the record and excluded from the sealed hash. The underlying measurements are sealed inside `events[]`. |
| `advisories[]` | Advisory | Record conditions in the advise state that were evaluated and not met. |
| `copy_delivery` | Mixed | Receipt email channel, `status` (`queued`, `delivered`, `bounced`, `disabled`) and time. |
| `record_hash` | Observed | SHA-256 over a random salt and the canonical record (RFC 8785). |
| `receipt`, `verify_url` | Observed | The signed receipt and the verification page for this record. |
| `seal` | Observed | Receipt, key ID, ledger sequence, previous-entry hash, entry hash, timestamp (`pending`, or authority and time), checkpoint (`pending`, or ID, time, tree size, root, leaf index), public anchor (`pending`, or kind, time, reference), inclusion proof. |
| `annotations[]` | Observed | Later facts Esign Comply observed or enforced. Each is its own ledger entry. |
| `supplements[]` | Customer-supplied | The first 20 supplements for this record: ID, type, `received_at`, `occurred_at`, hash, `withdrawn`. Outside the sealed hash. Page the rest through [`GET /v1/supplements`](https://esigncomply.com/docs/api/supplements.md). |
| `certificates[]` | Observed | On-request certificates issued for this record: ID, type, status, issue time, requester class, charge class. |
| `quota_locked` | Observed | See "Quota lock". |

After an erasure the content fields are gone. The response then carries `content_available: false` and a `content_note`, together with the fields that remain: status, hash, seal and ledger position.

**Errors**

[`not_found`](https://esigncomply.com/docs/api/errors.md#not_found) when the record does not exist in this domain and environment, or is voided. Test records are not visible to live keys and the reverse.

## Retrieve the receipt

`GET /v1/records/{id}/receipt`

Key: secret key with any permission.

The receipt is a compact signed token (JWS, `ES256`, `typ: esc-receipt+jwt`). Store it in your own database next to your acceptance row. Its holder can check it against the published keys at `/.well-known/jwks.json` or through [`POST /v1/verify`](https://esigncomply.com/docs/api/verification.md).

**Example request**

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

**Example response**

`200 OK`

```json
{
  "object": "receipt",
  "record_id": "rec_Z4m8",
  "receipt": "eyJhbGciOiJFUzI1NiIs...",
  "kid": "esc-us-live-2026-11",
  "payload": {
    "iss": "https://esigncomply.com",
    "rid": "rec_Z4m8",
    "dom": "example.com",
    "hash": "sha256:5be7...",
    "iat": 1795273400,
    "lvl": "simple",
    "asr": "L1",
    "seq": 18244,
    "prev": "sha256:a91c...",
    "live": true
  }
}
```

| Claim | Meaning |
|---|---|
| `iss` | Issuer. |
| `rid` | Record ID. |
| `dom` | Registered domain. |
| `hash` | Record hash. |
| `iat` | Signed-at time, in seconds. |
| `lvl` | Signature level. |
| `asr` | Assurance level. |
| `seq`, `prev` | Position in the domain's ledger and the hash of the previous entry. |
| `live` | Live or test. A receipt signed by a test key never verifies as live evidence. |

**Errors**

[`not_found`](https://esigncomply.com/docs/api/errors.md#not_found). [`service_unavailable`](https://esigncomply.com/docs/api/errors.md#service_unavailable) with `Retry-After: 5` while the record is `pending_seal`.

## Download the evidence report

`GET /v1/records/{id}/report`

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

Returns the evidence report as a PDF (`Content-Type: application/pdf`, served as an attachment named `rec_Z4m8-evidence-report.pdf`). The report is generated from the sealed record. It is included for every record on every plan and is never charged per download. Test records are watermarked "TEST".

The report states what was recorded, with each field labeled observed or asserted. It does not state that an agreement is valid or enforceable. A report downloaded later also lists supplements received since sealing, in a separate part. See [Evidence](https://esigncomply.com/docs/concepts/evidence.md).

**Example request**

```bash
curl https://esigncomply.com/v1/records/rec_Z4m8/report \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -o rec_Z4m8-evidence-report.pdf
```

**Example response**

`200 OK` with the PDF bytes.

**Errors**

[`not_found`](https://esigncomply.com/docs/api/errors.md#not_found), [`insufficient_permission`](https://esigncomply.com/docs/api/errors.md#insufficient_permission) for a `recording_access` key, [`quota_exceeded`](https://esigncomply.com/docs/api/errors.md#quota_exceeded) for a record locked under the earlier Starter quota rule.

## Download the evidence package

`GET /v1/records/{id}/evidence`

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

The evidence package is a ZIP archive with the canonical record, the seal, the receipt, the timestamp token, the inclusion proof, the exact stored bytes of each document, the evidence report, the public keys and verification instructions. It verifies offline with [`esigncomply-verify`](https://esigncomply.com/docs/sdk/verify.md).

By default the response is JSON with a signed download URL that is valid for 10 minutes. Packages can be larger than an API response may be.

**Query parameters**

| Parameter | Description |
|---|---|
| `inline` | `true` returns the archive itself (`Content-Type: application/zip`) when it is under 4 MB. Larger packages still return the JSON with a URL. |
| `supplements` | `false` leaves out the `customer_supplied/` folder. |

**Example request**

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

**Example response**

`200 OK`

```json
{
  "object": "evidence_package",
  "record_id": "rec_Z4m8",
  "url": "https://.../rec_Z4m8.zip?token=...",
  "expires_in": 600,
  "size": 184213,
  "files": [
    { "path": "manifest.json", "sha256": "sha256:...", "size": 2104 },
    { "path": "record.json", "sha256": "sha256:...", "size": 9120 },
    { "path": "seal.json", "sha256": "sha256:...", "size": 811 },
    { "path": "receipt.jws", "sha256": "sha256:...", "size": 402 },
    { "path": "report.pdf", "sha256": "sha256:...", "size": 151300 }
  ],
  "format": "esc-evidence-package/1"
}
```

Download and verify:

```bash
curl -L "$PACKAGE_URL" -o rec_Z4m8.zip
npx esigncomply-verify rec_Z4m8.zip
```

**Errors**

[`not_found`](https://esigncomply.com/docs/api/errors.md#not_found), [`insufficient_permission`](https://esigncomply.com/docs/api/errors.md#insufficient_permission), [`quota_exceeded`](https://esigncomply.com/docs/api/errors.md#quota_exceeded).

## Add an annotation

`POST /v1/records/{id}/annotations`

Key: secret key with `full_access`. Idempotent with `Idempotency-Key`.

An annotation is a later fact attached to a record. The record itself never changes. Each annotation is its own ledger entry with its own signed receipt.

**Request fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string | Yes | One of the customer types below. |
| `data` | object | No | Structured detail, stored with the annotation. |
| `note` | string, up to 4,000 characters | No | Free text. Stored as `data.note`. |

| Customer type | Use |
|---|---|
| `superseded` | A later record replaces this one for your purposes. |
| `legal_hold` | Keep the record's content regardless of the retention schedule. Blocks erasure. |
| `legal_hold_released` | Ends an earlier `legal_hold`. |
| `note` | Anything else worth attaching in plain words. |
| `paper_copy_requested` | A paper-copy request. Requests made in the signer view are added by Esign Comply. Report the delivery of the copy as a `paper_copy.delivered` supplement. |

These types are written by Esign Comply only and are refused here: `consent_withdrawn`, `disputed`, `electronic_transactions_refused`, `erased`.

Customer reports are supplements, not annotations. The earlier annotation types `notice.sent` and `cancellation.requested` are still accepted here so that older integrations keep working: they are stored as a [supplement](https://esigncomply.com/docs/api/supplements.md), and the response is the supplement object with the warning `stored_as_supplement`. New integrations send reports to `POST /v1/supplements`.

**Example request**

```bash
curl https://esigncomply.com/v1/records/rec_Z4m8/annotations \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "legal_hold", "note": "Matter 2026-0412. Review on 2027-06-01." }'
```

**Example response**

`201 Created`

```json
{
  "object": "annotation",
  "record_id": "rec_Z4m8",
  "id": "ann_3Fd8",
  "type": "legal_hold",
  "actor": "customer:key:key_2bQ1",
  "created_at": "2026-12-03T09:14:55.120Z",
  "data": { "note": "Matter 2026-0412. Review on 2027-06-01." },
  "ledger_seq": 18310
}
```

**Errors**

[`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request) for any other `type`. [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found) for an unknown or voided record. [`insufficient_permission`](https://esigncomply.com/docs/api/errors.md#insufficient_permission) for keys without `full_access`.

## Issue a certificate for one record

`POST /v1/records/{id}/certificates`

Key: secret key with `full_access`.

Issues an on-request certificate, the Contemporaneous Record Statement, for one record. The record must be `timestamped` or `anchored`: a record that is only `recorded` returns [`record_not_timestamped`](https://esigncomply.com/docs/api/errors.md#record_not_timestamped) with `Retry-After`. A request that would incur a charge needs `confirm_charge: true`, otherwise it returns [`certificate_charge_unconfirmed`](https://esigncomply.com/docs/api/errors.md#certificate_charge_unconfirmed) with a quote and issues nothing. Certificates for live records are on paid plans: on the Free plan the call returns [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable) for a live record. The request body, the response, quotes, sets and share links are documented under [Certificates](https://esigncomply.com/docs/api/certificates.md). The [certificates guide](https://esigncomply.com/docs/guides/certificates.md) explains what the statement says and what it does not.

## Submit a deferred acceptance

`POST /v1/records/deferred`

Key: secret key with `full_access` or `recording_access`. Send an `Idempotency-Key`.

For profiles created with `failure_mode: "fail_open_deferred"`, which is available only for terms acceptances at L1. When Esign Comply could not be reached at signing time, your server stores the acceptance and submits it here later.

The record is sealed with `capture_mode: "deferred"`. Every ceremony field is tagged asserted: Esign Comply did not observe the act. The evidence report and any certificate say so, and the certificate does not say the record was made at or near the time of the act. No jurisdiction rules or conformance checks are evaluated for a deferred record.

**Request fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `profile` | string | Yes | A profile with `failure_mode: "fail_open_deferred"`. |
| `signer.external_id` | string | Yes | Your identifier for the signer. |
| `signer.email`, `signer.name`, `signer.class`, `signer.country`, `signer.region` | string | No | Asserted signer facts. With an email, the signer receives a receipt. |
| `documents[]` | array, 1 to 10 | Yes | `{ "document": "doc_...", "version": "dv_..." }`. Name the exact version that was shown. `"current"` is refused. |
| `signed_at` | RFC 3339 timestamp | Yes | When you say the act occurred. Must not be in the future. |
| `signature.method` | string | Yes | For example `checkbox`. |
| `signature.label_text`, `signature.button_text` | string | No | The label and button text your page showed. |
| `context.url`, `context.locale`, `context.purpose`, `context.notes` | string | No | As on a session. |
| `reason` | string, up to 500 characters | No | Why the acceptance was deferred, for example the outage window. |
| `metadata` | object | No | Your key-value pairs. |

**Example request**

```bash
curl https://esigncomply.com/v1/records/deferred \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deferred-user_7c1d-tos-2026-11-21" \
  -d '{
    "profile": "prof_signup_4f1a",
    "signer": { "external_id": "user_7c1d", "email": "dana@example.org", "class": "consumer", "country": "US" },
    "documents": [{ "document": "doc_8Hq2", "version": "dv_3kT9" }],
    "signed_at": "2026-11-21T15:03:20.000Z",
    "signature": { "method": "checkbox", "label_text": "I agree to the Terms of Service", "button_text": "Create account" },
    "context": { "url": "https://app.example.com/signup", "purpose": "account_signup" },
    "reason": "Esign Comply API unreachable from 15:01 to 15:09 UTC."
  }'
```

**Example response**

`201 Created`

```json
{
  "object": "record",
  "id": "rec_Z4m8",
  "livemode": true,
  "status": "recorded",
  "capture_mode": "deferred",
  "signed_at": "2026-11-21T15:11:02.417Z",
  "asserted_signed_at": "2026-11-21T15:03:20.000Z",
  "signature_level": "simple",
  "assurance_level": "L1",
  "signer": { "external_id": "user_7c1d" },
  "documents": [{ "version_id": "dv_3kT9", "content_hash": "sha256:9f2c..." }],
  "record_hash": "sha256:5be7...",
  "receipt": "eyJhbGciOiJFUzI1NiIs...",
  "verify_url": "https://esigncomply.com/verify/rec_Z4m8",
  "note": "Deferred submission: every ceremony field is asserted by the customer. Esign Comply did not observe the act; its record of this report was made at the receipt time shown."
}
```

`signed_at` on a deferred record is the time Esign Comply received your report. The time you say the act occurred is kept as `asserted_signed_at`. The `record.completed` webhook is sent as for any record.

**Errors**

| Code | When |
|---|---|
| [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request) | The profile is `fail_closed` (`param: "profile"`), a document names `"current"`, or `signed_at` is in the future. |
| [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found) | Unknown profile, document or version. |
| [`quota_exhausted`](https://esigncomply.com/docs/api/errors.md#quota_exhausted) | A live submission, on Free or Starter, that came past the plan's limit and was refused. The check is the same as on `POST /v1/sessions`. |

## Import records (Planned)

> **Planned.** `POST /v1/records/import` is not available yet.

Import will accept historical acceptances from a system you ran before Esign Comply. Imported records will have `capture_mode: "imported"`, will always be marked asserted, will not count toward quota, and will be capped per domain. Until then, keep your earlier acceptance table as it is and record new acceptances through sessions.

## Quota lock

Records sealed now are never locked. The plan's limit acts on the account and on new live signatures, not on records. 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).

`quota_locked` is `false` on every record sealed now. It is `true` only on a record that was locked under the earlier Starter quota rule. For such a record:

- `GET /v1/records/{id}`, the receipt, signer receipts and verification keep working.
- The evidence report, the evidence package and certificates return [`quota_exceeded`](https://esigncomply.com/docs/api/errors.md#quota_exceeded) (`402`).

Adding an event pack, upgrading or renewing unlocks every such record at once. See [/pricing](https://esigncomply.com/pricing).

## Related

- [Server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md): the check to run before granting access.
- [Evidence](https://esigncomply.com/docs/concepts/evidence.md): sealing pipeline, receipt, report and package.
- [Verification](https://esigncomply.com/docs/api/verification.md): `POST /v1/verify`, the public log and the keys.
- [Webhooks](https://esigncomply.com/docs/api/webhooks.md): `record.completed`, `record.timestamped`, `record.anchored`, `record.disputed`.
