# Supplements

> Send free text, JSON and files about a record, session, signer, document version or your domain, sealed on receipt and labeled customer-supplied.

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

You hold evidence that Esign Comply never sees: the renewal reminder you emailed, the cancellation request that arrived by phone, a screenshot, an export from your billing system, a note from counsel. A supplement lets you file that material with Esign Comply in the shape you already have it. The API hashes it as received, signs a receipt with the receipt time, adds a ledger entry, and keeps it apart from Esign Comply's own record.

Supplements come from your server only. The browser SDK has no supplement methods.

## What a supplement is

- Any content you send that Esign Comply did not observe: free text, arbitrary JSON, and files.
- Attached to exactly one subject: a record, a session, a signer, a document version, or your domain as a whole.
- Sealed on receipt. The seal shows that you sent these exact bytes to Esign Comply no later than the receipt time.
- Always labeled `provenance: "customer_supplied"`. Every response carries the sentence "Esign Comply received and sealed this material at the time shown and did not verify it."
- Immutable. You can supersede or withdraw a supplement, never edit it.

## What a supplement is not

- It is not verified. The seal says nothing about whether the content is true.
- It is never part of a record's sealed hash, and it never changes a record, a conformance result, a required step or a rule outcome.
- It is not evidence that you performed a duty. Esign Comply lists the obligations its rule packs identify for you and stores the reports you choose to send. It does not perform, monitor or verify those obligations.
- It is not a signature event and is never metered. Stored file bytes count toward your plan's storage allowance.
- It is not required. A failed report must never block your user's action.

## Send a supplement

At least one of `text`, `data` or `files` is required. Nothing else is. A call that omits `type`, `subject`, `occurred_at` and `rule_ids` succeeds.

```bash
curl https://esigncomply.com/v1/supplements \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: renewal-notice-user_7c1d-2027-01" \
  -d '{
    "subject": { "record": "rec_Z4m8" },
    "type": "notice.sent",
    "occurred_at": "2027-01-04T15:02:11Z",
    "rule_ids": ["NY-05"],
    "text": "Annual renewal reminder emailed to the address on the account. Template v7.",
    "data": { "notice_kind": "renewal_reminder", "channel": "email", "recipient_ref": "user_7c1d", "template": "renewal-v7" },
    "labels": ["renewal", "2027"]
  }'
```

The response is `201 Created`:

```json
{
  "object": "supplement",
  "id": "sup_5Hc1",
  "livemode": false,
  "subject": { "record": "rec_Z4m8" },
  "type": "notice.sent",
  "type_recognized": true,
  "provenance": "customer_supplied",
  "occurred_at": "2027-01-04T15:02:11.000Z",
  "received_at": "2027-01-04T15:02:13.482Z",
  "gap_seconds": 2,
  "rule_ids": ["NY-05"],
  "labels": ["renewal", "2027"],
  "content_hash": "sha256:41be...",
  "size": 0,
  "has_text": true,
  "has_data": true,
  "files": [],
  "supersedes": null,
  "withdrawn": false,
  "withdrawn_at": null,
  "submitted_by": "key:key_2bQ1",
  "seal": { "receipt": "eyJhbGciOiJFUzI1NiIs...", "ledger_seq": 48122, "status": "recorded" },
  "note": "Esign Comply received and sealed this material at the time shown and did not verify it.",
  "warnings": ["suggested_field_absent:content_sha256"]
}
```

With the server SDK:

```ts
import { esc } from "@/lib/esigncomply";

const { data, error } = await esc.supplements.create(
  {
    subject: { record: "rec_Z4m8" },
    type: "notice.sent",
    occurred_at: sentAt.toISOString(),
    rule_ids: ["NY-05"],
    text: "Annual renewal reminder emailed to the address on the account. Template v7.",
    data: { notice_kind: "renewal_reminder", channel: "email", recipient_ref: userId },
  },
  { idempotencyKey: `renewal-notice-${userId}-2027-01` },
);

if (error) {
  // Log it and move on. A failed report must not block the reminder itself.
  console.error("Esign Comply supplement failed", error.code, error.message);
}
```

Keys with `full_access` or `recording_access` can create supplements. Keys with `full_access` or `read_only` can list and read them. Only `full_access` keys can withdraw.

`seal.status` moves from `recorded` to `timestamped` to `anchored` in the same pipeline as records. The content hash covers the canonical form of the text, the data, the file hashes, the subject, the type and `occurred_at`.

## The two times

| Field | Who states it | Meaning |
|---|---|---|
| `occurred_at` | You (asserted) | When you say the thing happened. Optional. |
| `received_at` | Esign Comply (observed) | Server time when the supplement arrived. |
| `gap_seconds` | Computed | `received_at` minus `occurred_at`, in seconds. `null` without `occurred_at`. |

Reports print both times and the gap as a number. Send supplements close to the event: a short gap is a fact a reader can see for themselves.

## Subjects

`subject` holds exactly one key. Sending more than one returns `400 invalid_request`.

| Subject | Value | Notes |
|---|---|---|
| `record` | Record ID, `rec_Z4m8` | Listed on the record under `supplements[]` and in Part C of its evidence report. |
| `session` | Session ID, `ses_5nWq` | If the session already completed, the supplement is attached to its record. |
| `signer` | Your external ID, `user_7c1d` | For material about a person across records, such as a phone cancellation. |
| `document_version` | Version ID, `dv_3kT9` | For example counsel's review of that version. |
| `domain` | `true` | Material about your business as a whole, such as your cancellation policy. This is the default when `subject` is omitted. |

A subject that does not exist in this domain and environment returns [`subject_not_found`](https://esigncomply.com/docs/api/errors.md#subject_not_found).

## More examples

Free-form material with no type and no structure is equally valid:

```json
{
  "subject": { "signer": "user_7c1d" },
  "text": "Customer called support on March 3 to cancel. Agent: J. Ortiz. Ticket 55120."
}
```

A cancellation request with a little structure:

```json
{
  "subject": { "record": "rec_Z4m8" },
  "type": "cancellation.requested",
  "occurred_at": "2027-03-03T17:41:00Z",
  "rule_ids": ["CA-10"],
  "data": { "channel": "phone", "requested_at": "2027-03-03T17:41:00Z", "reference": "ticket-55120" }
}
```

## Types

`type` is a name from the public catalogue, or any name under `custom.<slug>` that you define. An unknown type is accepted and stored with `type_recognized: false`. It is never an error.

Read the catalogue at run time with `GET /v1/supplement-types` (no key needed) and do not hard-code it. Each entry has a `type`, a `use` sentence and `suggested_fields` for `data`. Every field is optional: the list tells you what is useful, not what is required. A suggested field you leave out adds the warning `suggested_field_absent:<field>` and nothing else.

| Type | Use |
|---|---|
| `notice.sent` | A notice you sent after or outside the ceremony: renewal reminder, price change, material change, trial ending |
| `cancellation.requested`, `cancellation.completed` | The signer asked to cancel; you completed the cancellation |
| `copy.delivered`, `paper_copy.delivered` | A copy reached the signer outside Esign Comply's receipt; a paper copy was sent on request |
| `disclosure.delivered`, `translation.delivered` | A disclosure or translation given by your own means |
| `order.acknowledged`, `withdrawal.acknowledged` | Order confirmation or withdrawal acknowledgment sent on a durable medium |
| `consent.obtained`, `identity.checked` | A consent or identity check you ran yourself |
| `counsel.reviewed`, `policy.snapshot` | Counsel's review; your own policy in force |
| `screenshot`, `correspondence`, `note` | An image of your interface; email, chat or call notes; anything else in plain words |

The full list is on the [Supplements API page](https://esigncomply.com/docs/api/supplements.md).

## Link a supplement to rules

`rule_ids` names the rules the supplement relates to, for example `NY-05`. Up to 20 IDs. The dashboard obligations list then shows a count of reports per item. The count is information for you. It is not a finding that the obligation was met. An ID that is not in the catalogue is kept and returns the warning `rule_unknown:<id>`.

## Correct or withdraw

Supplements are immutable. To correct one, send another with `supersedes`:

```json
{
  "subject": { "record": "rec_Z4m8" },
  "type": "notice.sent",
  "supersedes": "sup_5Hc1",
  "text": "Correction: the reminder used template v8, not v7."
}
```

Both stay visible. To withdraw one, call `DELETE /v1/supplements/sup_5Hc1` with a `full_access` key. The content is deleted, the ledger keeps the hash and the receipt time, and the supplement is returned with `withdrawn: true`. A supplement under legal hold, or listed on an issued certificate, cannot be withdrawn.

## Upload a file in three steps

Text and JSON travel in the API call. Files go straight from your server to storage, so they are not limited by the request body size.

**1. Declare the file.** Send its name, size and SHA-256.

```bash
FILE=renewal-notice.eml
SHA=$(sha256sum "$FILE" | cut -d' ' -f1)
SIZE=$(wc -c < "$FILE" | tr -d ' ')

curl https://esigncomply.com/v1/files \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"name\": \"$FILE\", \"size\": $SIZE, \"content_type\": \"message/rfc822\", \"sha256\": \"$SHA\" }"
```

```json
{
  "object": "file",
  "id": "fil_9Qe2",
  "livemode": false,
  "name": "renewal-notice.eml",
  "content_type": "message/rfc822",
  "size": 48213,
  "sha256": "sha256:9d07...",
  "status": "pending",
  "supplement": null,
  "created_at": "2027-01-04T15:01:58.120Z",
  "upload_url": "https://<storage-host>/...signed...",
  "upload_method": "PUT",
  "upload_expires_in": 7200
}
```

**2. Send the bytes** to `upload_url` with `PUT`. The URL is valid for 2 hours and works for that file only. Files above 6 MB also get a `resumable_url` and upload in chunks of `resumable_chunk_bytes`.

```bash
curl -X PUT "$UPLOAD_URL" -H "Content-Type: message/rfc822" --data-binary @renewal-notice.eml
```

**3. Reference the file ID** in a supplement.

```json
{ "subject": { "record": "rec_Z4m8" }, "type": "notice.sent", "files": ["fil_9Qe2"] }
```

When the supplement is created, Esign Comply reads the stored object, recomputes its hash and copies it to the write-once vault. The file is sealed as part of that supplement.

| Situation | Result |
|---|---|
| The bytes do not match the declared hash or size | File `status: "rejected"`, [`file_hash_mismatch`](https://esigncomply.com/docs/api/errors.md#file_hash_mismatch) |
| The file is an executable, or an archive that contains one | [`file_type_refused`](https://esigncomply.com/docs/api/errors.md#file_type_refused) |
| The file is larger than your plan allows | [`file_too_large`](https://esigncomply.com/docs/api/errors.md#file_too_large) |
| The storage allowance is used up | [`storage_limit_reached`](https://esigncomply.com/docs/api/errors.md#storage_limit_reached). Text and JSON supplements are still accepted. |
| The file was declared but not uploaded yet | `400 invalid_request` |
| The file already belongs to another supplement | `400 invalid_request` |

`GET /v1/files/fil_9Qe2` returns the file's status (`pending`, `stored`, `rejected`) and runs the hash check if the bytes have arrived. A file that no supplement references within 7 days is deleted.

The server SDK performs the three steps for you:

```ts
const { data: file, error } = await esc.files.upload("./renewal-notice.eml", {
  name: "renewal-notice.eml",
  contentType: "message/rfc822",
});
if (error) throw new Error(error.message);

await esc.supplements.create({ subject: { record: "rec_Z4m8" }, type: "notice.sent", files: [file.id] });
```

Files are stored as opaque bytes. They are never rendered as HTML or executed, and downloads are served as attachments through short-lived URLs from `GET /v1/supplements/{id}/content`.

## Limits

| Limit | Value |
|---|---|
| `text` | 20,000 characters |
| `data` | Any JSON value up to 256 KB |
| `files` | Up to 10 file IDs per supplement |
| `labels` | Up to 20 strings |
| `rule_ids` | Up to 20 rule IDs |
| File size | Starter 10 MB, Unlimited 25 MB, Enterprise by contract |
| File storage | Starter 2 GB, Unlimited 20 GB under fair use, Enterprise by contract |
| Supplements per record | 200 |
| Domain-level supplements | 10,000 |

Unknown top-level fields are ignored with the warning `unknown_field:<name>`. Unknown fields inside `data` are kept as sent. Test-mode supplements use the test ledger and are purged with test records after 30 days.

## Sensitive data

Do not send payment card numbers, government identity numbers, passwords or health records. Text and JSON are checked for likely card numbers. A match is masked before storage, the response carries the warning `sensitive_data_masked`, and the stored hash covers the masked content. Files are not inspected for content.

A supplement attached to a record or a signer is encrypted under that signer's key. Erasing the signer removes the content and leaves only the hash in the ledger.

## Context sent with the session

Two fields on `POST /v1/sessions` carry your own context at signing time. They are not supplements: they are sealed inside the record and labeled asserted.

| Field | Limit | Use |
|---|---|---|
| `context.notes` | 2,000 characters | Free text, for example "Signup A/B variant 7." |
| `context.extra` | 16 KB of JSON | Any structure, for example `{ "experiment": "signup-v7" }` |

No rule reads either field. Use a supplement for anything that happens after signing.

## Where supplements appear

- **Record object.** `GET /v1/records/{id}` lists the first 20 under `supplements[]` (ID, type, `received_at`, `occurred_at`, hash). Page through the rest with `GET /v1/supplements?subject=rec_Z4m8`.
- **Evidence report.** Part C, "Supplied by {customer} after signing": a list with type, both times and hash, under the sentence that Esign Comply received the material at the times shown and did not verify its contents. Parts A and B do not change. See [Observed and asserted](https://esigncomply.com/docs/concepts/observed-and-asserted.md).
- **Evidence package.** A `customer_supplied/` folder with `manifest.json` and the content as received, separate from `record.json`. Leave it out with `?supplements=false`. The offline verifier checks each item separately.
- **Certificates.** Only when the request sets `include: ["supplements"]`, and then as a list. Content is never reproduced on a certificate.
- **Signer view.** Never.

## Webhooks

| Event | Sent when |
|---|---|
| `supplement.received` | The supplement was accepted. Payload: `supplement_id`, `subject`, `type`, `content_hash`. |
| `supplement.sealed` | Its external timestamp was attached. Payload: `supplement_id`, `content_hash`, `timestamp_time`. |
| `supplement.withdrawn` | It was withdrawn. |

See [Webhooks](https://esigncomply.com/docs/api/webhooks.md) for signature verification.

## Earlier annotation types

Reports sent through `POST /v1/records/{id}/annotations` with the earlier types `notice.sent` and `cancellation.requested` are stored as supplements, so code built from earlier prompts keeps working. The response is the supplement object, with the warning `stored_as_supplement`. New integrations send customer reports to `POST /v1/supplements`. Annotations remain for state changes Esign Comply observes or enforces, such as a dispute or a consent withdrawal.
