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_idis 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: truehas 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.
Withdraw consent to electronic records
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
erasedentry 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 returns404, and the records leave list results unless you filter bystatus=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.
Related
- 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.