Skip to content

Supplements and files

Send customer-supplied text, JSON and files about a record, session, signer, document version or domain, and read them back.

A supplement is material your team holds and Esign Comply never saw: the renewal reminder you emailed, a cancellation request that arrived by phone, a screenshot, a note from counsel. Esign Comply seals each supplement with its own receipt time, labels it customer-supplied, and keeps it apart from its own record. Sealing shows what Esign Comply received and when. It does not verify the contents and does not show that you performed a duty.

Supplements are not signature events and are never metered. Stored file bytes count toward the plan's storage allowance. For when and why to send them, read the supplements guide.

Method and path Key Purpose
POST /v1/supplements Secret (full_access, recording_access) Create a supplement.
GET /v1/supplements Secret (full_access, read_only) List supplements, with filters.
GET /v1/supplements/{id} Secret (full_access, read_only) Retrieve one supplement.
GET /v1/supplements/{id}/content Secret (full_access, read_only) Read text, data and file download links as stored.
DELETE /v1/supplements/{id} Secret (full_access) Withdraw a supplement.
GET /v1/supplement-types None (public) Catalogue of recognized types with suggested fields.
POST /v1/files Secret (full_access, recording_access) Start a file upload.
GET /v1/files/{id} Secret (full_access, recording_access) Read a file's status and trigger its hash check.

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

Create a supplement

POST /v1/supplements

Key: secret key with full_access or recording_access. Idempotent with Idempotency-Key: a repeat with the same key and body returns the same supplement and adds no ledger entry. The request body is limited to 600 KB.

At least one of text, data or files is required. Nothing else is.

Request fields

Field Type Required Description
subject object No Exactly one of record, session, signer (your external ID), document_version or domain. Omitted means the domain as a whole. A supplement on a completed session is attached to its record.
type string No A name from the type catalogue or any custom.<slug>. Unknown names are stored with type_recognized: false. Up to 80 characters.
occurred_at timestamp No When you say the thing happened. Asserted by you, never verified.
rule_ids string[] No Up to 20 rule IDs the material relates to, for example NY-05. An unknown ID is kept and returns the warning rule_unknown:<id>.
text string One of three UTF-8 text, up to 20,000 characters.
data any JSON One of three Any JSON value, up to 256 KB. Unknown fields inside it are kept as sent.
files string[] One of three Up to 10 file IDs from POST /v1/files. Each file must be uploaded and may belong to one supplement only.
labels string[] No Up to 20 strings for your own filtering.
supersedes string No ID of an earlier supplement this one corrects. Both stay visible.

Example request

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", "template": "renewal-v7", "provider_message_id": "0100018d-3f2a" },
    "files": ["fil_9Qe2"],
    "labels": ["renewal", "2027"]
  }'

Example response

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": 48213,
  "has_text": true,
  "has_data": true,
  "files": [
    { "id": "fil_9Qe2", "name": "renewal-notice.eml", "size": 48213, "sha256": "sha256:9d07...", "status": "stored" }
  ],
  "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:recipient_ref", "suggested_field_absent:content_sha256"]
}

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

Errors

  • invalid_request: none of text, data, files was sent; subject holds more than one key; data is over 256 KB; a file is still pending, already belongs to another supplement, or the record already has 200 supplements (10,000 for domain-level supplements).
  • subject_not_found: the record, session, signer, document version, file or superseded supplement does not exist in this domain and environment.
  • file_hash_mismatch, file_type_refused: a referenced file was rejected.
  • insufficient_permission: a read_only key cannot create supplements.

The supplement object

Field Type Description
id string sup_...
livemode boolean Live or test. Test supplements use the test ledger and are purged with test records after 30 days.
subject object { "record": "rec_..." }, { "session": "ses_..." }, { "signer": "<external ID>" }, { "document_version": "dv_..." } or { "domain": true }.
type, type_recognized string, boolean The type as sent, and whether it is in the catalogue or under custom..
provenance string Always customer_supplied.
occurred_at timestamp or null Your statement of when it happened (asserted).
received_at timestamp Esign Comply's server time on receipt (observed).
gap_seconds integer or null received_at minus occurred_at, in seconds.
rule_ids, labels string[] As sent.
content_hash string SHA-256 over the canonical form (RFC 8785) of { text, data, files (their hashes), subject, type, occurred_at } as stored.
size integer Total bytes of the referenced files.
has_text, has_data boolean Whether text or JSON is stored. Read it through the content endpoint.
files[] array id, name, size, sha256, status.
supersedes string or null The supplement this one corrects.
withdrawn, withdrawn_at boolean, timestamp Set after a withdrawal.
submitted_by string The key or member that sent it, for example key:key_2bQ1.
seal object receipt (signed receipt for the supplement, or null while signing is deferred), ledger_seq, and status: recorded, then timestamped, then anchored.
note string The fixed provenance sentence.
warnings string[] Non-blocking remarks. The list is open.

Supplements are immutable. To correct one, send another with supersedes. The record object lists the first 20 supplements for a record (id, type, received_at, occurred_at, content_hash, withdrawn), outside the record's sealed hash. Page through the rest with GET /v1/supplements?subject=rec_Z4m8.

Warnings

Warning Meaning
unknown_field:<path> A top-level field Esign Comply does not know was ignored.
rule_unknown:<id> A rule ID in rule_ids is not in the catalogue. It is kept as sent.
suggested_field_absent:<field> The type is in the catalogue and data is an object without one of its suggested fields. Nothing is required.
sensitive_data_masked A likely payment card number in text or data was masked before storage. The stored hash covers the masked content.
stored_as_supplement The report arrived through POST /v1/records/{id}/annotations with the earlier type notice.sent or cancellation.requested and was stored as a supplement.

Do not send payment card numbers, government identity numbers, passwords or health records. Files are stored as opaque bytes and are not inspected for content.

List supplements

GET /v1/supplements

Key: secret key with full_access or read_only.

Query parameters

Parameter Description
subject A record, session or document version ID, a signer's external ID, or the word domain for domain-level supplements.
type Exact type name.
rule_id Supplements that name this rule ID.
label Supplements that carry this label.
received_after, received_before RFC 3339 bounds on received_at.
limit, after, before Cursor pagination. See API conventions.

Example request

curl "https://esigncomply.com/v1/supplements?subject=rec_Z4m8&type=notice.sent&limit=20" \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"

Example response

200 OK

{
  "object": "list",
  "data": [
    {
      "object": "supplement",
      "id": "sup_5Hc1",
      "subject": { "record": "rec_Z4m8" },
      "type": "notice.sent",
      "provenance": "customer_supplied",
      "received_at": "2027-01-04T15:02:13.482Z",
      "content_hash": "sha256:41be...",
      "seal": { "receipt": "eyJhbGciOiJFUzI1NiIs...", "ledger_seq": 48122, "status": "timestamped" },
      "warnings": []
    }
  ],
  "has_more": false
}

Each item is the full supplement object. The example is shortened. Results are ordered by received_at, newest first.

Retrieve a supplement

GET /v1/supplements/{id}

Key: secret key with full_access or read_only.

Example request

curl https://esigncomply.com/v1/supplements/sup_5Hc1 \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"

Example response

200 OK with the supplement object.

Errors

  • not_found: no such supplement in this domain and environment.

Read supplement content

GET /v1/supplements/{id}/content

Key: secret key with full_access or read_only.

Returns the text and JSON as stored and a short-lived download link for each file. Content is never rendered as HTML or executed. File links are valid for 10 minutes and are served as attachments.

Example request

curl https://esigncomply.com/v1/supplements/sup_5Hc1/content \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"

Example response

200 OK

{
  "object": "supplement_content",
  "id": "sup_5Hc1",
  "provenance": "customer_supplied",
  "note": "Esign Comply received and sealed this material at the time shown and did not verify it.",
  "content_hash": "sha256:41be...",
  "withdrawn": false,
  "text": "Annual renewal reminder emailed to the address on the account. Template v7.",
  "data": { "notice_kind": "renewal_reminder", "channel": "email", "template": "renewal-v7", "provider_message_id": "0100018d-3f2a" },
  "files": [
    {
      "id": "fil_9Qe2",
      "name": "renewal-notice.eml",
      "size": 48213,
      "sha256": "sha256:9d07...",
      "status": "stored",
      "content_type": "message/rfc822",
      "download_url": "https://storage.example/renewal-notice.eml?token=..."
    }
  ]
}

text and data are null after a withdrawal or after the signer's data was erased. download_url is null for a withdrawn supplement or a file that is not stored.

Withdraw a supplement

DELETE /v1/supplements/{id}

Key: secret key with full_access.

Withdrawal deletes the content. The ledger keeps the hash and the receipt time, and a withdrawal entry is added. The supplement.withdrawn webhook is sent. A supplement under legal hold, or one listed on an issued certificate, cannot be withdrawn.

Example request

curl -X DELETE https://esigncomply.com/v1/supplements/sup_5Hc1 \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"

Example response

200 OK

{
  "object": "supplement",
  "id": "sup_5Hc1",
  "subject": { "record": "rec_Z4m8" },
  "type": "notice.sent",
  "content_hash": "sha256:41be...",
  "withdrawn": true,
  "withdrawn_at": "2027-02-01T09:12:44.310Z",
  "seal": { "receipt": "eyJhbGciOiJFUzI1NiIs...", "ledger_seq": 48122, "status": "anchored" },
  "warnings": []
}

Errors

List supplement types

GET /v1/supplement-types

Key: none. Public, cacheable for 5 minutes. Read the catalogue instead of hard-coding it: new types can be added at any time.

Example request

curl https://esigncomply.com/v1/supplement-types

Example response

200 OK

{
  "object": "list",
  "data": [
    {
      "object": "supplement_type",
      "type": "notice.sent",
      "use": "A notice the customer sent after or outside the ceremony: renewal reminder, price change, material change, trial ending",
      "suggested_fields": ["notice_kind", "channel", "recipient_ref", "content_sha256"]
    },
    { "object": "supplement_type", "type": "note", "use": "Anything else in plain words", "suggested_fields": [] }
  ],
  "has_more": false,
  "note": "Every field is optional. Any type name is accepted; names under custom.<slug> are yours to define."
}

Type catalogue

Every field is optional. The list says what is useful, not what is required.

Type Use Suggested fields in data
notice.sent A notice you sent after or outside the ceremony: renewal reminder, price change, material change, trial ending notice_kind, channel, recipient_ref, content_sha256 (or attach a file)
cancellation.requested The signer asked to cancel channel, requested_at, reference
cancellation.completed You completed the cancellation effective_at, refund
copy.delivered A copy of the signed document or a required disclosure reached the signer outside Esign Comply's receipt channel, document, delivered_at
paper_copy.delivered A paper copy was sent on request sent_at, carrier, fee
disclosure.delivered A statutory disclosure or notice given before or at signing by your own means disclosure, channel, language
translation.delivered A translation was given to the signer language, document, delivered_at
consent.delivered A consent or election was delivered to the entity giver, delivered_at
wage_notice.delivered A wage notice was given to an employee language, delivered_at
withdrawal.acknowledged You acknowledged an EU consumer's withdrawal on a durable medium through your own function channel, received_at, acknowledged_at
order.acknowledged You acknowledged an order or sent the contract confirmation on a durable medium channel, sent_at
payment.disclosure_presented Your own checkout showed a payment or price disclosure outside the recorded ceremony disclosure, shown_at
language.presented The language in which you negotiated or presented the offer language, channel
privacy_notice.presented Your privacy notice was shown or sent version, channel
consent.obtained A consent you collected by your own means, for example consent to electronic delivery taken by phone consent, method, obtained_at
record.delivered A record or document reached a person other than the signer who is entitled to it recipient_ref, channel, delivered_at
sign.posted A required sign or posting was displayed at a physical or online location location, posted_at
erasure.completed You completed an erasure or restriction in your own systems request_ref, completed_at
incident.reviewed You reviewed a dispute, complaint or incident touching a record reference, outcome
identity.checked Your own identity check result method, provider, result
counsel.reviewed Your counsel reviewed a document or flow reviewer, scope, reviewed_at
policy.snapshot Your own policy or process in force, for example your cancellation policy title, effective_at
screenshot An image of what your interface showed url, captured_at
correspondence Email, chat or call notes with the signer channel, direction
note Anything else in plain words None
custom.<slug> Any type you define Any

Create a file

POST /v1/files

Key: secret key with full_access or recording_access.

Text and JSON travel in the supplement call. Files go from your server straight to storage in three steps:

  1. POST /v1/files with the name, size and SHA-256 of the file. The response carries id and an upload_url on a path used only for that file. The URL is valid for 2 hours.
  2. PUT the bytes to upload_url. An upload never overwrites an existing object.
  3. Reference the file ID in files on POST /v1/supplements. Esign Comply reads the stored object, recomputes the hash and copies the file to write-once storage. A file is sealed when a supplement references it. A file not referenced within 7 days is deleted.

Request fields

Field Type Required Description
name string Yes File name, up to 255 characters. Executable extensions are refused.
size integer Yes Size in bytes. Must equal the bytes you upload.
content_type string No Media type, stored as sent.
sha256 string Yes SHA-256 of the bytes in lower-case hexadecimal, with or without the sha256: prefix.

Example request

curl https://esigncomply.com/v1/files \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "renewal-notice.eml",
    "size": 48213,
    "content_type": "message/rfc822",
    "sha256": "9d07..."
  }'

Example response

201 Created

{
  "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.201Z",
  "upload_url": "https://storage.example/object/upload/sign/customer_material/...?token=...",
  "upload_method": "PUT",
  "upload_expires_in": 7200
}

For a file larger than 6 MB the response also carries resumable_url and resumable_chunk_bytes (6 MB chunks). esc.files.upload() in the Node SDK performs all three steps, including chunked uploads.

Errors

  • file_too_large: size exceeds the plan's file limit.
  • file_type_refused: the name has an executable extension.
  • storage_limit_reached: the storage allowance is used up. Text and JSON supplements are still accepted, so a report is never lost for lack of file storage.

Complete upload example (Node)

import { createHash } from "node:crypto";
import { readFile } from "node:fs/promises";

const API = "https://esigncomply.com/v1";
const headers = {
  Authorization: `Bearer ${process.env.ESIGNCOMPLY_API_KEY}`, // esc_test_us_...
  "Content-Type": "application/json",
};

async function api(path: string, body: unknown, extra: Record<string, string> = {}) {
  const res = await fetch(`${API}${path}`, { method: "POST", headers: { ...headers, ...extra }, body: JSON.stringify(body) });
  const json = await res.json();
  if (!res.ok) throw new Error(`${json.error.code}: ${json.error.message}`);
  return json;
}

export async function reportNoticeSent(recordId: string, path: string) {
  const bytes = await readFile(path);
  const sha256 = createHash("sha256").update(bytes).digest("hex");

  // 1. Declare the file and get a signed upload URL.
  const file = await api("/files", {
    name: "renewal-notice.eml",
    size: bytes.length,
    content_type: "message/rfc822",
    sha256,
  });

  // 2. Send the bytes straight to storage.
  const put = await fetch(file.upload_url, {
    method: "PUT",
    headers: { "Content-Type": "message/rfc822" },
    body: bytes,
  });
  if (!put.ok) throw new Error(`Upload failed with status ${put.status}`);

  // 3. Reference the file from a supplement. The hash is checked here.
  return api(
    "/supplements",
    {
      subject: { record: recordId },
      type: "notice.sent",
      occurred_at: new Date().toISOString(),
      data: { notice_kind: "renewal_reminder", channel: "email" },
      files: [file.id],
    },
    { "Idempotency-Key": `notice-${recordId}-${sha256.slice(0, 16)}` },
  );
}

A failed report must never block your user's action. Catch the error, log it and retry later with the same Idempotency-Key.

Retrieve a file

GET /v1/files/{id}

Key: secret key with full_access or recording_access.

Returns the file object without the upload URL. If the file is still pending and the bytes have arrived, this call runs the check now: the stored bytes are hashed again and compared with the declared hash and size.

Example request

curl https://esigncomply.com/v1/files/fil_9Qe2 \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"

Example response

200 OK

{
  "object": "file",
  "id": "fil_9Qe2",
  "livemode": false,
  "name": "renewal-notice.eml",
  "content_type": "message/rfc822",
  "size": 48213,
  "sha256": "sha256:9d07...",
  "status": "stored",
  "supplement": "sup_5Hc1",
  "created_at": "2027-01-04T15:01:58.201Z"
}
status Meaning
pending Declared. The bytes have not arrived or have not been checked yet.
stored The bytes match the declared hash and size and were copied to write-once storage.
rejected The check failed. reject_reason says why: file_hash_mismatch, or file_type_refused with the detected kind (an executable, a script with an interpreter line, or an archive that contains an executable).
quarantined Reserved for a file held back by a content scan.
deleted Removed: never referenced within 7 days, or its supplement was withdrawn.

Limits

Free Starter Unlimited Enterprise
Maximum file size 10 MB 10 MB 25 MB 100 MB, or as contracted
Storage allowance for supplement files 2 GB 2 GB 20 GB, fair use Contracted
Limit Value
text 20,000 characters
data 256 KB of JSON
files per supplement 10
labels, rule_ids 20 each
Supplements per record 200
Domain-level supplements 10,000
Rate limit The key's plan limit. See API conventions.

Owners are notified at 80% and 100% of the storage allowance.

Rules in plain words

Rule What it means for your code
SM-1 Send at least one of text, data or files. A call with no type, subject, occurred_at or rule_ids succeeds.
SM-2 Sizes: 20,000 characters of text, 256 KB of JSON, 10 files, 20 labels, 20 rule IDs. Unknown rule IDs are kept with a warning.
SM-3 Unknown types are accepted with type_recognized: false. Unknown fields inside data are kept. Unknown top-level fields are ignored with unknown_field:<path>.
SM-4 subject holds exactly one key. A subject that does not exist returns 404 subject_not_found. No subject means the domain.
SM-5 Any content type is stored as opaque bytes, except executables and archives that contain one, which are refused. File size limits follow the plan.
SM-6 Above the storage allowance, new files return 402 storage_limit_reached. Text and JSON supplements are still accepted.
SM-7 At most 200 supplements per record and 10,000 at the domain level.
SM-8 An idempotent repeat returns the same supplement and adds no ledger entry.
SM-9 Supplements are immutable. Correct one by sending another with supersedes.
SM-10 Sealing is asynchronous, in the same pipeline as records: recorded, timestamped, anchored. The supplement.sealed webhook is sent when the external timestamp is attached.
SM-11 The record object lists a record's supplements outside its sealed hash. A supplement never changes a record, a conformance result, a required step or a rule outcome.
SM-12 POST /v1/records/{id}/annotations still accepts the earlier types notice.sent and cancellation.requested and stores them as supplements, so code built from earlier prompts keeps working. New integrations send reports here.

Related webhooks: supplement.received, supplement.sealed, supplement.withdrawn. See webhooks. In the evidence package, supplements for a record are exported in a separate customer_supplied/ folder. See evidence.