Developer API

Other Frappe apps can use Frappe Sign as their signing engine. Your app owns the business record (a KPI review, a disciplinary form, a policy acknowledgement), and Frappe Sign handles the PDF, signers, fields, links, emails, signed PDFs, certificates, hashes, events, validation and tamper checks.

The recommended model:

1. Your app owns the record and chooses the Print Format.
2. Frappe Sign renders the PDF from that record.
3. Your app passes signer profiles and field positions.
4. Frappe Sign creates (and optionally sends) the request, and generates each signer's link.
5. Signers sign through Frappe Sign.
6. Your app reads the completed request (or its files) to update its own workflow.

create_signing_request_from_document

frappe_sign.api.integration.create_signing_request_from_document(
    source_doctype,
    source_name,
    print_format=None,
    request_title=None,
    signing_mode="Parallel",
    signers=None,
    fields=None,
    send=False,
)

The source DocType must be configured in Frappe Sign Settings (see Configured Source DocTypes), so integrations follow the same configuration and permission model as the Desk button. The calling user needs permission to create Frappe Sign Requests (normally Frappe Sign Sender) and read permission on the source document.

It returns, for example:

{"name": "...", "status": "Sent", "source_pdf": "/private/files/...pdf",
 "signer_count": 2, "field_count": 4, "sent": True, "sent_signer_count": 1}

Signers

Each signer must resolve to an active Frappe Sign Profile, through profile (or its aliases signer / profile_name), user, or email.

{"key": "employee", "profile": "…", "role": "Signer", "signing_order": 1}

Fields

{"signer_key": "employee", "field_type": "Signature", "page": 1,
 "x_ratio": 0.10, "y_ratio": 0.80, "width_ratio": 0.30, "height_ratio": 0.06, "required": 1}

Typical sizes: Signature 0.25–0.35 × 0.05–0.08; Initials 0.08–0.14 × 0.03–0.05; Date 0.12–0.20 × 0.03–0.05; Checkbox 0.025–0.04 square; Text 0.20–0.50 × 0.04–0.08.

Ratios only stay correct if the signing block appears in a predictable place. For Print Formats that grow with their content, reserve a fixed signing block, put it on a forced final page, or create with send=False and let someone confirm placement in the Designer.

Example: sequential two-party request

result = frappe.call(
    "frappe_sign.api.integration.create_signing_request_from_document",
    source_doctype=doc.doctype,
    source_name=doc.name,
    print_format="KPI Review Signing Format",
    request_title=f"KPI Review - {doc.employee_name}",
    signing_mode="Sequential",
    signers=[
        {"key": "employee", "user": doc.employee_user, "role": "Signer", "signing_order": 1},
        {"key": "manager", "user": doc.manager_user, "role": "Signer", "signing_order": 2},
    ],
    fields=[
        {"signer_key": "employee", "field_type": "Signature", "page": 1,
         "x_ratio": 0.10, "y_ratio": 0.80, "width_ratio": 0.30, "height_ratio": 0.06},
        {"signer_key": "manager", "field_type": "Signature", "page": 1,
         "x_ratio": 0.60, "y_ratio": 0.80, "width_ratio": 0.30, "height_ratio": 0.06},
    ],
    send=True,
)
doc.db_set("frappe_sign_request", result["name"])

Security notes

• Never generate or distribute signing links yourself. Let Frappe Sign create them when the request is sent.
• Signing links are bearer tokens: each signer must receive only their own.
• Check permissions in your own whitelisted method before calling the API on a user's behalf.

Reacting to completion

When a request completes it holds the signed PDF, audit certificate, final package (if enabled), their hashes, the event chain hash and certificate records. Your app can react by checking the linked request's status, with a scheduled job, or with your own doc_events hook on Frappe Sign Request. If all you need is the signed PDF on the record, use Attach Signed PDF To Source instead.

The complete reference, with more examples, is in API_README.md in the app's repository.