Skip to content

Signers

Read a signer's records and outstanding documents, record a withdrawal of consent, and start an erasure or restriction.

A signer is the person acting in a ceremony. You never create a signer directly: the first session that names a signer.external_id creates one, and later sessions with the same ID attach to it. Signers are addressed by your external ID, URL-encoded in the path.

Method and path Key Purpose
GET /v1/signers/{external_id}/records Secret (full_access, read_only) All records for one signer.
GET /v1/signers/{external_id}/status Secret (any permission) For each document: the latest version accepted, and whether the current version is outstanding.
POST /v1/signers/{external_id}/consents/withdraw Secret (full_access) Record withdrawal of consent to electronic records.
POST /v1/signers/{external_id}/erasure-requests Secret (full_access) Start a data-subject erasure or restriction.

External IDs and identity facts

  • external_id is your own identifier for the person, 1 to 255 characters, for example your user ID. It is unique per domain and per environment: test signers and live signers are separate.
  • Choose an ID that does not change. For a signup that has no account yet, generate a UUID on your server, use it as the external ID, and store it on the account you create after confirmation.
  • Everything you send about a signer (name, email, phone, class, country, region) is asserted by you. Esign Comply stores it, tags it asserted, and does not verify it.
  • When Esign Comply itself verifies control of an email address or phone number at L2, or a passkey at L3, that fact is stored as observed, with the time of verification. It shows control of the channel or credential. It does not establish legal identity or authority.
  • Identity facts are append-only and are encrypted under a key that belongs to that signer. That key is what erasure destroys.

List a signer's records

GET /v1/signers/{external_id}/records

Key: secret key with full_access or read_only.

Returns the signer's records, newest first, in the same summary shape as GET /v1/records. It accepts limit, after and before. It is the same as GET /v1/records?signer_external_id=....

Example request

curl "https://esigncomply.com/v1/signers/user_7c1d/records?limit=20" \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"

Example response

200 OK

{
  "object": "list",
  "data": [
    {
      "object": "record",
      "id": "rec_Z4m8",
      "livemode": false,
      "status": "anchored",
      "signed_at": "2026-11-21T15:03:20.291Z",
      "signature_level": "simple",
      "assurance_level": "L1",
      "capture_mode": "direct",
      "signer": { "external_id": "user_7c1d", "region": "US-CA" },
      "documents": [
        { "document_id": "doc_8Hq2", "version_id": "dv_3kT9" },
        { "document_id": "doc_Pv71", "version_id": "dv_Lm02" }
      ],
      "jurisdictions": { "applied": ["US-FED", "US-CA"] },
      "purpose": "account_signup",
      "record_hash": "sha256:5be7...",
      "seal": { "status": "anchored" },
      "warnings": 0,
      "advisories": 0,
      "annotations": [],
      "supplements": 0,
      "quota_locked": false,
      "verify_url": "https://esigncomply.com/verify/rec_Z4m8"
    }
  ],
  "has_more": false
}

An external ID with no records returns an empty list, not an error.

Errors

insufficient_permission for a recording_access key. invalid_request for a bad limit or cursor.

Retrieve signer status

GET /v1/signers/{external_id}/status

Key: secret key with any permission, including recording_access.

Answers the question a gate in your app asks: has this person accepted the version of each document that is in effect now? Use it in your authenticated layout and send the user to a re-acceptance screen when anything is outstanding. See the re-acceptance guide.

Query parameters

Parameter Description
documents Comma-separated document IDs to check, for example doc_8Hq2,doc_Pv71. Without it, the response covers the documents the signer has a record on. Send it to include documents the signer has never accepted.
locale Selects the translation that current resolves to, as on a session.

Example request

curl "https://esigncomply.com/v1/signers/user_7c1d/status?documents=doc_8Hq2,doc_Pv71" \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"

Example response

200 OK

{
  "object": "signer_status",
  "signer": { "external_id": "user_7c1d", "known": true, "erased": false },
  "documents": [
    {
      "document_id": "doc_8Hq2",
      "name": "Terms of Service",
      "type": "terms",
      "current_version": { "id": "dv_9Rw4", "version_label": "2027-02-01", "effective_at": "2027-02-01T00:00:00.000Z", "material_change": true },
      "accepted_version": { "id": "dv_3kT9", "version_label": "2026-11-21", "record_id": "rec_Z4m8", "signed_at": "2026-11-21T15:03:20.291Z" },
      "outstanding": true,
      "reason": "material_change",
      "summary_of_changes": "Added arbitration clause in section 14."
    },
    {
      "document_id": "doc_Pv71",
      "name": "Privacy Notice",
      "type": "privacy_notice",
      "current_version": { "id": "dv_Lm02", "version_label": "2026-11-21", "effective_at": "2026-11-21T00:00:00.000Z", "material_change": false },
      "accepted_version": { "id": "dv_Lm02", "version_label": "2026-11-21", "record_id": "rec_Z4m8", "signed_at": "2026-11-21T15:03:20.291Z" },
      "outstanding": false,
      "reason": null,
      "summary_of_changes": null
    }
  ],
  "outstanding": ["doc_8Hq2"]
}

Response fields

Field Description
signer.known false when no session has ever named this external ID. The call still returns 200.
signer.erased true after a completed erasure.
documents[].current_version The version in effect now, or null when none is.
documents[].accepted_version The latest version this signer has a record on, with the record ID and its signed_at. Null when the signer has never accepted the document.
documents[].outstanding true when the signer needs to accept the current version.
documents[].reason never_accepted, material_change, or null.
documents[].summary_of_changes The summary you published with the current version, present only when the document is outstanding. Show it on the re-acceptance screen.
outstanding[] IDs of the outstanding documents. An empty array means nothing to do.

When a document is outstanding

  • The signer has never accepted it (only reported for documents you list in documents).
  • A version published with material_change: true has taken effect after the version the signer accepted.

A newer version without material_change does not make earlier acceptances outstanding. Earlier records stay on file either way. Archived documents and voided records are left out.

Publishing a material version also sends the signer.reacceptance_required webhook for each signer with a record on an earlier version.

Caching

The status changes only when you publish a version or the signer completes a ceremony. Caching the result per user for a few minutes is reasonable.

POST /v1/signers/{external_id}/consents/withdraw

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

Records that a consumer withdrew consent to receive records electronically. Call it when the withdrawal reaches you through your own channels, such as support or account settings. Signers can also withdraw themselves from the link in every receipt.

Esign Comply adds a consent_withdrawn annotation to a record of that signer, timestamps it, and sends the consent.withdrawn webhook. Withdrawal is prospective only: earlier records remain. What you do after a withdrawal, such as switching the person to paper delivery, is your responsibility. See the consumer consent guide.

Request fields

Field Type Required Description
record_id string No The record to attach the withdrawal to. It must belong to this signer. Default: the signer's latest record in which electronic-records consent was given, otherwise the latest record.
scope string, up to 64 characters No What the withdrawal covers. Default electronic_records.
note string, up to 2,000 characters No Free text, for example how the request arrived.

Example request

curl https://esigncomply.com/v1/signers/user_7c1d/consents/withdraw \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: withdraw-user_7c1d-2027-01-04" \
  -d '{ "note": "Requested by phone on 2027-01-04. Ticket 55120." }'

Example response

201 Created

{
  "object": "consent_withdrawal",
  "signer": "user_7c1d",
  "record_id": "rec_Z4m8",
  "annotation_id": "ann_7Kp2",
  "recorded_at": "2027-01-04T15:02:13.482Z"
}

Errors

Code When
not_found No signer with this external ID, or record_id is not one of the signer's records.
subject_not_found The signer has no record to attach the withdrawal to.
insufficient_permission The key does not have full_access.

Start an erasure or restriction

POST /v1/signers/{external_id}/erasure-requests

Key: secret key with full_access.

Use it when you, as the controller of the signer's data, have decided to erase or restrict it, for example after a data-subject request. The request is processed in the same call and the response reports the outcome.

Request fields

Field Type Required Description
scope erasure or restriction No Default erasure.
basis string, up to 500 characters No Your reason or reference, stored with the request.

Example request

curl https://esigncomply.com/v1/signers/user_7c1d/erasure-requests \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "erasure", "basis": "Data-subject request DSR-2027-018." }'

Example response

201 Created

{
  "object": "erasure_request",
  "id": "ers_5Vt9",
  "signer": "user_7c1d",
  "scope": "erasure",
  "status": "completed",
  "erased": true,
  "note": "The signer's data key was destroyed. Record hashes, seals and ledger entries remain."
}
status Meaning
completed Done. An erasure carries erased: true. A restriction carries restricted: true: the signer is marked as restricted and the request is logged, and nothing is removed.
blocked_by_hold Nothing was erased. reason says why: a legal hold applies to at least one of the signer's records, or a retention floor recorded on a record has not expired. Release the hold with a legal_hold_released annotation, or wait for the floor to pass, then ask again.
rejected The request could not be carried out. reason gives the cause.

What erasure removes

Erasure destroys the signer's data key, so every field encrypted under it becomes unrecoverable:

  • the signer's identity facts (name, email, phone, passkeys);
  • the content of the signer's records, with their salts, and the data of their ceremony events, including IP addresses and user agents;
  • session context and metadata, annotation data, and the text and data of supplements attached to the signer or the signer's records;
  • the content of single-record certificates issued for those records, and the signer's receipt links.

What erasure leaves behind

  • The record hash, the signed receipt and the ledger entries. These are hashes and positions, with no readable signer content.
  • An erased entry in the ledger for each record, so the erasure itself is evidenced.
  • The record IDs. Each record's status becomes voided: GET /v1/records/{id} then returns 404, and the records leave list results unless you filter by status=voided.

Evidence packages you exported earlier are your copies and are not changed by this call. If the same external ID signs again later, the new record is encrypted under a new key. Earlier content stays unrecoverable.

Erasure cannot be undone. Export what you are required to keep before you call it.

Errors

not_found when no signer has this external ID. invalid_request for an unknown scope. insufficient_permission for keys without full_access.

  • Re-acceptance guide: the gate and the blocking screen.
  • Records: annotations and legal holds.
  • Supplements: report what you did after a withdrawal or a paper-copy request.
  • Webhooks: consent.withdrawn, signer.reacceptance_required.