Signature requests
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
Every call takes your API key in the X-API-Key header, as described in Authentication.
- 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.
- 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.
- When the last signer has signed, Holofin seals the file and emails the sealed copy to every signer and to
copy_to. Follow it withGET /signature-requests/{id}or a webhook.
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 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. |
| 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. |
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.
When a request closes
A webhook tells you, or read the request. Then:
completed: download the sealed PDF and the evidence log with your key, and keep both.pdf_urlandevidence_urlare API URLs, not public links.declined: the signer'sdecline_reasonsays why.expiredorcancelled: 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_contractOrdinary commercial or consumer contract | proceed | proceed | proceed |
vehicle_rental_damage_waiverVehicle rental with a damage-waiver disclosure | proceed | proceed | flag |
employment_terminationEnding an employment contract | refuse | warn | proceed |
statutory_written_formDocument under a statutory written-form rule | provider | flag | proceed |
consumer_suretyship_debt_ackConsumer suretyship or acknowledgement of debt | refuse | flag | warn |
consumer_credit_loaConsumer credit or leasing with a purchase option | provider | provider | flag |
court_or_statutory_noticeCourt filing; default, foreclosure or eviction notice; cancellation of utilities or of health or life insurance; product recall | refuse | refuse | refuse |
real_estate_notarisedReal-estate transfer or notarised act | refuse | refuse | flag |
will_family_successionWill, 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:
| 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 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.
| 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 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, 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 |
| 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
idstringKept if you send one, else given as
fld_<n>.typestringsignature,initials,date(the day the signer signs, UTC),nameandemailare filled from the signer's act.textis your own text, printed into the document before it is frozen.signerinteger | nullThe signer's place in
signers, from 1. Null fortext.pageintegerFrom 1.
xintegerPoints from the left edge of the page.
yintegerPoints from the top edge of the page.
widthintegerheightintegervaluestringFor
textonly: what to print, at most 500 characters.groupstringFields 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, then send it, 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
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
idstringStarts with
sigreq_.statusstringdraftuntil it is sent, thenwaitinguntil every signer has signed, thenfinalizingwhile the file is sealed (usually under a minute), thencompleted.declined,expired,cancelledandfailedare final too. See statuses.titlestringexternal_refstring | nullYour reference, as sent on creation.
workflow_run_idstring | nullSet when a workflow's signature step created the request.
levelstringnative_simple: a simple electronic signature.verificationstringHow 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).languagestringOne of
fr,en.placementstringOne of
page,tags,fields.initials_every_pagebooleandocument_typestringcountrystringis_consumerbooleanguardrailobjectWhat the document-type check decided:
decision(proceed,warnorflagon a sent request;providerorrefuseon afailedone),note, the reason for that cell of the table, and itsversion.page_countintegerPages of the frozen document.
pagesarray of objectnumber,widthandheightof each page as displayed, in points: the space fields are placed in.fieldsarray of objectThe fields placed on the pages, for
placement: fields.revisionintegerOn a
draftonly: its version. Send it back with a change so that a change made elsewhere in between is not overwritten.filesarray of objectOn a
draftonly: the files it was built from, in order, each withname,page_countandconverted(true for an office document).editor_urlstring | nullOn a
draftonly: where a person in your organization opens it in the Holofin app to place fields and send it.nullwhile Signatures is off in the app for your organization: finish the draft through the API.signersarray of objectSigner objects, in the order you sent them. All are invited at once and sign in any order.
copy_toarray of stringAddresses that receive the signed copy.
failureobject | nullOn a
failedrequest:reason, one of the refusal codes, anddetail, a sentence for a person.created_atstringsent_atstring | nullexpires_atstring | nullcompleted_atstring | nullWhen the request reached a final status.
retention_untilstring | nullWhen 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_sha256string | nullSHA-256 of the document the signers saw, after intake.
sealed_sha256string | nullSHA-256 of the sealed PDF.
evidenceobjectevent_countandhead, the hash of the last event of the evidence log.pdf_urlstring | nullWhere to download the sealed PDF once
completed. An API URL: call it with your key, it is not a public link.evidence_urlstringWhere to download the evidence log, with your key.
The signer object
Attributes
idstringStarts with
sigrcp_.positionintegerPlace in
signers, from 1: thenof this signer's markers.namestringemailstringphonestring | nullThe mobile number the codes go to, in E.164. Set with
sms_otp.statusstringpendinguntil the signer enters the code, thenawaiting_consent, thensignedordeclined.invitationobject | nullThe last invitation email:
statusandat.sentmeans the mail provider accepted it;failedmeans it bounced or could not be handed over: correct the address or resend.viewed_atstring | nullWhen every page of the document had been shown to the signer.
verified_atstring | nullWhen the signer entered the right code.
signed_atstring | nulldeclined_atstring | nulldecline_reasonstring | nullWhat the signer wrote when declining.
Create a signature request
/api/v1.1/signature-requestsChecks 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.
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
titlestringrequiredShown to the signers and in the emails. At most 255 characters.
document_b64stringrequiredThe PDF, base64-encoded (
base64 -w0 contract.pdf). Line breaks and adata:application/pdf;base64,prefix are accepted. At most 25 MB and 500 pages.document_typestringrequiredWhat the document is, from the document types. It decides whether a simple signature is allowed for the
country. One ofordinary_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.countrystringrequiredTwo-letter code of the law that governs the document, such as
FR.signersarray of objectrequired1 to 20 objects with
nameandemail. The order sets the marker numbers: the first signer signs[Signature 1]. Two signers cannot share an address. Withverification: sms_otp, each also needs aphone: a French mobile number, written+33612345678or06 12 34 56 78. The link still goes by email; the code goes by SMS.verificationstringemail_otpsends each signer's one-time code to their email address.sms_otpsends it by SMS to theirphone, so signing needs both the mailbox that got the link and the phone. Default"email_otp".copy_toarray of stringUp to 20 addresses that receive the sealed copy. They do not sign. A malformed one answers
400 INVALID_SIGNER.languagestringLanguage of the emails, the signing pages and the evidence page. One of
fr,en. Default"fr".messagestringAdded to the invitation email. At most 2,000 characters.
placementstringpageappends a signature page.tagsprints each mark at its marker in the document.fieldsprints each mark in the box given infields. Default"page".fieldsarray of objectWith
placement: fields: up to 1,000 fields. A signer without asignaturefield signs on an appended signature page. Not combined withinitials_every_page: placeinitialsfields instead.draftbooleanKeep the request as a
draft: only shapes and limits are checked and nothing is sent. Finish it in the app or by API, then send it. Defaultfalse.initials_every_pagebooleanPrint the signers' initials and the request id at the foot of every page. Default
false.is_consumerbooleanThe signers act as consumers. Recorded in the evidence only: set
statutory_disclosuresto show them the consumer disclosure. Defaultfalse.statutory_disclosuresbooleanShow the consumer disclosure (paper copy, withdrawal of consent) before signing. Without
disclosure_contactthe request is refused:422, reasondisclosure_contact_missing. Defaultfalse.disclosure_contactstringWhere a signer asks for paper or withdraws consent. At most 500 characters.
paper_copy_feestringThe fee for a paper copy, as you want it shown, if there is one. At most 100 characters.
acknowledgementsarray of stringUp to 20 statements each signer ticks before signing, such as "I have read the general terms". At most 500 characters each.
aml_identification_confirmedbooleanYou identified the signers yourself, as anti-money-laundering rules require. It lets
consumer_credit_loabe sent where it would otherwise need an advanced signature (France, and countries without a column); the request is then recorded asflag. Defaultfalse.expires_in_daysintegerAfter this, an unsigned request becomes
expired. Default7.reminder_daysintegerEvery N days, email a new link to each signer who has not signed; the previous link stops working.
0: never. Default0.external_refstringYour 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_JSONThe body is not a JSON object. - 400
UNSUPPORTED_FIELDThe body carries a key this endpoint does not take. - 400
INVALID_FIELDA key is missing, has the wrong type or is out of range. For a wrong field,field_indexis its place infields. - 400
MISSING_DOCUMENTdocument_b64is missing. - 400
INVALID_DOCUMENTNot base64, not a PDF, or larger than 25 MB. - 400
INVALID_SIGNERA signer has no name or a malformed address, two signers share an address, orsignersis empty. Withsms_otp: a signer has no French mobilephone, or two share one. - 400
INVALID_EXTERNAL_REFexternal_refis not a string, or too long. - 422
SIGNATURE_REQUEST_REFUSEDRefused before anything was sent.reasonis one of the refusal codes;signature_request_idnames the keptfailedrequest. - 503
SIGNING_UNAVAILABLESigning, or codes by SMS forsms_otp, is not open on this environment. Retrying does not help. - 503
SERVICE_UNAVAILABLEReading PDFs is temporarily unavailable (busy, or a fault on our side). Retry after theRetry-Afterheader'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": "[email protected]"
}
],
"copy_to": [
"[email protected]"
],
"external_ref": "rental-2026-1042"
}'import os
import requests
response = requests.post(
"https://app.holofin.ai/api/v1.1/signature-requests",
headers={"X-API-Key": os.environ["HOLOFIN_API_KEY"]},
json={
"title": "Rental agreement 2026-1042",
"document_b64": "JVBERi0xLjcKJcfsj6IK...",
"document_type": "ordinary_contract",
"country": "FR",
"is_consumer": True,
"signers": [
{
"name": "Camille Martin",
"email": "[email protected]",
},
],
"copy_to": ["[email protected]"],
"external_ref": "rental-2026-1042",
},
)
response.raise_for_status()
print(response.json())const response = await fetch("https://app.holofin.ai/api/v1.1/signature-requests", {
method: "POST",
headers: {
"X-API-Key": process.env.HOLOFIN_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"title": "Rental agreement 2026-1042",
"document_b64": "JVBERi0xLjcKJcfsj6IK...",
"document_type": "ordinary_contract",
"country": "FR",
"is_consumer": true,
"signers": [
{
"name": "Camille Martin",
"email": "[email protected]"
}
],
"copy_to": [
"[email protected]"
],
"external_ref": "rental-2026-1042"
}),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());{
"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": "[email protected]",
"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": [
"[email protected]"
],
"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
/api/v1.1/signature-requests/{request_id}Where the request stands, signer by signer.
Path parameters
request_idstringrequiredThe request's
id.
Errors
- 404
NOT_FOUNDNo 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"import os
import requests
response = requests.get(
"https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3",
headers={"X-API-Key": os.environ["HOLOFIN_API_KEY"]},
)
response.raise_for_status()
print(response.json())const response = await fetch("https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3", {
headers: {
"X-API-Key": process.env.HOLOFIN_API_KEY,
},
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());{
"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": "[email protected]",
"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": [
"[email protected]"
],
"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
/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.
Path parameters
request_idstringrequiredThe request's
id.
Body
revisionintegerThe draft's
revisionyou last read. Optional; when sent and the draft has changed since, nothing is saved and the answer is409 DRAFT_CHANGED.
Errors
- 404
NOT_FOUNDNo resource with this ID in your organization. - 400
INVALID_JSONThe body is not a JSON object. - 400
UNSUPPORTED_FIELDThe body carries a key that belongs to another endpoint, such ascase_fieldson a run. - 400
INVALID_FIELDA key has the wrong type or is out of range. For a wrong field,field_indexis its place infields. - 400
INVALID_SIGNERA signer has no name or a malformed address, two signers share an address, orsignersis empty. Withsms_otp: a signer has no French mobilephone, or two share one. - 409
NOT_A_DRAFTThe request was already sent; only adraftcan change or be sent. - 409
DRAFT_CHANGEDThe draft changed since therevisionyou 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": "[email protected]"
},
{
"name": "Paul Garnier",
"email": "[email protected]"
}
],
"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
}
]
}'import os
import requests
response = requests.patch(
"https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3",
headers={"X-API-Key": os.environ["HOLOFIN_API_KEY"]},
json={
"revision": 3,
"signers": [
{
"name": "Camille Martin",
"email": "[email protected]",
},
{
"name": "Paul Garnier",
"email": "[email protected]",
},
],
"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,
},
],
},
)
response.raise_for_status()
print(response.json())const response = await fetch("https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3", {
method: "PATCH",
headers: {
"X-API-Key": process.env.HOLOFIN_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"revision": 3,
"signers": [
{
"name": "Camille Martin",
"email": "[email protected]"
},
{
"name": "Paul Garnier",
"email": "[email protected]"
}
],
"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
}
]
}),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());{
"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": "[email protected]"
}
],
"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
/api/v1.1/signature-requests/{request_id}/sendRuns the checks of 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_idstringrequiredThe request's
id.
Errors
- 404
NOT_FOUNDNo resource with this ID in your organization. - 400
INVALID_FIELDSomething a request needs is missing or wrong, such as the title. For a wrong field,field_indexis its place infields. - 400
INVALID_SIGNERA signer has no name or a malformed address, two signers share an address, orsignersis empty. Withsms_otp: a signer has no French mobilephone, or two share one. - 409
NOT_A_DRAFTThe request was already sent; only adraftcan change or be sent. - 422
SIGNATURE_REQUEST_REFUSEDThe document-type check refused it.reasonis one of the refusal codes; the draft is kept. - 503
SIGNING_UNAVAILABLESigning is not open on this environment. Retrying does not help. - 503
SERVICE_UNAVAILABLEReading PDFs is temporarily unavailable (busy, or a fault on our side). Retry after theRetry-Afterheader's seconds.
curl -X POST "https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/send" \
-H "X-API-Key: $HOLOFIN_API_KEY"import os
import requests
response = requests.post(
"https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/send",
headers={"X-API-Key": os.environ["HOLOFIN_API_KEY"]},
)
response.raise_for_status()
print(response.json())const response = await fetch("https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/send", {
method: "POST",
headers: {
"X-API-Key": process.env.HOLOFIN_API_KEY,
},
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());{
"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": "[email protected]",
"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": [
"[email protected]"
],
"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
/api/v1.1/signature-requests/{request_id}Deletes a draft and its files. A sent request cannot be deleted: cancel it.
Path parameters
request_idstringrequiredThe request's
id.
Errors
- 404
NOT_FOUNDNo resource with this ID in your organization. - 409
NOT_A_DRAFTThe request was already sent; only adraftcan 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"import os
import requests
response = requests.delete(
"https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3",
headers={"X-API-Key": os.environ["HOLOFIN_API_KEY"]},
)
response.raise_for_status()
print(response.status_code)const response = await fetch("https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3", {
method: "DELETE",
headers: {
"X-API-Key": process.env.HOLOFIN_API_KEY,
},
});
if (!response.ok) throw new Error(await response.text());
console.log(response.status);List signature requests
/api/v1.1/signature-requestsYour organization's requests, newest first, 100 at most per page.
Query parameters
statusstringOne of
draft,waiting,finalizing,completed,declined,expired,cancelled,failed.external_refstringOnly the request with this reference.
limitintegerPage size,
100by default and at most. A value outside 1 to 100 is brought into that range.next_tokenstringFrom the previous page's
pagination. Send the samestatusandexternal_refwith it: the token does not keep them.
Response
signature_requestsarray of objectNewest first.
paginationobjectpage_size,has_next, andnext_tokenwhen there is a next page: send it back asnext_token.
Errors
- 400
UNKNOWN_PARAMETERAn unsupported query parameter; the message lists the supported ones. - 400
INVALID_FILTERA 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"import os
import requests
response = requests.get(
"https://app.holofin.ai/api/v1.1/signature-requests",
headers={"X-API-Key": os.environ["HOLOFIN_API_KEY"]},
params={
"status": "completed",
},
)
response.raise_for_status()
print(response.json())const response = await fetch("https://app.holofin.ai/api/v1.1/signature-requests?status=completed", {
headers: {
"X-API-Key": process.env.HOLOFIN_API_KEY,
},
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());{
"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": "[email protected]",
"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": [
"[email protected]"
],
"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
/api/v1.1/signature-requests/inspectRuns a PDF through the same intake as a request and reports every marker found. Creates nothing and sends nothing.
Body
document_b64stringrequiredThe PDF, base64-encoded, as for a request.
Response
page_countintegerpagesarray of objectnumber,widthandheightof each page as displayed, in points: the space fields are placed in.removedarray of stringWhat intake took out of the file before freezing it, such as
javascriptorform_fields_flattened. A request would do the same.markersarray of objectEach marker found:
kind(signature,initialsordate),signer(its number),page(from 1),box(where the marker text sits,[x0, y0, x1, y1]in PDF points, origin top left) andfits: false when the mark would run off the page.signers_with_signature_markerarray of integerSigner numbers that have a
[Signature n]. A signer without one signs on an appended signature page.
Errors
- 400
INVALID_JSONThe body is not a JSON object. - 400
UNSUPPORTED_FIELDThe body carries a key other thandocument_b64. - 400
MISSING_DOCUMENTdocument_b64is missing. - 400
INVALID_DOCUMENTNot base64, not a PDF, or larger than 25 MB. - 422
DOCUMENT_REFUSEDThe PDF cannot be made safe to sign.reasonis an intake refusal code without itsintake_prefix. - 503
SERVICE_UNAVAILABLEReading PDFs is temporarily unavailable (busy, or a fault on our side). Retry after theRetry-Afterheader'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..."
}'import os
import requests
response = requests.post(
"https://app.holofin.ai/api/v1.1/signature-requests/inspect",
headers={"X-API-Key": os.environ["HOLOFIN_API_KEY"]},
json={
"document_b64": "JVBERi0xLjcKJcfsj6IK...",
},
)
response.raise_for_status()
print(response.json())const response = await fetch("https://app.holofin.ai/api/v1.1/signature-requests/inspect", {
method: "POST",
headers: {
"X-API-Key": process.env.HOLOFIN_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"document_b64": "JVBERi0xLjcKJcfsj6IK..."
}),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());{
"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
/api/v1.1/signature-requests/{request_id}/cancelWithdraws a waiting request: every link stops working and nobody else can sign. The body is optional.
Path parameters
request_idstringrequiredThe request's
id.
Body
reasonstringKept in the evidence log. At most 500 characters.
Errors
- 404
NOT_FOUNDNo resource with this ID in your organization. - 400
INVALID_JSONThe body is not a JSON object. - 400
INVALID_FIELDA field is missing, has the wrong type or is out of range; the message names it. - 409
CANNOT_CANCELThe request is no longerwaiting. 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."
}'import os
import requests
response = requests.post(
"https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/cancel",
headers={"X-API-Key": os.environ["HOLOFIN_API_KEY"]},
json={
"reason": "Replaced by a corrected version.",
},
)
response.raise_for_status()
print(response.json())const response = await fetch("https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/cancel", {
method: "POST",
headers: {
"X-API-Key": process.env.HOLOFIN_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"reason": "Replaced by a corrected version."
}),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());{
"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": "[email protected]",
"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": [
"[email protected]"
],
"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
/api/v1.1/signature-requests/{request_id}/signers/{signer_id}/resendEmails a new link. The previous link and any open signing session stop working, so the signer starts again from the code.
Path parameters
request_idstringrequiredThe request's
id.signer_idstringrequiredThe signer's
id, fromsigners.
Errors
- 404
NOT_FOUNDNo resource with this ID in your organization. - 409
CANNOT_RESENDNothing was sent: the request is notwaiting, 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"import os
import requests
response = requests.post(
"https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/signers/sigrcp_3hT9wE5yU2iO7pL1/resend",
headers={"X-API-Key": os.environ["HOLOFIN_API_KEY"]},
)
response.raise_for_status()
print(response.json())const response = await fetch("https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/signers/sigrcp_3hT9wE5yU2iO7pL1/resend", {
method: "POST",
headers: {
"X-API-Key": process.env.HOLOFIN_API_KEY,
},
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());{
"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": "[email protected]",
"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": [
"[email protected]"
],
"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
/api/v1.1/signature-requests/{request_id}/signers/{signer_id}/correctChanges 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_idstringrequiredThe request's
id.signer_idstringrequiredThe signer's
id, fromsigners.
Body
emailstringphonestring
Errors
- 404
NOT_FOUNDNo resource with this ID in your organization. - 400
INVALID_JSONThe body is not a JSON object. - 400
INVALID_FIELDA field is missing, has the wrong type or is out of range; the message names it. - 400
INVALID_SIGNERThe address or phone is not valid, or another signer already uses it. - 409
NOT_CORRECTABLEThe request is notwaiting, 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": "[email protected]"
}'import os
import requests
response = requests.post(
"https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/signers/sigrcp_3hT9wE5yU2iO7pL1/correct",
headers={"X-API-Key": os.environ["HOLOFIN_API_KEY"]},
json={
"email": "[email protected]",
},
)
response.raise_for_status()
print(response.json())const response = await fetch("https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/signers/sigrcp_3hT9wE5yU2iO7pL1/correct", {
method: "POST",
headers: {
"X-API-Key": process.env.HOLOFIN_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"email": "[email protected]"
}),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());{
"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": "[email protected]",
"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": [
"[email protected]"
],
"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
/api/v1.1/signature-requests/{request_id}/pdfThe 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 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_idstringrequiredThe request's
id.
Errors
- 404
NOT_FOUNDNo resource with this ID in your organization. - 409
NOT_COMPLETEDThe signed PDF exists once the request iscompleted.
curl -L "https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/pdf" \
-H "X-API-Key: $HOLOFIN_API_KEY" \
-o signed.pdfimport os
import requests
response = requests.get(
"https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/pdf",
headers={"X-API-Key": os.environ["HOLOFIN_API_KEY"]},
)
response.raise_for_status()
with open("signed.pdf", "wb") as f:
f.write(response.content)import { writeFile } from "node:fs/promises";
const response = await fetch("https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/pdf", {
headers: {
"X-API-Key": process.env.HOLOFIN_API_KEY,
},
});
if (!response.ok) throw new Error(await response.text());
await writeFile("signed.pdf", Buffer.from(await response.arrayBuffer()));Download the evidence log
/api/v1.1/signature-requests/{request_id}/evidenceEvery 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_idstringrequiredThe request's
id.
Response
formatstringrequest_idstringgenesisstringSHA-256 of the frozen document, which starts the chain.
frozen_sha256stringheadstringThe hash of the last event.
wording_versionstringprocess_versionstringeventsarray of objectIn order. Each has
seq,at,type,actor,ip,user_agent,data,prev_hashandhash.
Errors
- 404
NOT_FOUNDNo resource with this ID in your organization. - 409
NOT_SENTAdrafthas 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.jsonimport os
import requests
response = requests.get(
"https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/evidence",
headers={"X-API-Key": os.environ["HOLOFIN_API_KEY"]},
)
response.raise_for_status()
with open("evidence.json", "wb") as f:
f.write(response.content)import { writeFile } from "node:fs/promises";
const response = await fetch("https://app.holofin.ai/api/v1.1/signature-requests/sigreq_8fK2pQ7xR4mN1vB3/evidence", {
headers: {
"X-API-Key": process.env.HOLOFIN_API_KEY,
},
});
if (!response.ok) throw new Error(await response.text());
await writeFile("evidence.json", Buffer.from(await response.arrayBuffer()));{
"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
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 with these names, or with no events to receive everything. Deliveries are signed, retried and verified as described in Webhooks.
The event comes in the usual envelope. 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
A refusal at creation sends no event: the create call already answered it.
Requests made by a 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
- A PDF of at most 25 MB and 500 pages; 20 signers and 20
copy_toaddresses. - 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.