# Certificates

> Request a Contemporaneous Record Statement for a timestamped record or a set of records, with a quote before any charge.

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

A certificate is a dated statement about one or more sealed records, issued on request. Its printed title is "Contemporaneous Record Statement". It says when and how Esign Comply made its record, shows the time evidence that rests on parties other than Esign Comply and you, and reports a fresh integrity check run at the moment of issue.

It is not the per-record PDF. That document is the evidence report: it is generated for every record, included in every plan and never charged per download. Request a certificate only when a dispute turns on when a record was made.

In the API the object is `certificate`, with IDs prefixed `crt_`. Requests need a `full_access` key. `read_only` keys can list and download certificates. `recording_access` keys have no certificate access and can never incur a charge.

## What the statement says

| Section | Content |
|---|---|
| Header | Printed title, certificate ID, issue time in UTC, record ID or set description, requester class, your `reference` marked asserted, live or test mark, verification URL and QR code |
| What is stated | A fixed paragraph (below) |
| Chronology | For each ceremony event: browser-reported time (reported, not verified) and Esign Comply server receipt time (observed), with the difference. Then record committed, receipt signed with key ID, external timestamp, checkpoint and public anchor. Every time is labeled with its source. |
| Intervals | Measured durations from the final ceremony event to commit, receipt signature, external timestamp, checkpoint and public anchor. Printed as numbers. No adjective such as "immediately". |
| Independent time bound | "The timestamp token issued by {authority} shows that this record hash existed no later than {time}. The public anchor {reference} shows that the checkpoint containing it existed no later than {time}." |
| Integrity check at issue | Record hash recomputed from stored content, receipt signature, timestamp token, inclusion proof, consistency proof to the current checkpoint, and write-once storage status. Each with its result and check time. |
| Capture mode | `direct`, `server_only`, `deferred` or `imported`, with one sentence on what that means for when the record was made |
| Later history | Annotations with times (dispute, consent withdrawal, supersession, legal hold) and earlier certificates for the record |
| Process in force | System description version, jurisdiction packs and versions applied, the time source used |
| Limits | A fixed text (below) |
| Seal | Certificate hash, signed receipt, external timestamp and ledger sequence for the certificate itself |

The fixed statement for a record captured directly from the signer's browser reads:

> Esign Comply's systems created record {record ID} by an automated process. Each event in it was recorded when Esign Comply's server received it from the signer's browser session, at the server receipt time shown. Esign Comply makes and keeps records of this kind in the regular course of providing its recording service to {customer}, and making them is its regular practice. The record was sealed at {time}. On {issue time} Esign Comply recomputed the hash of the stored record and found that it matches the hash committed to the seal, the external timestamp token and the ledger checkpoint, with the results shown below. This statement was issued on {issue time}; the record it describes was made at the times shown in the chronology.

For `deferred` and `imported` records the statement does not say the record was made at or near the time of the act. It says that you reported the signing act at the receipt time, that you assert when it occurred, and that Esign Comply did not observe it. For `server_only` records it says the events were received from your server and not from the signer's browser.

## What the statement does not say

Every certificate prints this limits text:

> This statement describes when and how Esign Comply's record was made and whether it has changed since. It does not establish who the signer was, the signer's capacity or authority, that the signer read the documents, or that any agreement is valid or enforceable. Times reported by the signer's browser are reported, not verified. A court decides admissibility and weight. The automated statement is not a custodian declaration. A custodian-signed unsworn declaration is available on request where the forum permits it. This document is not a qualified certificate, a qualified electronic time stamp, or a qualified electronic seal.

The external timestamp bounds when the record hash existed. It does not show when the person acted. No free text from you appears on the statement except `reference` (120 characters at most), printed as "Requester reference (asserted)". IP addresses, raw device data and drawn-signature images are left out by default.

## Before you request

| Record status | Result |
|---|---|
| `timestamped` or `anchored` | A certificate can be issued. If the public anchor is not available yet, its line reads "pending". |
| `recorded` or `pending_seal` | [`record_not_timestamped`](https://esigncomply.com/docs/api/errors.md#record_not_timestamped) (409) with `Retry-After: 30`. The external timestamp normally follows within 60 seconds. |
| `disputed` | A certificate can be issued. The dispute appears under Later history. |
| `voided` | [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found) |
| Locked under the earlier Starter quota rule | [`quota_exceeded`](https://esigncomply.com/docs/api/errors.md#quota_exceeded) (402). Records sealed now are not locked. |

If any integrity check fails at issue, nothing is issued. The request returns [`certificate_verification_failed`](https://esigncomply.com/docs/api/errors.md#certificate_verification_failed), an integrity incident is opened, and `certificate.failed` is sent. Do not retry: contact support with the request ID.

## Price

One unit is one issued single-record certificate, or each 100 records (or part of 100) covered by a set certificate. Issuing a certificate is not a signature event and uses no event quota.

| Plan | Included per subscription year | Price beyond the allowance | Records per set request |
|---|---|---|---|
| Free | None for live records. Test certificates are unlimited and watermarked "TEST". | Not sold | 10 (test certificates) |
| Starter, $200 per year | None | $20 per certificate, charged only when one is issued | Up to 100 |
| Unlimited, $1,200 per year | 25 | $20 per certificate | Up to 10,000 |
| Enterprise, from $10,000 per year | Unlimited | Included | By contract |

Certificates for live records are on paid plans. On the Free plan a certificate request or quote for a live record returns `403` [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable). Test certificates are free and watermarked "TEST" on every plan.

The Unlimited allowance is counted per domain subscription and per subscription year. It does not roll over and cannot be moved between domains. Included units are used first. Charged certificates are invoiced monthly in arrears to the payment method on file, one line per certificate. The same numbers are in [pricing.md](https://esigncomply.com/pricing.md).

| Plan | Activity in a year | Certificate cost |
|---|---|---|
| Starter | No certificates | $0 |
| Starter | 3 single-record certificates for one dispute | $60 |
| Starter | One set certificate covering 100 records | $20 |
| Unlimited | 18 single-record certificates | $0 (18 of 25 included) |
| Unlimited | 40 single-record certificates | $300 (25 included, 15 at $20) |
| Unlimited | One set certificate covering 2,500 records | $0 (25 units, all included) |

## Quote, then confirm

No charge is created without a recorded confirmation: a confirming click in the dashboard, or `confirm_charge: true` from a `full_access` key. A request covered by an allowance, by an Enterprise contract or by test mode needs no confirmation.

**1. Ask for a quote.** `POST /v1/certificates/quote` accepts a certificate request body and returns what it would cost. It never issues and never charges. `full_access` and `read_only` keys can call it.

```bash
curl https://esigncomply.com/v1/certificates/quote \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "contemporaneous_record", "record_id": "rec_Z4m8" }'
```

```json
{
  "object": "certificate_quote",
  "record_count": 1,
  "units": 1,
  "unit_amount": 2000,
  "amount": 2000,
  "currency": "usd",
  "allowance_remaining": 0,
  "month_to_date": 4000,
  "spend_limit": 20000,
  "charge_class": "charged",
  "units_included": 0,
  "units_charged": 1,
  "requires_confirmation": true
}
```

Amounts are integers in the smallest currency unit: `2000` is $20.00. `units_included` come from your allowance and `units_charged` are billed. For a set, send the same `filter` you will use for the request: the quote counts the matching records.

**2. Show the quote to a person.** An administrator approves the charge.

**3. Issue with `confirm_charge: true`.**

```ts
const { data: certificate, error } = await esc.records.certify("rec_Z4m8", {
  type: "contemporaneous_record",
  wording: "auto",
  reference: "Matter 2026-0412",
  share: { expires_in: 2592000 },
  confirm_charge: true, // only after an administrator approved the quote
});

if (error) throw new Error(`${error.code}: ${error.message}`);
console.log(certificate.id, certificate.pdf_url, certificate.billing.charge_class);
```

The same call over HTTP:

```bash
curl https://esigncomply.com/v1/records/rec_Z4m8/certificates \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cert-rec_Z4m8-matter-0412" \
  -d '{ "type": "contemporaneous_record", "wording": "auto", "reference": "Matter 2026-0412", "confirm_charge": true }'
```

A single-record certificate is synchronous (`201 Created`), with a target of under 10 seconds. If the request would incur a charge and does not carry `confirm_charge: true`, nothing is issued and the quote comes back in the error:

```json
{
  "error": {
    "type": "billing_error",
    "code": "certificate_charge_unconfirmed",
    "message": "This certificate costs $20.00. Resend the request with confirm_charge set to true to issue it.",
    "quote": { "units": 1, "unit_amount": 2000, "amount": 2000, "currency": "usd", "allowance_remaining": 0, "month_to_date": 4000, "spend_limit": 20000, "charge_class": "charged", "units_included": 0, "units_charged": 1 },
    "doc_url": "https://esigncomply.com/docs/api/errors#certificate_charge_unconfirmed",
    "request_id": "req_8Wd3"
  }
}
```

The issued certificate carries the full `statement`, the `verification` results, `pdf_url`, `json_url` and a `billing` object: `charge_class` (`included`, `charged`, `enterprise`, `test` or `reissue`), `units`, `unit_amount`, `amount`, `currency`, the `allowance` counters, `month_to_date`, `spend_limit` and `confirmed_by`. Treat `charge_class` as an open list. The full response is on the [Certificates API page](https://esigncomply.com/docs/api/certificates.md).

> **Never.** Do not build a certificate request that can run without a person confirming the charge. Do not send `confirm_charge: true` by default.

Idempotency matters here. A repeat with the same `Idempotency-Key` and body returns the same certificate and is never charged twice. A call without a key, or with a new key, issues a new certificate with a new issue time. Earlier certificates stay retrievable and verifiable.

## Sets of records

One certificate can cover many records: one statement plus a manifest that lists every record with its hash, its times and its check results. In the JSON form the manifest is under `statement.manifest`.

```http
POST /v1/certificates
Authorization: Bearer esc_test_us_...
Content-Type: application/json

{
  "type": "contemporaneous_record_set",
  "filter": { "version_id": "dv_3kT9", "created_after": "2026-12-01T00:00:00Z", "created_before": "2027-06-01T00:00:00Z" },
  "wording": "US-NY",
  "reference": "Arbitration clause, first half of the term",
  "confirm_charge": true
}
```

The call returns `202 Accepted` with `status: "processing"` and a `billing` object with the unit count. The `certificate.issued` webhook carries the certificate ID when it is ready, or poll `GET /v1/certificates/{id}`. The target is under 10 minutes per 1,000 records.

- The filter is one of `record_ids[]`, `signer_external_id`, `document_id` or `version_id`, each optionally bounded by `created_after` and `created_before`.
- A set of 250 records is three units. A set that needs more units than your allowance has left uses what remains and charges the rest. The quote shows both numbers.
- A request above your plan's set size returns [`certificate_set_too_large`](https://esigncomply.com/docs/api/errors.md#certificate_set_too_large) with the count.
- Records that fail a precondition are listed in the manifest as excluded, with the reason. They are never silently dropped.
- Set certificates identify signers by external ID only.
- A filter that matches no records returns `400 invalid_request`.
- At most five set jobs run per domain at a time. A sixth returns [`rate_limit_exceeded`](https://esigncomply.com/docs/api/errors.md#rate_limit_exceeded) with `Retry-After`.
- If an integrity check fails during the job, the certificate ends with `status: "failed"` and a `failure` object, `certificate.failed` is sent, and nothing is charged.

## Spend limit

Each domain has a monthly certificate spend limit: $200 by default. An owner can set it from $0 to $5,000 in the dashboard, or higher on request. A limit of $0 switches paid certificates off. Through the API, send `certificate_spend_limit` in cents to `PATCH /v1/domains/{id}` with a `full_access` key.

- A request that would pass the limit returns [`certificate_spend_limit_reached`](https://esigncomply.com/docs/api/errors.md#certificate_spend_limit_reached) and issues nothing.
- A charged certificate on a domain with no valid payment method returns [`payment_method_required`](https://esigncomply.com/docs/api/errors.md#payment_method_required). The same code is returned while an invoice for the domain is unpaid. Certificates already issued stay valid and verifiable, and recording, evidence reports and verification are not affected.
- Owners are notified at 80% and 100% of the limit, and the `certificate.spend_threshold_reached` webhook is sent.
- `GET /v1/usage` reports `certificates: { included, used, remaining, charged_units, resets_at, charged_month_to_date, spend_limit, unit_amount }`.

## What is not charged

- Test-mode certificates.
- A request that is refused or fails, including a set job that fails.
- Downloads, JSON retrieval, share links and verification of an issued certificate.
- An idempotent repeat.
- One re-issue for the same record or set within 30 days of a certificate whose public-anchor line read "pending". Send `reissue_of: "crt_7Hd2"`.
- A certificate re-issued to correct an Esign Comply error.

Only you pay Esign Comply. A signer, the holder of a share link or any other reader is never charged, and opening or verifying an issued certificate is free for everyone. Certificate charges are not refunded on a plan change or a cancellation.

## Share links

A share link lets someone outside your account open the certificate and run verification without signing in.

- Create one with `share: { "expires_in": 2592000 }` on the request, or later with `POST /v1/certificates/{id}/share`. `expires_in` is in seconds: 60 at least, 90 days at most, 30 days when omitted. Only an issued certificate can be shared.
- The response carries `share_url` and `share_expires_at`. The link carries an access secret in the URL fragment, which browsers do not send to servers. The secret is shown once and stored only as a hash, so keep the URL.
- Revoke every active link for a certificate with `DELETE /v1/certificates/{id}/share`. Opens are counted and shown on the certificate under `share`.
- Without the certificate file or the secret, a certificate ID reveals nothing.

```bash
curl https://esigncomply.com/v1/certificates/crt_7Hd2/share \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "expires_in": 2592000 }'
```

```json
{
  "object": "certificate_share",
  "certificate_id": "crt_7Hd2",
  "id": "shr_2Lp7",
  "share_url": "https://esigncomply.com/verify/c/crt_7Hd2#<secret>",
  "share_expires_at": "2026-12-21T18:40:02.117Z"
}
```

Third parties do not request certificates. You issue one and share it.

## Wording variants

`wording` is `auto` (the packs applied on the record) or a pack code that names the forum's variant, for example a record made under `US-CA` with a dispute before a New York court. A code that is not in the catalogue returns [`jurisdiction_unknown`](https://esigncomply.com/docs/api/errors.md#jurisdiction_unknown). It changes the statement paragraph only: the timing wording, the declaration form and the notice reminder. The underlying facts do not change, and `wording` never changes ceremony rules.

`include` is empty by default. `["supplements"]` adds a list of customer-supplied material for the record under the sentence "The following material was supplied by {customer}. Esign Comply received it at the times shown and did not verify its contents." `["network"]` adds network facts where they were captured and you confirm the need. It is refused with [`certificate_field_unavailable`](https://esigncomply.com/docs/api/errors.md#certificate_field_unavailable) for records that hold no network facts, which includes every record made under EU minimal capture.

## Custodian-signed form

`type: "custodian_certification"` requests a separate service: a named Esign Comply records custodian reviews the automated statement and signs a dated, unsworn declaration, printed as "Certification of Custodian of Records", with the automated statement attached as an exhibit.

- It is asynchronous. The request returns `202 Accepted` with `status: "requested"` and a `service` object that restates the form, the delivery target and the price. `status` then moves through `in_review` to `issued`. The target is 5 business days.
- It is a live-mode service on paid plans. In test mode, and on the Free plan, the request returns [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable).
- Price: Starter $250 per request. Unlimited: 5 included per subscription year, then $250 per request. Enterprise: by contract. It does not use the certificate allowance.
- It covers facts Esign Comply observed and records it made. It does not cover facts you asserted or who the signer was.
- A notarized affidavit is not offered.

## Test mode

Certificates for test records are free, carry the "TEST" watermark, are sealed with the test key and are not anchored publicly. `billing.charge_class` is `test`. Use them to build and review the request flow, including the quote step, before go-live. See [Test mode](https://esigncomply.com/docs/guides/test-mode.md).

## Signer-requested certificates (Planned)

> **Planned.** `POST /v1/receipts/{receipt_token}/certificates` is not part of the current API.

A signer would request a certificate for their own record from the signer view. The option is off unless you enable it per profile. When on, each request uses your allowance or is charged to you within the spend limit, never to the signer. Until then such a request is refused with [`signer_certificates_disabled`](https://esigncomply.com/docs/api/errors.md#signer_certificates_disabled).

## Standing issue (Planned)

> **Planned.** The Enterprise profile option `certify_on_anchor` is not available yet.

It would issue the automated statement when a record reaches `anchored` and add it to the evidence package. On Starter and Unlimited every certificate is requested and confirmed one at a time.

## Related

- [Evidence](https://esigncomply.com/docs/concepts/evidence.md) for the seal, the timestamp and the checkpoint the statement reports on.
- [Verification](https://esigncomply.com/docs/concepts/verification.md) for checking a certificate offline with `esigncomply-verify`.
- [Certificates API](https://esigncomply.com/docs/api/certificates.md) for every endpoint and field.
