Supplements
Send free text, JSON and files about a record, session, signer, document version or your domain, sealed on receipt and labeled customer-supplied.
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.
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:
{
"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:
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.
More examples
Free-form material with no type and no structure is equally valid:
{
"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:
{
"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.
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:
{
"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.
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\" }"
{
"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.
curl -X PUT "$UPLOAD_URL" -H "Content-Type: message/rfc822" --data-binary @renewal-notice.eml
3. Reference the file ID in a supplement.
{ "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 |
| The file is an executable, or an archive that contains one | file_type_refused |
| The file is larger than your plan allows | file_too_large |
| The storage allowance is used up | 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:
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 undersupplements[](ID, type,received_at,occurred_at, hash). Page through the rest withGET /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.
- Evidence package. A
customer_supplied/folder withmanifest.jsonand the content as received, separate fromrecord.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 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.