# Signers

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

Source: https://esigncomply.com/docs/api/signers

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`](https://esigncomply.com/docs/api/records.md). It accepts `limit`, `after` and `before`. It is the same as `GET /v1/records?signer_external_id=...`.

**Example request**

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

**Example response**

`200 OK`

```json
{
  "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`](https://esigncomply.com/docs/api/errors.md#insufficient_permission) for a `recording_access` key. [`invalid_request`](https://esigncomply.com/docs/api/errors.md#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](https://esigncomply.com/docs/guides/reacceptance.md).

**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**

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

**Example response**

`200 OK`

```json
{
  "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`](https://esigncomply.com/docs/api/webhooks.md) 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](https://esigncomply.com/docs/guides/consumer-econsent.md).

**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**

```bash
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`

```json
{
  "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`](https://esigncomply.com/docs/api/errors.md#not_found) | No signer with this external ID, or `record_id` is not one of the signer's records. |
| [`subject_not_found`](https://esigncomply.com/docs/api/errors.md#subject_not_found) | The signer has no record to attach the withdrawal to. |
| [`insufficient_permission`](https://esigncomply.com/docs/api/errors.md#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**

```bash
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`

```json
{
  "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`](https://esigncomply.com/docs/api/errors.md#not_found) when no signer has this external ID. [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request) for an unknown `scope`. [`insufficient_permission`](https://esigncomply.com/docs/api/errors.md#insufficient_permission) for keys without `full_access`.

## Related

- [Re-acceptance guide](https://esigncomply.com/docs/guides/reacceptance.md): the gate and the blocking screen.
- [Records](https://esigncomply.com/docs/api/records.md): annotations and legal holds.
- [Supplements](https://esigncomply.com/docs/api/supplements.md): report what you did after a withdrawal or a paper-copy request.
- [Webhooks](https://esigncomply.com/docs/api/webhooks.md): `consent.withdrawn`, `signer.reacceptance_required`.
