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.

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

StatusMeaning
draftKept, not sent. Nothing has been checked beyond shapes and limits, and no evidence log exists yet. See Drafts.
waitingSent. At least one signer has not signed.
finalizingEveryone 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.
completedSealed and delivered. pdf_url is set.
declinedA signer declined; the others can no longer sign. The signer's decline_reason says why.
expiredexpires_at passed before everyone signed.
cancelledYou withdrew it.
failedRefused 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_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_typeDEFRUS
ordinary_contract
Ordinary commercial or consumer contract
proceedproceedproceed
vehicle_rental_damage_waiver
Vehicle rental with a damage-waiver disclosure
proceedproceedflag
employment_termination
Ending an employment contract
refusewarnproceed
statutory_written_form
Document under a statutory written-form rule
providerflagproceed
consumer_suretyship_debt_ack
Consumer suretyship or acknowledgement of debt
refuseflagwarn
consumer_credit_loa
Consumer credit or leasing with a purchase option
providerproviderflag
court_or_statutory_notice
Court filing; default, foreclosure or eviction notice; cancellation of utilities or of health or life insurance; product recall
refuserefuserefuse
real_estate_notarised
Real-estate transfer or notarised act
refuserefuseflag
will_family_succession
Will, family law or succession
refuserefuserefuse

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"
  }
}
reasonWhat to do
document_type_excludedA simple signature is not allowed for this document in this country. Sign it another way.
provider_level_requiredThe document needs an advanced or qualified signature here. Use a provider that offers one, or aml_identification_confirmed where it applies.
disclosure_contact_missingstatutory_disclosures is on without disclosure_contact. Send one.
intake_encryptedThe PDF is password-protected or encrypted. Send it unprotected.
intake_already_signedThe PDF already carries a digital signature. Send the version before it was signed.
intake_too_many_pagesMore than 500 pages. Split the document.
intake_no_pagesThe PDF has no pages.
intake_page_too_largeA 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_complexReading 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.

MarkerWhat 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.

typeWhat prints thereSmallest box
signatureThe signature, the signer's name, the time and the request id.140 x 40
initialsThe signer's initials.24 x 14
dateThe signing date in UTC: DD/MM/YYYY when language is fr, YYYY-MM-DD in English.50 x 14
nameThe signer's name.40 x 14
emailThe signer's address.40 x 14
textYour 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

  • idstring

    Kept if you send one, else given as fld_<n>.

  • typestring

    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.

  • signerinteger | null

    The signer's place in signers, from 1. Null for text.

  • pageinteger

    From 1.

  • xinteger

    Points from the left edge of the page.

  • yinteger

    Points from the top edge of the page.

  • widthinteger
  • heightinteger
  • valuestring

    For text only: what to print, at most 500 characters.

  • groupstring

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

  • idstring

    Starts with sigreq_.

  • statusstring

    draft until it is sent, 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.

  • titlestring
  • external_refstring | null

    Your reference, as sent on creation.

  • workflow_run_idstring | null

    Set when a workflow's signature step created the request.

  • levelstring

    native_simple: a simple electronic signature.

  • verificationstring

    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).

  • languagestring

    One of fr, en.

  • placementstring

    One of page, tags, fields.

  • initials_every_pageboolean
  • document_typestring
  • countrystring
  • is_consumerboolean
  • guardrailobject

    What the document-type check 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_countinteger

    Pages of the frozen document.

  • pagesarray of object

    number, width and height of each page as displayed, in points: the space fields are placed in.

  • fieldsarray of object

    The fields placed on the pages, for placement: fields.

  • revisioninteger

    On a draft only: its version. Send it back with a change so that a change made elsewhere in between is not overwritten.

  • filesarray 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_urlstring | 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.

  • signersarray of object

    Signer objects, in the order you sent them. All are invited at once and sign in any order.

  • copy_toarray of string

    Addresses that receive the signed copy.

  • failureobject | null

    On a failed request: reason, one of the refusal codes, and detail, a sentence for a person.

  • created_atstring
  • sent_atstring | null
  • expires_atstring | null
  • completed_atstring | null

    When the request reached a final status.

  • retention_untilstring | 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_sha256string | null

    SHA-256 of the document the signers saw, after intake.

  • sealed_sha256string | null

    SHA-256 of the sealed PDF.

  • evidenceobject

    event_count and head, the hash of the last event of the evidence log.

  • pdf_urlstring | null

    Where to download the sealed PDF once completed. An API URL: call it with your key, it is not a public link.

  • evidence_urlstring

    Where to download the evidence log, with your key.

The signer object

Attributes

  • idstring

    Starts with sigrcp_.

  • positioninteger

    Place in signers, from 1: the n of this signer's markers.

  • namestring
  • emailstring
  • phonestring | null

    The mobile number the codes go to, in E.164. Set with sms_otp.

  • statusstring

    pending until the signer enters the code, then awaiting_consent, then signed or declined.

  • invitationobject | 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 or resend.

  • viewed_atstring | null

    When every page of the document had been shown to the signer.

  • verified_atstring | null

    When the signer entered the right code.

  • signed_atstring | null
  • declined_atstring | null
  • decline_reasonstring | null

    What the signer wrote when declining.

Create a signature request

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.

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

  • titlestringrequired

    Shown to the signers and in the emails. At most 255 characters.

  • document_b64stringrequired

    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_typestringrequired

    What the document is, from the 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.

  • countrystringrequired

    Two-letter code of the law that governs the document, such as FR.

  • signersarray 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.

  • verificationstring

    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_toarray of string

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

  • languagestring

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

  • messagestring

    Added to the invitation email. At most 2,000 characters.

  • placementstring

    page appends a signature page. tags prints each mark at its marker in the document. fields prints each mark in the box given in fields. Default "page".

  • fieldsarray of object

    With placement: fields: up to 1,000 fields. A signer without a signature field signs on an appended signature page. Not combined with initials_every_page: place initials fields instead.

  • draftboolean

    Keep 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. Default false.

  • initials_every_pageboolean

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

  • is_consumerboolean

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

  • statutory_disclosuresboolean

    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_contactstring

    Where a signer asks for paper or withdraws consent. At most 500 characters.

  • paper_copy_feestring

    The fee for a paper copy, as you want it shown, if there is one. At most 100 characters.

  • acknowledgementsarray 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_confirmedboolean

    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_daysinteger

    After this, an unsigned request becomes expired. Default 7.

  • reminder_daysinteger

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

  • external_refstring

    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

  • 400INVALID_JSONThe body is not a JSON object.
  • 400UNSUPPORTED_FIELDThe body carries a key this endpoint does not take.
  • 400INVALID_FIELDA key is missing, has the wrong type or is out of range. For a wrong field, field_index is its place in fields.
  • 400MISSING_DOCUMENTdocument_b64 is missing.
  • 400INVALID_DOCUMENTNot base64, not a PDF, or larger than 25 MB.
  • 400INVALID_SIGNERA 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.
  • 400INVALID_EXTERNAL_REFexternal_ref is not a string, or too long.
  • 422SIGNATURE_REQUEST_REFUSEDRefused before anything was sent. reason is one of the refusal codes; signature_request_id names the kept failed request.
  • 503SIGNING_UNAVAILABLESigning, or codes by SMS for sms_otp, is not open on this environment. Retrying does not help.
  • 503SERVICE_UNAVAILABLEReading 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": "[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());
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": "[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

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

Where the request stands, signer by signer.

Path parameters

  • request_idstringrequired

    The request's id.

Errors

  • 404NOT_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());
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": "[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

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.

Path parameters

  • request_idstringrequired

    The request's id.

Body

  • revisioninteger

    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

  • 404NOT_FOUNDNo resource with this ID in your organization.
  • 400INVALID_JSONThe body is not a JSON object.
  • 400UNSUPPORTED_FIELDThe body carries a key that belongs to another endpoint, such as case_fields on a run.
  • 400INVALID_FIELDA key has the wrong type or is out of range. For a wrong field, field_index is its place in fields.
  • 400INVALID_SIGNERA 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.
  • 409NOT_A_DRAFTThe request was already sent; only a draft can change or be sent.
  • 409DRAFT_CHANGEDThe 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": "[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());
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": "[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

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

Runs 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_idstringrequired

    The request's id.

Errors

  • 404NOT_FOUNDNo resource with this ID in your organization.
  • 400INVALID_FIELDSomething a request needs is missing or wrong, such as the title. For a wrong field, field_index is its place in fields.
  • 400INVALID_SIGNERA 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.
  • 409NOT_A_DRAFTThe request was already sent; only a draft can change or be sent.
  • 422SIGNATURE_REQUEST_REFUSEDThe document-type check refused it. reason is one of the refusal codes; the draft is kept.
  • 503SIGNING_UNAVAILABLESigning is not open on this environment. Retrying does not help.
  • 503SERVICE_UNAVAILABLEReading 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"
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());
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": "[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

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

Deletes a draft and its files. A sent request cannot be deleted: cancel it.

Path parameters

  • request_idstringrequired

    The request's id.

Errors

  • 404NOT_FOUNDNo resource with this ID in your organization.
  • 409NOT_A_DRAFTThe 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"
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

GET/api/v1.1/signature-requests

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

Query parameters

  • statusstring

    One of draft, waiting, finalizing, completed, declined, expired, cancelled, failed.

  • external_refstring

    Only the request with this reference.

  • limitinteger

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

  • next_tokenstring

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

Response

  • signature_requestsarray of object

    Newest first.

  • paginationobject

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

Errors

  • 400UNKNOWN_PARAMETERAn unsupported query parameter; the message lists the supported ones.
  • 400INVALID_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());
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": "[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

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_b64stringrequired

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

Response

  • page_countinteger
  • pagesarray of object

    number, width and height of each page as displayed, in points: the space fields are placed in.

  • removedarray 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.

  • markersarray 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_markerarray of integer

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

Errors

  • 400INVALID_JSONThe body is not a JSON object.
  • 400UNSUPPORTED_FIELDThe body carries a key other than document_b64.
  • 400MISSING_DOCUMENTdocument_b64 is missing.
  • 400INVALID_DOCUMENTNot base64, not a PDF, or larger than 25 MB.
  • 422DOCUMENT_REFUSEDThe PDF cannot be made safe to sign. reason is an intake refusal code without its intake_ prefix.
  • 503SERVICE_UNAVAILABLEReading 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..."
  }'
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());
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

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_idstringrequired

    The request's id.

Body

  • reasonstring

    Kept in the evidence log. At most 500 characters.

Errors

  • 404NOT_FOUNDNo resource with this ID in your organization.
  • 400INVALID_JSONThe body is not a JSON object.
  • 400INVALID_FIELDA field is missing, has the wrong type or is out of range; the message names it.
  • 409CANNOT_CANCELThe 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."
  }'
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());
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": "[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

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_idstringrequired

    The request's id.

  • signer_idstringrequired

    The signer's id, from signers.

Errors

  • 404NOT_FOUNDNo resource with this ID in your organization.
  • 409CANNOT_RESENDNothing 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"
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());
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": "[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

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_idstringrequired

    The request's id.

  • signer_idstringrequired

    The signer's id, from signers.

Body

  • emailstring
  • phonestring

Errors

  • 404NOT_FOUNDNo resource with this ID in your organization.
  • 400INVALID_JSONThe body is not a JSON object.
  • 400INVALID_FIELDA field is missing, has the wrong type or is out of range; the message names it.
  • 400INVALID_SIGNERThe address or phone is not valid, or another signer already uses it.
  • 409NOT_CORRECTABLEThe 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": "[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());
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": "[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

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

    The request's id.

Errors

  • 404NOT_FOUNDNo resource with this ID in your organization.
  • 409NOT_COMPLETEDThe 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
import 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

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_idstringrequired

    The request's id.

Response

  • formatstring
  • request_idstring
  • genesisstring

    SHA-256 of the frozen document, which starts the chain.

  • frozen_sha256string
  • headstring

    The hash of the last event.

  • wording_versionstring
  • process_versionstring
  • eventsarray of object

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

Errors

  • 404NOT_FOUNDNo resource with this ID in your organization.
  • 409NOT_SENTA 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
import 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()));
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

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

{
  "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

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_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.