# Certificates

> Request, quote, list, download and share the on-request Contemporaneous Record Statement for one record or a set of records.

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

In this API, "certificate" means one thing: the Contemporaneous Record Statement that Esign Comply issues on request. It is a dated statement of when and how a record was made, with the independent time evidence and a fresh integrity check run at the moment of issue. It is sealed, externally timestamped and added to the domain ledger. It is not the per-record PDF: that is the evidence report, which is included for every record and never charged (see [records](https://esigncomply.com/docs/api/records.md)).

A certificate describes when Esign Comply made its record and whether the stored bytes still match the sealed hash. It does not establish who the signer was, when the person actually acted, or whether any agreement is valid. For what the statement says, prices per plan and the spend limit, read the [certificates guide](https://esigncomply.com/docs/guides/certificates.md).

| Method and path | Key | Purpose |
|---|---|---|
| `POST /v1/records/{id}/certificates` | Secret (`full_access`) | Issue a certificate for one record. Synchronous. |
| `POST /v1/certificates` | Secret (`full_access`) | Issue one certificate over a set of records. Asynchronous. |
| `POST /v1/certificates/quote` | Secret (`full_access`, `read_only`) | Return what a request would cost. Issues nothing. |
| `GET /v1/certificates` | Secret (`full_access`, `read_only`) | List certificates. |
| `GET /v1/certificates/{id}` | Secret (`full_access`, `read_only`) | Retrieve a certificate as JSON, with its statement. |
| `GET /v1/certificates/{id}/pdf` | Secret (`full_access`, `read_only`) | Download the certificate as PDF. |
| `POST /v1/certificates/{id}/share` | Secret (`full_access`) | Create a time-limited share link. |
| `DELETE /v1/certificates/{id}/share` | Secret (`full_access`) | Revoke the share links of a certificate. |
| `POST /v1/receipts/{receipt_token}/certificates` | Signer link | Planned. Signer requests a certificate for the signer's own record. |

## Permissions and charges

| Key permission | Issue and share | List, read, download, quote | Can incur a charge |
|---|---|---|---|
| `full_access` | Yes | Yes | Yes, with `confirm_charge: true` |
| `read_only` | No | Yes | No |
| `recording_access` | No | No | No |

A leaked application key with `recording_access` can never issue a certificate or create a charge.

Issuing a certificate is not a signature event and uses no event quota. It is charged per plan: Starter has none included, Unlimited includes 25 per subscription year, Enterprise includes them all, and test mode is free and watermarked "TEST" on every plan. Certificates for live records are on paid plans: on the Free plan a request or a quote for a live record returns `403` [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable). The numbers are on the [pricing page](https://esigncomply.com/pricing). A request that would create a charge must carry `confirm_charge: true`. Without it nothing is issued and the API returns `402 certificate_charge_unconfirmed` with a `quote`. Downloads, share links, verification and refused or failed requests are never charged.

> **Never.** Do not build a certificate request that can run without a person confirming the charge. Show the quote to an administrator and send `confirm_charge: true` only after they approve.

## Issue a certificate for one record

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

Key: secret key with `full_access`. Idempotent with `Idempotency-Key`: a repeat with the same 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.

The record must be `timestamped` or `anchored`. A `disputed` record can be covered by a certificate: the dispute appears under later history.

**Request fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string | No | `contemporaneous_record` (default) or `custodian_certification`. Unknown types return `400 invalid_request`. |
| `wording` | string | No | `auto` (default: the packs applied on the record) or one pack code that names the forum's variant, for example `US-NY`. It changes the wording variant only, never the facts. An unknown code returns `400 jurisdiction_unknown`. |
| `reference` | string | No | Your reference, up to 120 characters. Printed as "Requester reference (asserted)". |
| `include` | string[] | No | Empty by default. `"supplements"` adds a list of customer-supplied material for the record (type, both times, hash, size; never the content). `"network"` adds network facts where they were captured. |
| `share` | object | No | `{ "expires_in": <seconds> }`, 60 seconds to 90 days. Creates a share link with the certificate. |
| `confirm_charge` | boolean | When a charge results | Must be `true` to approve a charge. Not needed when the request is covered by an allowance, by an Enterprise contract, or in test mode. |
| `reissue_of` | string | No | ID of an earlier certificate for the same record whose public-anchor line read "pending". One re-issue within 30 days is free. |

**Example request**

```http
POST /v1/records/rec_Z4m8/certificates
Authorization: Bearer esc_live_us_...
Content-Type: application/json
Idempotency-Key: cert-rec_Z4m8-matter-0412

{
  "type": "contemporaneous_record",
  "wording": "auto",
  "reference": "Matter 2026-0412",
  "include": [],
  "share": { "expires_in": 2592000 },
  "confirm_charge": true
}
```

**Example response**

`201 Created`. The `statement` object is shortened here.

```json
{
  "object": "certificate",
  "id": "crt_7Hd2",
  "type": "contemporaneous_record",
  "status": "issued",
  "livemode": true,
  "record_ids": ["rec_Z4m8"],
  "record_count": 1,
  "issued_at": "2026-11-21T18:40:02.117Z",
  "requested_by": { "class": "customer", "key_id": "key_2bQ1" },
  "reference": "Matter 2026-0412",
  "wording": ["US-FED", "US-CA"],
  "include": [],
  "capture_mode": "direct",
  "chronology": {
    "first_event_received_at": "2026-11-21T15:02:09.118Z",
    "final_event_received_at": "2026-11-21T15:02:41.902Z",
    "record_committed_at": "2026-11-21T15:02:41.951Z",
    "receipt_signed_at": "2026-11-21T15:02:42.006Z",
    "external_timestamp": { "authority": "tsa_primary", "time": "2026-11-21T15:02:44.000Z", "serial": "5f3a..." },
    "checkpoint": { "id": "chk_18f2", "time": "2026-11-21T15:03:00.000Z", "tree_size": 48130 },
    "public_anchor": { "kind": "ots", "time": "2026-11-21T16:00:04.000Z", "ref": "https://a.pool.opentimestamps.org", "provider": "a.pool.opentimestamps.org" }
  },
  "intervals_ms": {
    "final_event_to_commit": 49,
    "commit_to_receipt": 55,
    "receipt_to_external_timestamp": 1994,
    "receipt_to_checkpoint": 17994,
    "receipt_to_public_anchor": 3442000
  },
  "statement": {
    "title": "Contemporaneous Record Statement",
    "statement": "Esign Comply's systems created record rec_Z4m8 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. ...",
    "limits": "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, ..."
  },
  "verification": {
    "checked_at": "2026-11-21T18:40:01.530Z",
    "record_hash": "pass",
    "receipt_signature": "pass",
    "ledger_entry": "pass",
    "timestamp_token": "pass",
    "inclusion_proof": "pass",
    "consistency_proof": "pass",
    "storage_lock": "pass",
    "detail": { "receipt_signature": "key esc-us-live-2026-11" }
  },
  "certificate_hash": "sha256:7ac1...",
  "seal": {
    "receipt": "eyJhbGciOiJFUzI1NiIs...",
    "ledger": {
      "format": "esc-ledger-v1",
      "domain_id": "dom_4Kx9",
      "environment": "live",
      "seq": 48213,
      "entry_type": "certificate",
      "subject_id": "crt_7Hd2",
      "subject_hash": "sha256:7ac1...",
      "prev_hash": "sha256:1be9...",
      "entry_hash": "sha256:c04d...",
      "created_at": "2026-11-21T18:40:02.117Z"
    },
    "ledger_seq": 48213,
    "timestamp_token": "pending"
  },
  "pdf_url": "https://esigncomply.com/v1/certificates/crt_7Hd2/pdf",
  "json_url": "https://esigncomply.com/v1/certificates/crt_7Hd2",
  "share": { "id": "shr_2Vk8", "url": "https://esigncomply.com/verify/c/crt_7Hd2#...", "expires_at": "2026-12-21T18:40:02.117Z", "opens": 0, "last_opened_at": null },
  "billing": {
    "charge_class": "charged",
    "units": 1,
    "unit_amount": 2000,
    "amount": 2000,
    "currency": "usd",
    "allowance": { "included": 0, "used": 0, "remaining": 0, "resets_at": "2027-03-01T00:00:00.000Z" },
    "month_to_date": 4000,
    "spend_limit": 20000,
    "confirmed_by": "key_2bQ1"
  },
  "reissue_of": null,
  "anchor_pending": false,
  "created_at": "2026-11-21T18:40:02.117Z",
  "share_url": "https://esigncomply.com/verify/c/crt_7Hd2#...",
  "share_expires_at": "2026-12-21T18:40:02.117Z"
}
```

When `share` was requested, the response carries the new link as `share`, with its `url`. `share.url` appears only in this response: the access secret is the part after `#`, it is shown once and stored only as a hash, so keep the URL if you need it. `share_url` and `share_expires_at` repeat `share.url` and `share.expires_at` under their earlier names and also appear only in this response. Without `share` in the request, `share` is `null` and the two fields are absent.

With `type: "custodian_certification"` the call returns `202 Accepted` with `status: "requested"` and a `service` object that describes the separate, person-signed service (printed title "Certification of Custodian of Records", an unsworn declaration, its price and the number included per year). It is available in live mode on paid plans, moves through `requested`, `in_review` and `issued`, and does not use the certificate allowance.

**Errors**

- [`record_not_timestamped`](https://esigncomply.com/docs/api/errors.md#record_not_timestamped) `409`: the external timestamp is not attached yet. Retry after the interval in `Retry-After`.
- [`certificate_charge_unconfirmed`](https://esigncomply.com/docs/api/errors.md#certificate_charge_unconfirmed) `402`: a charge would result and `confirm_charge` was not `true`. The error carries a `quote`.
- [`certificate_spend_limit_reached`](https://esigncomply.com/docs/api/errors.md#certificate_spend_limit_reached) `402`: the charge would pass the domain's monthly certificate spend limit. Carries a `quote`.
- [`payment_method_required`](https://esigncomply.com/docs/api/errors.md#payment_method_required) `402`: a charge would result and the domain has no valid payment method, or an invoice for the domain is unpaid.
- [`quota_exceeded`](https://esigncomply.com/docs/api/errors.md#quota_exceeded) `402`: the record was locked under the earlier Starter quota rule. Records sealed now are not locked.
- [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable) `403`: a certificate for a live record was requested on the Free plan.
- [`certificate_field_unavailable`](https://esigncomply.com/docs/api/errors.md#certificate_field_unavailable) `422`: `include: ["network"]` was requested for a record made without network capture, for example under EU minimal capture.
- [`certificate_verification_failed`](https://esigncomply.com/docs/api/errors.md#certificate_verification_failed) `503`: an integrity check failed at issue. Nothing is issued and nothing is charged. Do not retry. Contact support with the request ID.
- [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found) `404`: no such record, the record is `voided`, or `reissue_of` names no issued certificate.
- [`insufficient_permission`](https://esigncomply.com/docs/api/errors.md#insufficient_permission) `403`: the key is not `full_access`.

The unconfirmed-charge error looks like this:

```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_8Yb3..."
  }
}
```

## Issue a certificate for a set of records

`POST /v1/certificates`

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

One statement plus a manifest that lists every record with its times and check results. The call returns `202 Accepted` with `status: "processing"`. The `certificate.issued` webhook carries the certificate ID when it is ready, or poll `GET /v1/certificates/{id}`.

**Request fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string | No | `contemporaneous_record_set` (default), `contemporaneous_record` or `custodian_certification`. |
| `filter` | object | Yes | Selects the records. One of `record_ids` (array), `signer_external_id`, `document_id` or `version_id`, each optionally bounded by `created_after` and `created_before`. |
| `wording` | string | No | `auto` or a pack code, as for one record. |
| `reference` | string | No | Up to 120 characters. |
| `include` | string[] | No | As for one record. |
| `confirm_charge` | boolean | When a charge results | Must be `true` to approve the charge shown in the quote. |

A set is charged as one certificate for each 100 records, or part of 100, that it covers. A set of 250 records is three units. Included units are used first and the rest is charged: the quote shows both numbers. Records per request: Free 10 (test certificates only), Starter 100, Unlimited 10,000, Enterprise as contracted.

Records that fail a precondition (not yet timestamped, or locked under the earlier Starter quota rule) are listed in the manifest as excluded with the reason. They are never silently dropped. Signers are identified in the manifest by external ID only.

**Example request**

```http
POST /v1/certificates
Authorization: Bearer esc_live_us_...
Content-Type: application/json
Idempotency-Key: cert-set-arbitration-2026-h1

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

**Example response**

`202 Accepted`

```json
{
  "object": "certificate",
  "id": "crt_4Wn6",
  "type": "contemporaneous_record_set",
  "status": "processing",
  "livemode": true,
  "record_ids": ["rec_Z4m8"],
  "record_count": 250,
  "issued_at": null,
  "requested_by": { "class": "customer", "key_id": "key_2bQ1" },
  "reference": "Arbitration clause, first half 2026",
  "wording": ["US-NY"],
  "include": [],
  "verification": null,
  "certificate_hash": null,
  "seal": { "receipt": null, "ledger": null, "ledger_seq": null, "timestamp_token": "pending" },
  "share": null,
  "billing": {
    "charge_class": "charged",
    "units": 3,
    "unit_amount": 2000,
    "amount": 6000,
    "currency": "usd",
    "allowance": { "included": 0, "used": 0, "remaining": 0, "resets_at": "2027-03-01T00:00:00.000Z" },
    "month_to_date": 4000,
    "spend_limit": 20000,
    "confirmed_by": "key_2bQ1"
  },
  "reissue_of": null,
  "anchor_pending": false,
  "created_at": "2026-11-21T18:45:10.004Z"
}
```

`record_ids` lists at most the first 100 records. `record_count` is the full count. When the job finishes, `status` becomes `issued` and the units are settled against the records actually covered after exclusions. If a record fails an integrity check, the whole job ends with `status: "failed"` and a `failure` object, the `certificate.failed` webhook is sent, and nothing is charged.

A request with `type: "contemporaneous_record"` whose filter matches exactly one record is issued synchronously and returns `201`, like the single-record endpoint. To share a set certificate, create the link after issue with `POST /v1/certificates/{id}/share`.

**Errors**

- [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request) `400`: `filter` is missing or names none of the selectors, or it matches no records.
- [`certificate_set_too_large`](https://esigncomply.com/docs/api/errors.md#certificate_set_too_large) `422`: the set is over the plan's limit. The error carries `record_count` and `limit`.
- [`rate_limit_exceeded`](https://esigncomply.com/docs/api/errors.md#rate_limit_exceeded) `429`: five set certificates are already being prepared for this domain. Retry after the interval in `Retry-After`.
- The charge errors listed for one record: [`certificate_charge_unconfirmed`](https://esigncomply.com/docs/api/errors.md#certificate_charge_unconfirmed), [`certificate_spend_limit_reached`](https://esigncomply.com/docs/api/errors.md#certificate_spend_limit_reached), [`payment_method_required`](https://esigncomply.com/docs/api/errors.md#payment_method_required).
- [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable) `403`: a certificate for live records was requested on the Free plan.

## Quote a certificate

`POST /v1/certificates/quote`

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

Accepts any certificate request body and returns the charge it would incur. It never issues and never charges. For one record send an empty body, or the body you would send to the issue endpoint. For a set send `type` and `filter`. On the Free plan a quote for a live record returns `403` [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable).

**Example request**

```bash
curl https://esigncomply.com/v1/certificates/quote \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "contemporaneous_record_set",
    "filter": { "version_id": "dv_3kT9", "created_after": "2026-01-01T00:00:00Z" }
  }'
```

**Example response**

`200 OK`

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

| Field | Description |
|---|---|
| `record_count` | Records the request would cover. `1` unless a set is requested. |
| `units` | One per single-record certificate, or one per 100 records or part of 100 in a set. |
| `unit_amount`, `amount`, `currency` | Integers in the smallest currency unit. `amount` is what would be charged after the allowance. |
| `allowance_remaining` | Included units left this subscription year. `null` when the plan has no cap. |
| `units_included`, `units_charged` | How the units split between the allowance and a charge. |
| `month_to_date`, `spend_limit` | This month's certificate charges and the domain's monthly limit. |
| `charge_class` | See [the billing object](#the-billing-object). |
| `requires_confirmation` | `true` when the request needs `confirm_charge: true`. |

## List certificates

`GET /v1/certificates`

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

**Query parameters**

| Parameter | Description |
|---|---|
| `record_id` | Certificates that cover this record. |
| `status` | `processing`, `requested`, `in_review`, `issued` or `failed`. |
| `limit`, `after`, `before` | Cursor pagination. See [API conventions](https://esigncomply.com/docs/api.md). |

**Example request**

```bash
curl "https://esigncomply.com/v1/certificates?record_id=rec_Z4m8&status=issued" \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

**Example response**

`200 OK`

```json
{
  "object": "list",
  "data": [
    {
      "object": "certificate",
      "id": "crt_7Hd2",
      "type": "contemporaneous_record",
      "status": "issued",
      "livemode": true,
      "record_ids": ["rec_Z4m8"],
      "record_count": 1,
      "issued_at": "2026-11-21T18:40:02.117Z",
      "certificate_hash": "sha256:7ac1...",
      "seal": {
        "receipt": "eyJhbGciOiJFUzI1NiIs...",
        "ledger": { "format": "esc-ledger-v1", "domain_id": "dom_4Kx9", "environment": "live", "seq": 48213, "entry_type": "certificate", "subject_id": "crt_7Hd2", "subject_hash": "sha256:7ac1...", "prev_hash": "sha256:1be9...", "entry_hash": "sha256:c04d...", "created_at": "2026-11-21T18:40:02.117Z" },
        "ledger_seq": 48213,
        "timestamp_token": { "authority": "tsa_primary", "time": "2026-11-21T18:40:05.000Z" }
      },
      "pdf_url": "https://esigncomply.com/v1/certificates/crt_7Hd2/pdf",
      "json_url": "https://esigncomply.com/v1/certificates/crt_7Hd2",
      "share": { "id": "shr_2Vk8", "expires_at": "2026-12-21T18:40:02.117Z", "opens": 0, "last_opened_at": null }
    }
  ],
  "has_more": false
}
```

List items carry every field of the certificate object except `statement`, `chronology`, `intervals_ms` and `capture_mode`. The example is shortened. Newest first.

## Retrieve a certificate

`GET /v1/certificates/{id}`

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

Returns the full [certificate object](#the-certificate-object) including `statement`. Retrieval is never charged.

**Example request**

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

**Example response**

`200 OK` with the certificate object shown under [Issue a certificate for one record](#issue-a-certificate-for-one-record), without `share_url`, `share_expires_at` and `share.url`. Once a share link exists, `share` holds `{ id, expires_at, opens, last_opened_at }`. This JSON is the `certificate.json` the [offline verifier](https://esigncomply.com/docs/sdk/verify.md) reads: `seal.ledger` is the full ledger entry it recomputes.

**Errors**

- [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found): no such certificate in this domain and environment.

## Download a certificate as PDF

`GET /v1/certificates/{id}/pdf`

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

Returns `application/pdf` as an attachment named `<id>.pdf`. The PDF is in English and carries the same fields as the JSON. Test certificates carry the "TEST" watermark. Downloads are never charged.

**Example request**

```bash
curl https://esigncomply.com/v1/certificates/crt_7Hd2/pdf \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -o crt_7Hd2.pdf
```

**Example response**

`200 OK`

```http
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="crt_7Hd2.pdf"
Cache-Control: no-store
```

**Errors**

- [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request): the certificate is not `issued` yet, or its content was removed with its record.

## Create a share link

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

Key: secret key with `full_access`.

Creates a link that opens the certificate and runs verification without an account, for a court, an auditor or a counterparty. The link carries an access secret in the URL fragment. Every open is counted for you. Without the file or the secret, a certificate ID reveals nothing. Opening and verifying is free for everyone.

**Request fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `expires_in` | integer | No | Lifetime in seconds, 60 to 7,776,000 (90 days). Default 2,592,000 (30 days). |

**Example request**

```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 }'
```

**Example response**

`201 Created`

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

The URL is shown once. This response is not kept for idempotent replay, so a repeat creates another link.

**Errors**

- [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request): only an issued certificate can be shared.
- [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found): no such certificate.

## Revoke share links

`DELETE /v1/certificates/{id}/share`

Key: secret key with `full_access`.

Revokes every active share link of the certificate. The certificate itself stays issued and retrievable.

**Example request**

```bash
curl -X DELETE https://esigncomply.com/v1/certificates/crt_7Hd2/share \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

**Example response**

`200 OK`

```json
{ "object": "certificate_share", "certificate_id": "crt_7Hd2", "revoked": 1 }
```

## Request a certificate as a signer (Planned)

> **Planned.** Version 1.1. Not part of the current API.

`POST /v1/receipts/{receipt_token}/certificates`

Key: signer link. Called from the signer view after the one-time code, for the signer's own record only.

Signer requests are off unless you turn them on for the profile (`signer_certificates_enabled`). When on, the request issues a `contemporaneous_record` certificate for that signer's record, limited to 3 per record in 30 days. It uses your allowance or is charged to you within the spend limit. The signer is never charged. You receive `certificate.issued` with `requested_by.class: "signer"`. While signer requests are off the call is refused with [`signer_certificates_disabled`](https://esigncomply.com/docs/api/errors.md#signer_certificates_disabled).

## The certificate object

| Field | Type | Description |
|---|---|---|
| `id` | string | `crt_...` |
| `type` | string | `contemporaneous_record`, `contemporaneous_record_set` or `custodian_certification`. |
| `status` | string | `processing` (set job running), `requested` and `in_review` (custodian-signed form), `issued`, `failed`. Treat the list as open. |
| `livemode` | boolean | Test certificates are sealed with the test key, watermarked "TEST" and not anchored publicly. |
| `record_ids`, `record_count` | array, integer | Up to the first 100 record IDs, and the full count. |
| `issued_at` | timestamp or null | When the certificate was issued. |
| `requested_by` | object | `class` (`customer` or `signer`) and the key that made the request. |
| `reference` | string or null | Your reference, as sent. Asserted. |
| `wording` | string[] | Pack codes whose wording variant was used. |
| `include` | string[] | As requested. |
| `capture_mode` | string | `direct`, `server_only`, `deferred` or `imported`. For `deferred` and `imported` records the statement says the act was reported by the customer and not observed by Esign Comply. |
| `chronology` | object | Server receipt time of the first and final event, commit time, receipt signature time, external timestamp (`authority`, `time`, `serial`), checkpoint (`id`, `time`, `tree_size`) and public anchor (`kind`, `time`, `ref`, `provider`, or `"pending"`). |
| `intervals_ms` | object | Measured durations from the final event to commit, to receipt, to external timestamp, to checkpoint and to public anchor. `null` where a step has not happened. |
| `statement` | object | The full statement as sealed. See below. |
| `verification` | object | Result of each check run at issue and `checked_at`. Values: `pass`, `fail`, `pending`, `not_applicable`. Checks: `record_hash`, `receipt_signature`, `ledger_entry`, `timestamp_token`, `inclusion_proof`, `consistency_proof`, `storage_lock`. For a set: `checked_at`, `records_checked`, `records_excluded`. |
| `certificate_hash` | string | SHA-256 over the canonical form (RFC 8785) of `statement`. |
| `seal` | object | `receipt` (signed receipt for the certificate), `ledger` (the certificate's ledger entry: `format`, `domain_id`, `environment`, `seq`, `entry_type`, `subject_id`, `subject_hash`, `prev_hash`, `entry_hash`, `created_at`), `ledger_seq` (the same number as `ledger.seq`), and `timestamp_token`: `"pending"`, then `{ authority, time }`. `ledger` and `ledger_seq` are `null` until the certificate is issued. |
| `pdf_url`, `json_url` | string | Present once `status` is `issued`. |
| `share` | object or null | The active share link: `id`, `expires_at`, `opens`, `last_opened_at`. The link's `url` is included only in the response of the request that created it. |
| `billing` | object | See [the billing object](#the-billing-object). |
| `reissue_of` | string or null | The certificate this one re-issues. |
| `anchor_pending` | boolean | `true` when the public-anchor line read "pending" at issue. A later request includes the anchor. |
| `failure` | object | Only on `failed`: `code` and, for an integrity failure, `record_id` and `failed_checks`. |
| `created_at` | timestamp | When the request was accepted. |

### The statement

`statement` is generated only from sealed data and from the checks run at issue. The only free text from you is `reference`.

| Key | Content |
|---|---|
| `title` | "Contemporaneous Record Statement", with "(deferred submission)", "(imported record)" or "(set of records)" where that applies. |
| `certificate_id`, `issued_at`, `livemode`, `record_id`, `requester`, `reference`, `customer`, `domain` | Header fields. |
| `statement` | The fixed paragraph. It says the stored bytes match the sealed hash. |
| `capture_mode`, `capture_mode_meaning` | The capture mode and one plain sentence on what it means. |
| `chronology` | As above, plus `events[]`: for each ceremony event its `type`, `tag`, `browser_reported_time` (reported, not verified), `server_receipt_time` (observed) and `difference_ms`. |
| `intervals_ms` | Durations as numbers. |
| `independent_time_bound` | Two sentences: what the external timestamp token shows and what the public anchor shows. |
| `verification` | The integrity check at issue, with `detail`. |
| `record_hash` | The sealed record hash. |
| `later_history` | Annotations with times (dispute, consent withdrawal, supersession, legal hold) and earlier certificates for the record. |
| `customer_supplied` | Only with `include: ["supplements"]`: the fixed sentence and a list of `type`, `occurred_at`, `received_at`, `content_hash`, `size`. |
| `network` | Only with `include: ["network"]` and only where captured. |
| `process_in_force` | System description version, packs and versions applied, guidance release, time source. |
| `jurisdiction_wording` | `requested`, the pack `codes` used and their wording `variants`. |
| `limits` | The fixed limits text. |

A set statement replaces the per-record fields with `set` (`filter`, `requested`, `included`, `excluded`) and `manifest[]`: one row per record with `record_id`, `signer_external_id`, `record_hash`, `final_event_received_at`, `external_timestamp_time`, `checks` and `excluded` (with `reason` when excluded).

### The billing object {#the-billing-object}

| Field | Description |
|---|---|
| `charge_class` | `included` (from the plan allowance), `charged`, `enterprise`, `test` or `reissue`. Treat the list as open. |
| `units`, `unit_amount`, `amount`, `currency` | Units issued and the amount charged, as integers in the smallest currency unit. |
| `allowance` | `included`, `used`, `remaining`, `resets_at` for the subscription year. `included` and `remaining` are `null` when there is no cap. |
| `month_to_date`, `spend_limit` | This month's certificate charges and the domain's monthly limit. |
| `confirmed_by` | The key or member that confirmed a charge. `null` when nothing was charged. |

Charged certificates are invoiced monthly in arrears, one line per certificate. `GET /v1/usage` reports the allowance, the month's charges and the spend limit. See [account](https://esigncomply.com/docs/api/account.md).

## Rules in plain words

| Rule | What it means for your code |
|---|---|
| OC-1 | `type` is `contemporaneous_record`, `contemporaneous_record_set` or `custodian_certification`. Anything else is `400 invalid_request`. |
| OC-2 | `full_access` keys issue and share. `read_only` keys list, download and quote. `recording_access` keys have no certificate access and can never incur a charge. |
| OC-3 | Same `Idempotency-Key` and body: the same certificate. No key, or a new key: a new certificate with a new issue time. |
| OC-4 | One record is synchronous. A set is asynchronous. The custodian-signed form is asynchronous and reviewed by a person. |
| OC-5 | Set filters: `record_ids`, `signer_external_id`, `document_id` or `version_id`, optionally bounded by dates. Over the plan limit: `422 certificate_set_too_large`. Excluded records are listed with a reason. |
| OC-6 | `wording` is `auto` or a pack code for the forum's variant. It changes wording only. |
| OC-7 | `include` is empty by default. `supplements` adds a list, never content. `network` is refused with `422 certificate_field_unavailable` where network facts were not captured. |
| OC-8 | Share links last at most 90 days, carry the secret in the URL fragment, can be revoked, and count every open. |
| OC-9 | Signer requests are Planned and off by default. |
| OC-10 | If any integrity check fails, nothing is issued: `503 certificate_verification_failed`, an incident is opened and `certificate.failed` is sent. |
| OC-11 | Certificates never consume signature events. A charge needs `confirm_charge: true`. The response always carries `billing`. |
| OC-12 | Test certificates are watermarked "TEST", sealed with the test key and not anchored publicly. |
| OC-13 | The quote endpoint accepts any certificate request body and issues nothing. |
| OC-14 | `reissue_of` gives one free re-issue within 30 days of a certificate whose public-anchor line read "pending". Otherwise it is an ordinary request. |
| OC-15 | Amounts are integers in the smallest currency unit. `charge_class` is an open list. |
| OC-16 | `GET /v1/usage` reports certificate usage. The spend limit is set per domain by an owner. |

## Rate limits

Single-record requests are limited to 60 per minute per key, within the key's plan limit. A domain can have 5 set certificates in preparation at once. A sixth returns `429 rate_limit_exceeded` with `Retry-After: 60`.

## Webhooks

| Event | Sent when | `data` |
|---|---|---|
| `certificate.issued` | A certificate was issued. | `certificate_id`, `type`, `record_count`, `requested_by.class` |
| `certificate.failed` | An integrity check stopped a certificate. | `record_id`, `failed_checks`, `request_id` |
| `certificate.charged` | A certificate was charged. | `certificate_id`, `units`, `amount`, `currency` |
| `certificate.spend_threshold_reached` | The month's certificate spend reached 80% or 100% of the limit. | `threshold`, `month_to_date`, `spend_limit` |

See [webhooks](https://esigncomply.com/docs/api/webhooks.md) for the delivery format and signature verification, and [verification](https://esigncomply.com/docs/concepts/verification.md) for checking a certificate offline.
