Signature requests
==================

v1.1

Send a PDF for signature, follow each signer, and fetch the sealed result with its evidence log.

**Preview.** Signing is not open to clients yet. Where it is not configured, creating a request answers `503 SIGNING_UNAVAILABLE`; on test environments, files are sealed with a development certificate that has no legal weight. Field names and codes may still change before signing opens. Creating, inspecting, changing and sending answer `404 NOT_FOUND` for an organization that does not have Signatures turned on (ask us to turn it on); reading, downloading, cancelling, resending and correcting its requests keep working.

[How it works](#overview)
-------------------------

Every call takes your API key in the `X-API-Key` header, as described in [Authentication](https://app.holofin.ai/docs/api/v1.1/authentication/).

1. You create a request with the PDF, its signers and what the document is. Holofin checks that a simple signature is allowed for that document, cleans and freezes the PDF, and emails each signer a link of their own.
2. Each signer opens the link, enters a 6-digit code sent to the same address, is shown the document, ticks your acknowledgements, and signs by typing or drawing. Signers are invited at once and sign in any order.
3. When the last signer has signed, Holofin seals the file and emails the sealed copy to every signer and to `copy_to`. Follow it with [`GET /signature-requests/{id}`](#read) or a [webhook](#webhooks).

The signer makes a **simple electronic signature**, tied to an email address by a one-time code. Holofin then seals the result in its own name, with timestamps from an independent authority. The seal proves who sealed the file and that it has not changed since. It does not raise the signature above simple, and it does not verify who the signer is beyond the mailbox.

You never receive a signing link or a code: they go only to the signer's mailbox, so nobody on your side can sign in the signer's place. A wrong address cannot be fixed by forwarding the email. [Correct it](#correct) instead, which sends a new link.

### Statuses

| Status | Meaning |
| --- | --- |
| draft | Kept, not sent. Nothing has been checked beyond shapes and limits, and no evidence log exists yet. See [Drafts](#drafts). |
| waiting | Sent. At least one signer has not signed. |
| finalizing | Everyone signed; the file is being sealed, usually in under a minute. If the timestamp authority is down, Holofin retries and the request stays here: it never seals with its own clock. Still here after an hour: contact support. |
| completed | Sealed and delivered. `pdf_url` is set. |
| declined | A signer declined; the others can no longer sign. The signer's `decline_reason` says why. |
| expired | `expires_at` passed before everyone signed. |
| cancelled | You withdrew it. |
| failed | Refused at creation, before anything was sent. `failure.reason` is one of the [refusal codes](#refusals). |

A signer is `pending`, then `awaiting_consent` once the code is verified, then `signed` or `declined`. Each signer's `invitation` tells you whether the mail provider accepted the last email (`sent`) or it bounced (`failed`): when it bounced, [correct the address](#correct).

### When a request closes

A [webhook](#webhooks) tells you, or [read the request](#read). Then:

* `completed`: [download the sealed PDF](#pdf) and [the evidence log](#evidence) with your key, and keep both. `pdf_url` and `evidence_url` are API URLs, not public links.
* `declined`: the signer's `decline_reason` says why.
* `expired` or `cancelled`: the links no longer work. Create a new request to try again.

### Document types

A simple signature is not enough for every document. You declare what the document is in `document_type` and which country's law governs it in `country`, and Holofin applies this table (version `2026-11-draft-1`) before anything is sent. A country without its own column takes the strictest of the listed ones. The table is a safety net, not legal advice: what you declare, and whether a simple signature suits your document, stay your decision.

| document\_type | DE | FR | US |
| --- | --- | --- | --- |
| `ordinary_contract` Ordinary commercial or consumer contract | proceed | proceed | proceed |
| `vehicle_rental_damage_waiver` Vehicle rental with a damage-waiver disclosure | proceed | proceed | flag |
| `employment_termination` Ending an employment contract | refuse | warn | proceed |
| `statutory_written_form` Document under a statutory written-form rule | provider | flag | proceed |
| `consumer_suretyship_debt_ack` Consumer suretyship or acknowledgement of debt | refuse | flag | warn |
| `consumer_credit_loa` Consumer credit or leasing with a purchase option | provider | provider | flag |
| `court_or_statutory_notice` Court filing; default, foreclosure or eviction notice; cancellation of utilities or of health or life insurance; product recall | refuse | refuse | refuse |
| `real_estate_notarised` Real-estate transfer or notarised act | refuse | refuse | flag |
| `will_family_succession` Will, family law or succession | refuse | refuse | refuse |

`proceed`, `warn` and `flag` are sent; the decision and the reason for it are kept in the request's `guardrail` and its evidence. `provider` needs an advanced or qualified signature, which this API does not offer, and `refuse` is refused at every level. Both answer `422 SIGNATURE_REQUEST_REFUSED`, and the refusal is kept as a `failed` request you can read. One `provider` cell can be sent anyway: `consumer_credit_loa` in France and countries without a column, when you set `aml_identification_confirmed` because you identified the signers yourself. The request is then recorded as `flag`.

### Refusals

A refused request answers `422` with the reason and the id of the kept `failed` request:

```
{
  "error": {
    "code": "SIGNATURE_REQUEST_REFUSED",
    "message": "The lender's anti-money-laundering duty needs an advanced or qualified signature when the signature is the identification measure it relies on.",
    "reason": "provider_level_required",
    "signature_request_id": "sigreq_2bN7vC4xZ9kL1mQ5"
  }
}
```

| reason | What to do |
| --- | --- |
| document\_type\_excluded | A simple signature is not allowed for this document in this country. Sign it another way. |
| provider\_level\_required | The document needs an advanced or qualified signature here. Use a provider that offers one, or `aml_identification_confirmed` where it applies. |
| disclosure\_contact\_missing | `statutory_disclosures` is on without `disclosure_contact`. Send one. |
| intake\_encrypted | The PDF is password-protected or encrypted. Send it unprotected. |
| intake\_already\_signed | The PDF already carries a digital signature. Send the version before it was signed. |
| intake\_too\_many\_pages | More than 500 pages. Split the document. |
| intake\_no\_pages | The PDF has no pages. |
| intake\_page\_too\_large | A page is larger than 5000 points (1.76 m) on a side, or sets its own unit size (`/UserUnit`). Export it again at its real size. |
| intake\_optional\_content intake\_alternate\_images | The PDF has layers a reader can show or hide, or images with an alternate version for printing: the signer could sign a page that is not the one printed. Export or print it to PDF again without layers. |
| intake\_too\_complex | Reading or drawing the PDF takes more memory or time than intake allows, whatever its size in bytes: for example a very large image drawn inline, or pages with millions of drawing commands. Export or print it to PDF again from its source. |
| intake\_unreadable intake\_hybrid\_xref intake\_could\_not\_clean | The PDF cannot be read or safely rewritten. Export or print it to PDF again from its source. |

A refused request does not keep its `external_ref`: find it by the `signature_request_id` of the answer. [`POST /signature-requests/inspect`](#inspect) answers the same intake refusals as `422 DOCUMENT_REFUSED`, without the `intake_` prefix.

### Markers

With `"placement": "page"`, Holofin appends a signature page. With `"placement": "tags"`, it prints each mark where the document already says so. With `"placement": "fields"`, you give the boxes yourself: see [Fields](#fields).

| Marker | What prints there |
| --- | --- |
| [Signature 1] | The signature, in a box 200 by 56 points that starts at the marker's top left corner. |
| [Initials 1] | The signer's initials. |
| [Date 1] | The signing date, as YYYY-MM-DD. |

The number is the signer's place in `signers`: the first signs `[Signature 1]`, the second `[Signature 2]`, never matched by name. Write the marker exactly: capital first letter, one space, a number up to 99. The marker text is removed and the mark printed in its place. A signer with no `[Signature n]` in the document signs on an appended page. A marker numbered above the number of signers stays in the document as text. `[Date n]` prints the date in UTC. Run the PDF through [`POST /signature-requests/inspect`](#inspect) before sending to see where each marker prints; `"fits": false` means the mark would run off the page, so move the marker.

### Fields

With `"placement": "fields"`, you give each box yourself in `fields`, and no marker is needed in the document. A field names its page (from 1), its box in whole points from the top left corner of the page as displayed (`x`, `y`, `width`, `height`), and the signer by place in `signers`. `pages`, in the request and in [inspect](#inspect), gives each page's size in the same points.

| type | What prints there | Smallest box |
| --- | --- | --- |
| signature | The signature, the signer's name, the time and the request id. | 140 x 40 |
| initials | The signer's initials. | 24 x 14 |
| date | The signing date in UTC: DD/MM/YYYY when `language` is `fr`, YYYY-MM-DD in English. | 50 x 14 |
| name | The signer's name. | 40 x 14 |
| email | The signer's address. | 40 x 14 |
| text | Your own `value`, at most 500 characters, with `signer` null. It is printed into the document before it is frozen, so every signer reads it and `frozen_sha256` covers it. | 20 x 10 |

A box must lie inside its page and be at least the size above. A wrong field answers `400 INVALID_FIELD` with `field_index`, its place in `fields`. A signer without a `signature` field signs on an appended page. To initial every page, place one `initials` field per page; `initials_every_page` does not combine with fields.

### Attributes

* `id`string

  Kept if you send one, else given as `fld_<n>`.
* `type`string

  `signature`, `initials`, `date` (the day the signer signs, UTC), `name` and `email` are filled from the signer's act. `text` is your own text, printed into the document before it is frozen.
* `signer`integer | null

  The signer's place in `signers`, from 1. Null for `text`.
* `page`integer

  From 1.
* `x`integer

  Points from the left edge of the page.
* `y`integer

  Points from the top edge of the page.
* `width`integer
* `height`integer
* `value`string

  For `text` only: what to print, at most 500 characters.
* `group`string

  Fields that share a group move together in the editor, such as the initials added on every page. At most 64 characters.

### Drafts

Create with `"draft": true` to keep the request instead of sending it. Only shapes and limits are checked: a draft may have no title or signer yet. Its `editor_url` opens it in the Holofin app, where a person in your organization places the fields on the pages, adds files, and sends it; it is `null` while Signatures is not turned on in the app for your organization (ask us to turn it on). You can also finish it here: [change it](#update), then [send it](#send), which runs every check of a create.

Each change raises `revision`. Send the one you read with your change: if someone changed the draft in between, nothing is saved and the answer is `409 DRAFT_CHANGED`. A draft has no evidence log until it is sent, and one that was not sent within 30 days is deleted.

[The signature request object](#object)
---------------------------------------

Create, get, change, send, cancel, resend and correct all return it; the list returns an array of it. A `draft` carries its settings as you would send them, plus `revision`, `files` and `editor_url`, and no evidence.

### Attributes

* `id`string

  Starts with `sigreq_`.
* `status`string

  `draft` until it is [sent](#send), then `waiting` until every signer has signed, then `finalizing` while the file is sealed (usually under a minute), then `completed`. `declined`, `expired`, `cancelled` and `failed` are final too. See [statuses](#statuses).
* `title`string
* `external_ref`string | null

  Your reference, as sent on creation.
* `workflow_run_id`string | null

  Set when a workflow's signature step created the request.
* `level`string

  `native_simple`: a simple electronic signature.
* `verification`string

  How a signer proves control of a channel: a one-time code sent to the email address (`email_otp`) or by SMS to the phone (`sms_otp`).
* `language`string

  One of `fr`, `en`.
* `placement`string

  One of `page`, `tags`, `fields`.
* `initials_every_page`boolean
* `document_type`string
* `country`string
* `is_consumer`boolean
* `guardrail`object

  What the [document-type check](#document-types) decided: `decision` (`proceed`, `warn` or `flag` on a sent request; `provider` or `refuse` on a `failed` one), `note`, the reason for that cell of the table, and its `version`.
* `page_count`integer

  Pages of the frozen document.
* `pages`array of object

  `number`, `width` and `height` of each page as displayed, in points: the space [fields](#fields) are placed in.
* `fields`array of object

  The [fields](#fields) placed on the pages, for `placement: fields`.
* `revision`integer

  On a `draft` only: its version. Send it back with a [change](#update) so that a change made elsewhere in between is not overwritten.
* `files`array of object

  On a `draft` only: the files it was built from, in order, each with `name`, `page_count` and `converted` (true for an office document).
* `editor_url`string | null

  On a `draft` only: where a person in your organization opens it in the Holofin app to place fields and send it. `null` while Signatures is off in the app for your organization: finish the draft through the API.
* `signers`array of object

  [Signer objects](#signer-object), in the order you sent them. All are invited at once and sign in any order.
* `copy_to`array of string

  Addresses that receive the signed copy.
* `failure`object | null

  On a `failed` request: `reason`, one of the [refusal codes](#refusals), and `detail`, a sentence for a person.
* `created_at`string
* `sent_at`string | null
* `expires_at`string | null
* `completed_at`string | null

  When the request reached a final status.
* `retention_until`string | null

  When a completed request, its PDF and its evidence are deleted, 10 years after sealing. Null otherwise: a request that closed unsigned is deleted a year after it closed.
* `frozen_sha256`string | null

  SHA-256 of the document the signers saw, after intake.
* `sealed_sha256`string | null

  SHA-256 of the sealed PDF.
* `evidence`object

  `event_count` and `head`, the hash of the last event of the [evidence log](#evidence).
* `pdf_url`string | null

  Where to [download the sealed PDF](#pdf) once `completed`. An API URL: call it with your key, it is not a public link.
* `evidence_url`string

  Where to [download the evidence log](#evidence), with your key.

### The signer object

### Attributes

* `id`string

  Starts with `sigrcp_`.
* `position`integer

  Place in `signers`, from 1: the `n` of this signer's [markers](#markers).
* `name`string
* `email`string
* `phone`string | null

  The mobile number the codes go to, in E.164. Set with `sms_otp`.
* `status`string

  `pending` until the signer enters the code, then `awaiting_consent`, then `signed` or `declined`.
* `invitation`object | null

  The last invitation email: `status` and `at`. `sent` means the mail provider accepted it; `failed` means it bounced or could not be handed over: [correct the address](#correct) or [resend](#resend).
* `viewed_at`string | null

  When every page of the document had been shown to the signer.
* `verified_at`string | null

  When the signer entered the right code.
* `signed_at`string | null
* `declined_at`string | null
* `decline_reason`string | null

  What the signer wrote when declining.

[Create a signature request](#create)
-------------------------------------

POST`/api/v1.1/signature-requests`

Checks the document type, freezes the PDF, and emails each signer a link at once. Answers `201` with the request, or `200` with the existing one when `external_ref` was already used. With `draft: true` it keeps a `draft` instead and sends nothing.

The PDF is cleaned before anyone sees it: scripts, embedded files and actions are removed, and form fields and annotations are flattened into the page. What the signers read is that frozen file, and `frozen_sha256` is its hash. A PDF that cannot be made safe is [refused](#refusals).

Send `external_ref` on every call: if the answer is lost, sending it again returns the request (`200`) instead of emailing the signers twice. The rest of the body is not compared.

Check each signer's `invitation` in the answer: `failed` means the address bounced or the email could not be handed over.

### Body

* `title`stringrequired

  Shown to the signers and in the emails. At most 255 characters.
* `document_b64`stringrequired

  The PDF, base64-encoded (`base64 -w0 contract.pdf`). Line breaks and a `data:application/pdf;base64,` prefix are accepted. At most 25 MB and 500 pages.
* `document_type`stringrequired

  What the document is, from the [document types](#document-types). It decides whether a simple signature is allowed for the `country`. One of `ordinary_contract`, `vehicle_rental_damage_waiver`, `employment_termination`, `statutory_written_form`, `consumer_suretyship_debt_ack`, `consumer_credit_loa`, `court_or_statutory_notice`, `real_estate_notarised`, `will_family_succession`.
* `country`stringrequired

  Two-letter code of the law that governs the document, such as `FR`.
* `signers`array of objectrequired

  1 to 20 objects with `name` and `email`. The order sets the marker numbers: the first signer signs `[Signature 1]`. Two signers cannot share an address. With `verification: sms_otp`, each also needs a `phone`: a French mobile number, written `+33612345678` or `06 12 34 56 78`. The link still goes by email; the code goes by SMS.
* `verification`string

  `email_otp` sends each signer's one-time code to their email address. `sms_otp` sends it by SMS to their `phone`, so signing needs both the mailbox that got the link and the phone. Default `"email_otp"`.
* `copy_to`array of string

  Up to 20 addresses that receive the sealed copy. They do not sign. A malformed one answers `400 INVALID_SIGNER`.
* `language`string

  Language of the emails, the signing pages and the evidence page. One of `fr`, `en`. Default `"fr"`.
* `message`string

  Added to the invitation email. At most 2,000 characters.
* `placement`string

  `page` appends a signature page. `tags` prints each mark at its [marker](#markers) in the document. `fields` prints each mark in the box given in `fields`. Default `"page"`.
* `fields`array of object

  With `placement: fields`: up to 1,000 [fields](#fields). A signer without a `signature` field signs on an appended signature page. Not combined with `initials_every_page`: place `initials` fields instead.
* `draft`boolean

  Keep the request as a `draft`: only shapes and limits are checked and nothing is sent. Finish it [in the app](#drafts) or by API, then [send](#send) it. Default `false`.
* `initials_every_page`boolean

  Print the signers' initials and the request id at the foot of every page. Default `false`.
* `is_consumer`boolean

  The signers act as consumers. Recorded in the evidence only: set `statutory_disclosures` to show them the consumer disclosure. Default `false`.
* `statutory_disclosures`boolean

  Show the consumer disclosure (paper copy, withdrawal of consent) before signing. Without `disclosure_contact` the request is refused: `422`, reason `disclosure_contact_missing`. Default `false`.
* `disclosure_contact`string

  Where a signer asks for paper or withdraws consent. At most 500 characters.
* `paper_copy_fee`string

  The fee for a paper copy, as you want it shown, if there is one. At most 100 characters.
* `acknowledgements`array of string

  Up to 20 statements each signer ticks before signing, such as "I have read the general terms". At most 500 characters each.
* `aml_identification_confirmed`boolean

  You identified the signers yourself, as anti-money-laundering rules require. It lets `consumer_credit_loa` be sent where it would otherwise need an advanced signature (France, and countries without a column); the request is then recorded as `flag`. Default `false`.
* `expires_in_days`integer

  After this, an unsigned request becomes `expired`. Default `7`.
* `reminder_days`integer

  Every N days, email a new link to each signer who has not signed; the previous link stops working. `0`: never. Default `0`.
* `external_ref`string

  Your reference, at most 200 characters, unique in your organization. Sending it again returns the existing request (`200`) and sends nothing; the rest of the body is not compared. A refused request does not keep it, so a retry with the same reference is checked again.

### Errors

* 400`INVALID_JSON`The body is not a JSON object.
* 400`UNSUPPORTED_FIELD`The body carries a key this endpoint does not take.
* 400`INVALID_FIELD`A key is missing, has the wrong type or is out of range. For a wrong [field](#fields), `field_index` is its place in `fields`.
* 400`MISSING_DOCUMENT``document_b64` is missing.
* 400`INVALID_DOCUMENT`Not base64, not a PDF, or larger than 25 MB.
* 400`INVALID_SIGNER`A signer has no name or a malformed address, two signers share an address, or `signers` is empty. With `sms_otp`: a signer has no French mobile `phone`, or two share one.
* 400`INVALID_EXTERNAL_REF``external_ref` is not a string, or too long.
* 422`SIGNATURE_REQUEST_REFUSED`Refused before anything was sent. `reason` is one of the [refusal codes](#refusals); `signature_request_id` names the kept `failed` request.
* 503`SIGNING_UNAVAILABLE`Signing, or codes by SMS for `sms_otp`, is not open on this environment. Retrying does not help.
* 503`SERVICE_UNAVAILABLE`Reading PDFs is temporarily unavailable (busy, or a fault on our side). Retry after the `Retry-After` header's seconds.

```
curl -X POST "https://app.holofin.ai/api/v1.1/signature-requests" \
  -H "X-API-Key: $HOLOFIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Rental agreement 2026-1042",
    "document_b64": "JVBERi0xLjcKJcfsj6IK...",
    "document_type": "ordinary_contract",
    "country": "FR",
    "is_consumer": true,
    "signers": [
      {
        "name": "Camille Martin",
        "email": "camille.martin@example.com"
      }
    ],
    "copy_to": [
      "contracts@example.com"
    ],
    "external_ref": "rental-2026-1042"
  }'
```

201 · Created and sent: the signature request object.

```
{
  "id": "sigreq_8fK2pQ7xR4mN1vB3",
  "status": "waiting",
  "title": "Rental agreement 2026-1042",
  "external_ref": "rental-2026-1042",
  "workflow_run_id": null,
  "level": "native_simple",
  "verification": "email_otp",
  "language": "fr",
  "placement": "page",
  "initials_every_page": false,
  "document_type": "ordinary_contract",
  "country": "FR",
  "is_consumer": true,
  "guardrail": {
    "decision": "proceed",
    "note": null,
    "version": "2026-11-draft-1"
  },
  "page_count": 3,
  "signers": [
    {
      "id": "sigrcp_3hT9wE5yU2iO7pL1",
      "position": 1,
      "name": "Camille Martin",
      "email": "camille.martin@example.com",
      "status": "pending",
      "invitation": {
        "status": "sent",
        "at": "2026-11-15T09:12:04Z"
      },
      "viewed_at": null,
      "verified_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    }
  ],
  "copy_to": [
    "contracts@example.com"
  ],
  "failure": null,
  "created_at": "2026-11-15T09:12:03Z",
  "sent_at": "2026-11-15T09:12:03Z",
  "expires_at": "2026-11-22T09:12:03Z",
  "completed_at": null,
  "retention_until": null,
  "frozen_sha256": "3f1c0a9e7b5d4c2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a",
  "sealed_sha256": null,
  "evidence": {
    "event_count": 3,
    "head": "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b"
  },
  "pdf_url": null,
  "evidence_url": "https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/evidence"
}
```

[Get a signature request](#read)
--------------------------------

GET`/api/v1.1/signature-requests/{request_id}`

Where the request stands, signer by signer.

### Path parameters

* `request_id`stringrequired

  The request's `id`.

### Errors

* 404`NOT_FOUND`No resource with this ID in your organization.

```
curl "https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3" \
  -H "X-API-Key: $HOLOFIN_API_KEY"
```

200 · The signature request object.

```
{
  "id": "sigreq_8fK2pQ7xR4mN1vB3",
  "status": "waiting",
  "title": "Rental agreement 2026-1042",
  "external_ref": "rental-2026-1042",
  "workflow_run_id": null,
  "level": "native_simple",
  "verification": "email_otp",
  "language": "fr",
  "placement": "page",
  "initials_every_page": false,
  "document_type": "ordinary_contract",
  "country": "FR",
  "is_consumer": true,
  "guardrail": {
    "decision": "proceed",
    "note": null,
    "version": "2026-11-draft-1"
  },
  "page_count": 3,
  "signers": [
    {
      "id": "sigrcp_3hT9wE5yU2iO7pL1",
      "position": 1,
      "name": "Camille Martin",
      "email": "camille.martin@example.com",
      "status": "pending",
      "invitation": {
        "status": "sent",
        "at": "2026-11-15T09:12:04Z"
      },
      "viewed_at": null,
      "verified_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    }
  ],
  "copy_to": [
    "contracts@example.com"
  ],
  "failure": null,
  "created_at": "2026-11-15T09:12:03Z",
  "sent_at": "2026-11-15T09:12:03Z",
  "expires_at": "2026-11-22T09:12:03Z",
  "completed_at": null,
  "retention_until": null,
  "frozen_sha256": "3f1c0a9e7b5d4c2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a",
  "sealed_sha256": null,
  "evidence": {
    "event_count": 3,
    "head": "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b"
  },
  "pdf_url": null,
  "evidence_url": "https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/evidence"
}
```

[Change a draft](#update)
-------------------------

PATCH`/api/v1.1/signature-requests/{request_id}`

Saves settings, signers or fields on a `draft`. Only shapes and limits are checked: what a send needs is checked at [send](#send).

### Path parameters

* `request_id`stringrequired

  The request's `id`.

### Body

* `revision`integer

  The draft's `revision` you last read. Optional; when sent and the draft has changed since, nothing is saved and the answer is `409 DRAFT_CHANGED`.

### Errors

* 404`NOT_FOUND`No resource with this ID in your organization.
* 400`INVALID_JSON`The body is not a JSON object.
* 400`UNSUPPORTED_FIELD`The body carries a key that belongs to another endpoint, such as `case_fields` on a run.
* 400`INVALID_FIELD`A key has the wrong type or is out of range. For a wrong [field](#fields), `field_index` is its place in `fields`.
* 400`INVALID_SIGNER`A signer has no name or a malformed address, two signers share an address, or `signers` is empty. With `sms_otp`: a signer has no French mobile `phone`, or two share one.
* 409`NOT_A_DRAFT`The request was already sent; only a `draft` can change or be sent.
* 409`DRAFT_CHANGED`The draft changed since the `revision` you sent; read it again and reapply your change.

```
curl -X PATCH "https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3" \
  -H "X-API-Key: $HOLOFIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "revision": 3,
    "signers": [
      {
        "name": "Camille Martin",
        "email": "camille.martin@example.com"
      },
      {
        "name": "Paul Garnier",
        "email": "paul.garnier@example.com"
      }
    ],
    "fields": [
      {
        "type": "signature",
        "signer": 1,
        "page": 3,
        "x": 72,
        "y": 600,
        "width": 200,
        "height": 56
      },
      {
        "type": "signature",
        "signer": 2,
        "page": 3,
        "x": 320,
        "y": 600,
        "width": 200,
        "height": 56
      }
    ]
  }'
```

200 · The draft, with its new `revision`.

```
{
  "id": "sigreq_8fK2pQ7xR4mN1vB3",
  "status": "draft",
  "revision": 4,
  "frozen_sha256": "3f1c0a9e7b5d4c2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a",
  "title": "Rental agreement 2026-1042",
  "document_type": "ordinary_contract",
  "country": "FR",
  "signers": [
    {
      "position": 1,
      "name": "Camille Martin",
      "email": "camille.martin@example.com"
    }
  ],
  "copy_to": [],
  "language": "fr",
  "placement": "fields",
  "fields": [
    {
      "id": "fld_1",
      "type": "signature",
      "signer": 1,
      "page": 3,
      "x": 72,
      "y": 600,
      "width": 200,
      "height": 56
    }
  ],
  "pages": [
    {
      "number": 1,
      "width": 595,
      "height": 842
    },
    {
      "number": 2,
      "width": 595,
      "height": 842
    },
    {
      "number": 3,
      "width": 595,
      "height": 842
    }
  ],
  "files": [
    {
      "name": "contract.pdf",
      "page_count": 3,
      "converted": false
    }
  ],
  "external_ref": "rental-2026-1042",
  "page_count": 3,
  "created_at": "2026-11-15T09:10:41Z",
  "updated_at": "2026-11-15T09:11:58Z",
  "sent_at": null,
  "editor_url": "https://app.holofin.ai/signatures/sigreq_8fK2pQ7xR4mN1vB3/edit/",
  "evidence_url": null,
  "pdf_url": null
}
```

[Send a draft](#send)
---------------------

POST`/api/v1.1/signature-requests/{request_id}/send`

Runs the checks of [create](#create) on the draft, freezes it and emails each signer a link. The request becomes `waiting`. A refusal leaves the draft as it was, to fix and send again. No body.

### Path parameters

* `request_id`stringrequired

  The request's `id`.

### Errors

* 404`NOT_FOUND`No resource with this ID in your organization.
* 400`INVALID_FIELD`Something a request needs is missing or wrong, such as the title. For a wrong [field](#fields), `field_index` is its place in `fields`.
* 400`INVALID_SIGNER`A signer has no name or a malformed address, two signers share an address, or `signers` is empty. With `sms_otp`: a signer has no French mobile `phone`, or two share one.
* 409`NOT_A_DRAFT`The request was already sent; only a `draft` can change or be sent.
* 422`SIGNATURE_REQUEST_REFUSED`The [document-type check](#document-types) refused it. `reason` is one of the [refusal codes](#refusals); the draft is kept.
* 503`SIGNING_UNAVAILABLE`Signing is not open on this environment. Retrying does not help.
* 503`SERVICE_UNAVAILABLE`Reading PDFs is temporarily unavailable (busy, or a fault on our side). Retry after the `Retry-After` header's seconds.

```
curl -X POST "https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/send" \
  -H "X-API-Key: $HOLOFIN_API_KEY"
```

200 · Sent: the signature request object, `waiting`.

```
{
  "id": "sigreq_8fK2pQ7xR4mN1vB3",
  "status": "waiting",
  "title": "Rental agreement 2026-1042",
  "external_ref": "rental-2026-1042",
  "workflow_run_id": null,
  "level": "native_simple",
  "verification": "email_otp",
  "language": "fr",
  "placement": "fields",
  "initials_every_page": false,
  "document_type": "ordinary_contract",
  "country": "FR",
  "is_consumer": true,
  "guardrail": {
    "decision": "proceed",
    "note": null,
    "version": "2026-11-draft-1"
  },
  "page_count": 3,
  "signers": [
    {
      "id": "sigrcp_3hT9wE5yU2iO7pL1",
      "position": 1,
      "name": "Camille Martin",
      "email": "camille.martin@example.com",
      "status": "pending",
      "invitation": {
        "status": "sent",
        "at": "2026-11-15T09:12:04Z"
      },
      "viewed_at": null,
      "verified_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    }
  ],
  "copy_to": [
    "contracts@example.com"
  ],
  "failure": null,
  "created_at": "2026-11-15T09:12:03Z",
  "sent_at": "2026-11-15T09:12:03Z",
  "expires_at": "2026-11-22T09:12:03Z",
  "completed_at": null,
  "retention_until": null,
  "frozen_sha256": "3f1c0a9e7b5d4c2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a",
  "sealed_sha256": null,
  "evidence": {
    "event_count": 3,
    "head": "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b"
  },
  "pdf_url": null,
  "evidence_url": "https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/evidence"
}
```

[Delete a draft](#delete)
-------------------------

DELETE`/api/v1.1/signature-requests/{request_id}`

Deletes a `draft` and its files. A sent request cannot be deleted: [cancel](#cancel) it.

### Path parameters

* `request_id`stringrequired

  The request's `id`.

### Errors

* 404`NOT_FOUND`No resource with this ID in your organization.
* 409`NOT_A_DRAFT`The request was already sent; only a `draft` can change or be sent.

```
curl -X DELETE "https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3" \
  -H "X-API-Key: $HOLOFIN_API_KEY"
```

[List signature requests](#list)
--------------------------------

GET`/api/v1.1/signature-requests`

Your organization's requests, newest first, 100 at most per page.

### Query parameters

* `status`string

  One of `draft`, `waiting`, `finalizing`, `completed`, `declined`, `expired`, `cancelled`, `failed`.
* `external_ref`string

  Only the request with this reference.
* `limit`integer

  Page size, `100` by default and at most. A value outside 1 to 100 is brought into that range.
* `next_token`string

  From the previous page's `pagination`. Send the same `status` and `external_ref` with it: the token does not keep them.

### Response

* `signature_requests`array of object

  Newest first.
* `pagination`object

  `page_size`, `has_next`, and `next_token` when there is a next page: send it back as `next_token`.

### Errors

* 400`UNKNOWN_PARAMETER`An unsupported query parameter; the message lists the supported ones.
* 400`INVALID_FILTER`A filter has a value outside the allowed set; the message lists them.

```
curl -G "https://app.holofin.ai/api/v1.1/signature-requests" \
  -H "X-API-Key: $HOLOFIN_API_KEY" \
  --data-urlencode "status=completed"
```

200

```
{
  "signature_requests": [
    {
      "id": "sigreq_8fK2pQ7xR4mN1vB3",
      "status": "waiting",
      "title": "Rental agreement 2026-1042",
      "external_ref": "rental-2026-1042",
      "workflow_run_id": null,
      "level": "native_simple",
      "verification": "email_otp",
      "language": "fr",
      "placement": "page",
      "initials_every_page": false,
      "document_type": "ordinary_contract",
      "country": "FR",
      "is_consumer": true,
      "guardrail": {
        "decision": "proceed",
        "note": null,
        "version": "2026-11-draft-1"
      },
      "page_count": 3,
      "signers": [
        {
          "id": "sigrcp_3hT9wE5yU2iO7pL1",
          "position": 1,
          "name": "Camille Martin",
          "email": "camille.martin@example.com",
          "status": "pending",
          "invitation": {
            "status": "sent",
            "at": "2026-11-15T09:12:04Z"
          },
          "viewed_at": null,
          "verified_at": null,
          "signed_at": null,
          "declined_at": null,
          "decline_reason": null
        }
      ],
      "copy_to": [
        "contracts@example.com"
      ],
      "failure": null,
      "created_at": "2026-11-15T09:12:03Z",
      "sent_at": "2026-11-15T09:12:03Z",
      "expires_at": "2026-11-22T09:12:03Z",
      "completed_at": null,
      "retention_until": null,
      "frozen_sha256": "3f1c0a9e7b5d4c2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a",
      "sealed_sha256": null,
      "evidence": {
        "event_count": 3,
        "head": "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b"
      },
      "pdf_url": null,
      "evidence_url": "https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/evidence"
    }
  ],
  "pagination": {
    "page_size": 100,
    "has_next": false
  }
}
```

[Check where the markers print](#inspect)
-----------------------------------------

POST`/api/v1.1/signature-requests/inspect`

Runs a PDF through the same intake as a request and reports every marker found. Creates nothing and sends nothing.

### Body

* `document_b64`stringrequired

  The PDF, base64-encoded, as for a request.

### Response

* `page_count`integer
* `pages`array of object

  `number`, `width` and `height` of each page as displayed, in points: the space [fields](#fields) are placed in.
* `removed`array of string

  What intake took out of the file before freezing it, such as `javascript` or `form_fields_flattened`. A request would do the same.
* `markers`array of object

  Each marker found: `kind` (`signature`, `initials` or `date`), `signer` (its number), `page` (from 1), `box` (where the marker text sits, `[x0, y0, x1, y1]` in PDF points, origin top left) and `fits`: false when the mark would run off the page.
* `signers_with_signature_marker`array of integer

  Signer numbers that have a `[Signature n]`. A signer without one signs on an appended signature page.

### Errors

* 400`INVALID_JSON`The body is not a JSON object.
* 400`UNSUPPORTED_FIELD`The body carries a key other than `document_b64`.
* 400`MISSING_DOCUMENT``document_b64` is missing.
* 400`INVALID_DOCUMENT`Not base64, not a PDF, or larger than 25 MB.
* 422`DOCUMENT_REFUSED`The PDF cannot be made safe to sign. `reason` is an intake [refusal code](#refusals) without its `intake_` prefix.
* 503`SERVICE_UNAVAILABLE`Reading PDFs is temporarily unavailable (busy, or a fault on our side). Retry after the `Retry-After` header's seconds.

```
curl -X POST "https://app.holofin.ai/api/v1.1/signature-requests/inspect" \
  -H "X-API-Key: $HOLOFIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_b64": "JVBERi0xLjcKJcfsj6IK..."
  }'
```

200

```
{
  "page_count": 3,
  "pages": [
    {
      "number": 1,
      "width": 595,
      "height": 842
    },
    {
      "number": 2,
      "width": 595,
      "height": 842
    },
    {
      "number": 3,
      "width": 595,
      "height": 842
    }
  ],
  "removed": [],
  "markers": [
    {
      "kind": "signature",
      "signer": 1,
      "page": 3,
      "box": [
        72.0,
        610.2,
        160.4,
        624.0
      ],
      "fits": true
    },
    {
      "kind": "date",
      "signer": 1,
      "page": 3,
      "box": [
        320.0,
        610.2,
        368.9,
        624.0
      ],
      "fits": true
    }
  ],
  "signers_with_signature_marker": [
    1
  ]
}
```

[Cancel a signature request](#cancel)
-------------------------------------

POST`/api/v1.1/signature-requests/{request_id}/cancel`

Withdraws a `waiting` request: every link stops working and nobody else can sign. The body is optional.

### Path parameters

* `request_id`stringrequired

  The request's `id`.

### Body

* `reason`string

  Kept in the evidence log. At most 500 characters.

### Errors

* 404`NOT_FOUND`No resource with this ID in your organization.
* 400`INVALID_JSON`The body is not a JSON object.
* 400`INVALID_FIELD`A field is missing, has the wrong type or is out of range; the message names it.
* 409`CANNOT_CANCEL`The request is no longer `waiting`. Once sealing has begun it cannot be withdrawn.

```
curl -X POST "https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/cancel" \
  -H "X-API-Key: $HOLOFIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Replaced by a corrected version."
  }'
```

200 · The signature request object.

```
{
  "id": "sigreq_8fK2pQ7xR4mN1vB3",
  "status": "cancelled",
  "title": "Rental agreement 2026-1042",
  "external_ref": "rental-2026-1042",
  "workflow_run_id": null,
  "level": "native_simple",
  "verification": "email_otp",
  "language": "fr",
  "placement": "page",
  "initials_every_page": false,
  "document_type": "ordinary_contract",
  "country": "FR",
  "is_consumer": true,
  "guardrail": {
    "decision": "proceed",
    "note": null,
    "version": "2026-11-draft-1"
  },
  "page_count": 3,
  "signers": [
    {
      "id": "sigrcp_3hT9wE5yU2iO7pL1",
      "position": 1,
      "name": "Camille Martin",
      "email": "camille.martin@example.com",
      "status": "pending",
      "invitation": {
        "status": "sent",
        "at": "2026-11-15T09:12:04Z"
      },
      "viewed_at": null,
      "verified_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    }
  ],
  "copy_to": [
    "contracts@example.com"
  ],
  "failure": null,
  "created_at": "2026-11-15T09:12:03Z",
  "sent_at": "2026-11-15T09:12:03Z",
  "expires_at": "2026-11-22T09:12:03Z",
  "completed_at": null,
  "retention_until": null,
  "frozen_sha256": "3f1c0a9e7b5d4c2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a",
  "sealed_sha256": null,
  "evidence": {
    "event_count": 3,
    "head": "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b"
  },
  "pdf_url": null,
  "evidence_url": "https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/evidence"
}
```

[Send a signer a new link](#resend)
-----------------------------------

POST`/api/v1.1/signature-requests/{request_id}/signers/{signer_id}/resend`

Emails a new link. The previous link and any open signing session stop working, so the signer starts again from the code.

### Path parameters

* `request_id`stringrequired

  The request's `id`.
* `signer_id`stringrequired

  The signer's `id`, from `signers`.

### Errors

* 404`NOT_FOUND`No resource with this ID in your organization.
* 409`CANNOT_RESEND`Nothing was sent: the request is not `waiting`, the signer has signed or declined, or the email could not be handed over. In that last case the previous link no longer works: try again.

```
curl -X POST "https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/signers/sigrcp_3hT9wE5yU2iO7pL1/resend" \
  -H "X-API-Key: $HOLOFIN_API_KEY"
```

200 · The signature request object.

```
{
  "id": "sigreq_8fK2pQ7xR4mN1vB3",
  "status": "waiting",
  "title": "Rental agreement 2026-1042",
  "external_ref": "rental-2026-1042",
  "workflow_run_id": null,
  "level": "native_simple",
  "verification": "email_otp",
  "language": "fr",
  "placement": "page",
  "initials_every_page": false,
  "document_type": "ordinary_contract",
  "country": "FR",
  "is_consumer": true,
  "guardrail": {
    "decision": "proceed",
    "note": null,
    "version": "2026-11-draft-1"
  },
  "page_count": 3,
  "signers": [
    {
      "id": "sigrcp_3hT9wE5yU2iO7pL1",
      "position": 1,
      "name": "Camille Martin",
      "email": "camille.martin@example.com",
      "status": "pending",
      "invitation": {
        "status": "sent",
        "at": "2026-11-15T09:12:04Z"
      },
      "viewed_at": null,
      "verified_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    }
  ],
  "copy_to": [
    "contracts@example.com"
  ],
  "failure": null,
  "created_at": "2026-11-15T09:12:03Z",
  "sent_at": "2026-11-15T09:12:03Z",
  "expires_at": "2026-11-22T09:12:03Z",
  "completed_at": null,
  "retention_until": null,
  "frozen_sha256": "3f1c0a9e7b5d4c2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a",
  "sealed_sha256": null,
  "evidence": {
    "event_count": 3,
    "head": "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b"
  },
  "pdf_url": null,
  "evidence_url": "https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/evidence"
}
```

[Correct a signer's address](#correct)
--------------------------------------

POST`/api/v1.1/signature-requests/{request_id}/signers/{signer_id}/correct`

Changes the address or the phone of a signer who has not signed, and sends a new link. Anything verified before is reset. The change is in the evidence log. Send `email`, `phone` (on an `sms_otp` request), or both.

### Path parameters

* `request_id`stringrequired

  The request's `id`.
* `signer_id`stringrequired

  The signer's `id`, from `signers`.

### Body

* `email`string
* `phone`string

### Errors

* 404`NOT_FOUND`No resource with this ID in your organization.
* 400`INVALID_JSON`The body is not a JSON object.
* 400`INVALID_FIELD`A field is missing, has the wrong type or is out of range; the message names it.
* 400`INVALID_SIGNER`The address or phone is not valid, or another signer already uses it.
* 409`NOT_CORRECTABLE`The request is not `waiting`, or the signer has already signed.

```
curl -X POST "https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/signers/sigrcp_3hT9wE5yU2iO7pL1/correct" \
  -H "X-API-Key: $HOLOFIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "camille.martin@example.org"
  }'
```

200 · The signature request object, with the new address.

```
{
  "id": "sigreq_8fK2pQ7xR4mN1vB3",
  "status": "waiting",
  "title": "Rental agreement 2026-1042",
  "external_ref": "rental-2026-1042",
  "workflow_run_id": null,
  "level": "native_simple",
  "verification": "email_otp",
  "language": "fr",
  "placement": "page",
  "initials_every_page": false,
  "document_type": "ordinary_contract",
  "country": "FR",
  "is_consumer": true,
  "guardrail": {
    "decision": "proceed",
    "note": null,
    "version": "2026-11-draft-1"
  },
  "page_count": 3,
  "signers": [
    {
      "id": "sigrcp_3hT9wE5yU2iO7pL1",
      "position": 1,
      "name": "Camille Martin",
      "email": "camille.martin@example.com",
      "status": "pending",
      "invitation": {
        "status": "sent",
        "at": "2026-11-15T09:12:04Z"
      },
      "viewed_at": null,
      "verified_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    }
  ],
  "copy_to": [
    "contracts@example.com"
  ],
  "failure": null,
  "created_at": "2026-11-15T09:12:03Z",
  "sent_at": "2026-11-15T09:12:03Z",
  "expires_at": "2026-11-22T09:12:03Z",
  "completed_at": null,
  "retention_until": null,
  "frozen_sha256": "3f1c0a9e7b5d4c2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a",
  "sealed_sha256": null,
  "evidence": {
    "event_count": 3,
    "head": "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b"
  },
  "pdf_url": null,
  "evidence_url": "https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/evidence"
}
```

[Download the signed PDF](#pdf)
-------------------------------

GET`/api/v1.1/signature-requests/{request_id}/pdf`

The sealed PDF of a `completed` request: the document, the signatures, and the evidence page. Each download is recorded in the evidence log.

The file is the frozen document with the marks in place, a signature page when needed, and an evidence page with each signer's masked address, IP address, times and the document's hashes. It is sealed at PAdES B-LTA: a PDF validator checks the seal once it trusts the seal's root certificate, which the [process statement](https://app.holofin.ai/sign/process/) publishes with the rest of the process.

Holofin renews the archive timestamp on its own copy about once a year, which changes `sealed_sha256`. The copy you downloaded stays valid as it is; download again for the renewed file.

### Path parameters

* `request_id`stringrequired

  The request's `id`.

### Errors

* 404`NOT_FOUND`No resource with this ID in your organization.
* 409`NOT_COMPLETED`The signed PDF exists once the request is `completed`.

```
curl -L "https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/pdf" \
  -H "X-API-Key: $HOLOFIN_API_KEY" \
  -o signed.pdf
```

[Download the evidence log](#evidence)
--------------------------------------

GET`/api/v1.1/signature-requests/{request_id}/evidence`

Every event of the request in a hash chain, as JSON, in any status. Each download is itself recorded as the next event.

Each event's `hash` is the SHA-256 of its `prev_hash`, as bytes, followed by the JSON of its `seq`, `at`, `type`, `actor`, `ip`, `user_agent` and `data`, with keys sorted, no spaces, in UTF-8. The first `prev_hash` is `genesis`, the frozen document's hash. Removing or editing one event breaks every hash after it.

Email addresses in the log are masked; IP addresses and user agents are kept. Keep this file with the signed PDF: together they are what you show if a signature is ever disputed.

### Path parameters

* `request_id`stringrequired

  The request's `id`.

### Response

* `format`string
* `request_id`string
* `genesis`string

  SHA-256 of the frozen document, which starts the chain.
* `frozen_sha256`string
* `head`string

  The hash of the last event.
* `wording_version`string
* `process_version`string
* `events`array of object

  In order. Each has `seq`, `at`, `type`, `actor`, `ip`, `user_agent`, `data`, `prev_hash` and `hash`.

### Errors

* 404`NOT_FOUND`No resource with this ID in your organization.
* 409`NOT_SENT`A `draft` has no evidence log until it is sent.

```
curl -L "https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/evidence" \
  -H "X-API-Key: $HOLOFIN_API_KEY" \
  -o evidence.json
```

200

```
{
  "format": "holofin-signature-evidence/1",
  "request_id": "sigreq_8fK2pQ7xR4mN1vB3",
  "genesis": "3f1c0a9e7b5d4c2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a",
  "frozen_sha256": "3f1c0a9e7b5d4c2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a",
  "head": "5d0c7e2b9a14f3e6d8c1b0a7f6e5d4c3b2a1908f7e6d5c4b3a2918f7e6d5c4b3",
  "wording_version": "2026-11-draft-1",
  "process_version": "2026-11-draft-1",
  "events": [
    {
      "seq": 1,
      "at": "2026-11-15T09:12:03Z",
      "type": "request.created",
      "actor": "api_key:7b1e4c2a-9d3f-4e8b-a6c5-2f1d0e9c8b7a",
      "ip": "203.0.113.10",
      "user_agent": "python-requests/2.32",
      "data": {
        "document_type": "ordinary_contract",
        "country": "FR"
      },
      "prev_hash": "3f1c0a9e7b5d4c2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a",
      "hash": "c4a7e1f0b9d8c7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2"
    }
  ]
}
```

[Webhooks](#webhooks)
---------------------

A request sends one event when it closes: `signature-request.completed`, `signature-request.declined`, `signature-request.expired` or `signature-request.cancelled`. Subscribe through [`POST /webhooks`](https://app.holofin.ai/docs/api/v1.1/webhooks/#management-api) with these names, or with no `events` to receive everything. Deliveries are signed, retried and verified as described in [Webhooks](https://app.holofin.ai/docs/api/v1.1/webhooks/#webhook-security).

The event comes in the usual [envelope](https://app.holofin.ai/docs/api/v1.1/webhooks/#webhook-payload). `data.object` carries identifiers only, never an address or a link: read the request for the rest. A retried delivery keeps its `id`, so deduplicate on it.

### signature-request.completed

```
{
  "id": "whev_4kR8tY2wQ6pN3sV1",
  "event": "signature-request.completed",
  "created_at": "2026-11-15T10:02:41Z",
  "data": {
    "object": {
      "event": "signature-request.completed",
      "signature_request_id": "sigreq_8fK2pQ7xR4mN1vB3",
      "status": "completed",
      "external_ref": "rental-2026-1042",
      "workflow_run_id": null,
      "timestamp": "2026-11-15T10:02:41Z"
    }
  }
}
```

A refusal at creation sends no event: the create call already answered it.

[Requests made by a workflow](#workflow)
----------------------------------------

A workflow's signature step creates requests too. They appear in the list and send the same webhooks, with `workflow_run_id` set and `external_ref` null. Cancelling one through this API ends the run's step through its `failed` branch. A request the step could not create sends no event; the step leaves through `failed`.

[Limits and retention](#limits)
-------------------------------

* A PDF of at most 25 MB and 500 pages; 20 signers and 20 `copy_to` addresses.
* Up to 1,000 fields. A draft not sent within 30 days is deleted.
* A request expires after 1 to 90 days (`expires_in_days`, 7 by default).
* A signer gets 5 tries per code; a code lasts 10 minutes, a new one can be asked for after 60 seconds, and 8 at most in an hour.
* A completed request, its PDF and its evidence are kept until `retention_until`, 10 years after sealing. A request that closed unsigned is deleted a year after it closed.
