Skip to main content

PDF, data, or hash: what your signature request should carry

· 5 min read
Julien Jenoudet
Julien Jenoudet
CEO of IgniSign

When you add a signature step inside your product, the first technical choice is not the UI mode. It is what you put in the signature request. Your app may already hold a PDF contract, an office file, a JSON or XML record, or a document you prefer not to upload. IgniSign accepts those shapes. The integrating developer’s decision is which payload matches the object your product already owns — and what proof you expect back.

Four payloads, one request​

A signature request needs something to sign. In practice you choose among four inputs:

  • a PDF you already generated;
  • a file that is not a PDF (office document or image) that the service converts for signing;
  • structured data as JSON or XML;
  • a hash of a private file you keep on your side.

The request API is the same one-call path either way. What changes is the content type you attach and the shape of the signed artefact you later retrieve.

When a PDF is the right input​

Use a PDF when the user must see a fixed layout: a contract, a mandate, a consent form with pages and fields. Your product already produces that PDF, or you build it before calling the API. The signer reviews pages in the embedded iframe or a BySide link, then signs. The proof you retrieve includes a signed PDF with a signature page, plus the proof artefacts your app stores.

If the product’s source of truth is the PDF, do not round-trip through JSON just to feel more “API native.” Sign the document the user will keep.

When a file conversion is enough​

Sometimes the product holds a Word file or an image, not a PDF. You can send that file and let the signing service convert it for the ceremony. That is useful when generating a PDF in your backend is extra work and the visual result after conversion is acceptable for the flow.

It is the wrong choice when layout, fonts or exact pagination matter for the agreement. In that case generate the PDF yourself and send that.

When JSON or XML is the source of truth​

Many product flows do not start as documents. An onboarding step, a marketplace agreement or a mandate may live as a structured record in your database. Signing that record as JSON or XML keeps the signature tied to the data your backend already validates, instead of freezing a PDF you then have to reconcile with the record.

Use structured data when:

  • the signed object is machine-readable state, not a printable contract;
  • your backend will verify or process the signed payload later;
  • you do not need a page-by-page human review of a fixed PDF layout.

The proof for data signatures is signature files and related artefacts you can retrieve, not only a signed PDF. Plan your storage around the format your auditors and your code actually need.

When a hash is enough​

Some flows keep the document bytes entirely in your systems. You compute a hash, send that hash in the signature request, and the signer completes the ceremony against that commitment. Your product keeps the file; IgniSign works from the hash.

Pick the hash path when document residency is a hard constraint for that flow. Do not use it as a default “more private” switch for every request — for ordinary embedded contracts, a PDF or structured payload is the straightforward fit. The hash option exists for the case where your architecture already owns the bytes.

How to choose in one pass​

Ask three questions before you write the create-request call:

  1. What does the user need to read? Fixed pages → PDF (or a converted file only if the conversion is good enough). Structured fields with no fixed layout → JSON or XML.
  2. What does your backend already store as truth? Sign that object. Avoid inventing a parallel PDF if the record is the source of truth, and avoid inventing JSON if the PDF is what legal and the user will keep.
  3. Where must the bytes live? If they must stay in your storage, use a hash. Otherwise upload the PDF, file or data with the request.

The embedding mode (iframe or BySide) and the signature level (simple email or advanced with SMS or another sold method) are separate decisions. They do not change which payload type you attach. They change how the user signs and how you authenticate them.

The decision​

Carry a PDF when the agreement is a document. Carry JSON or XML when the agreement is a record. Convert a non-PDF file only when you accept the conversion. Carry a hash when your product must keep the bytes. Match the signature request to the object your product already owns, then retrieve the proof that matches that choice — signed PDF and proof page for documents, signature files and audit artefacts for data — and wire the webhook so your backend stores what it needs once the request is complete.