Request a signature on a quote

When to use this endpoint

Use when a selected quote Form signature field needs an external signature. It sends a link; it does not sign the quote synchronously.

Authentication and permissions

Authenticate with signed API-key fields or a CRM session. Requires Quotes View (pageQuotes_view); non-admin users blocked by legacy crm_access bit 32 are denied. Client administrators inherit page permissions.

Requires Quotes Edit in addition to View. Template setters also require client-administrator permission.

Quote visibility follows the account’s department/account-manager customer filters for non-admin users, including signed keys. Export routes additionally require pageMain_exportTableData. Linked Jobs require Jobs View and their TeamAccess scope; invoice enrichment requires Invoices View and the legacy invoice access check.

Parameters

Parameter	Type	Required	Description
`id`	Positive integer-compatible quote ID	Yes	Requires an active quote.
`email`	Single email address	Yes	Trimmed and validated as a single email address.
`sig_field`	String	Yes	Must match a nonblank signature-type field ID on this quote’s Form.
`subject`	String	Yes	Nonblank string.
`message`	String	Yes, may be blank	HTML-escaped and line breaks converted to HTML.
`email_template`	Integer-compatible template ID	No	Defaults 0; a nonzero ID must resolve to an unarchived general/signature-request template.
`send_quote`	Integer-compatible switch	No	Canonical 0/1 choice. Legacy send_report is accepted only when send_quote is omitted; default 0.

Example request

$result = FM_api('Quote_signatureRequest', [
	'id'=>'1042','email'=>'developer@example.com',
	'sig_field'=>'1042001','subject'=>'Please sign this quote',
	'message'=>'Follow the link to sign.','send_quote'=>'0',
]);

Example response

{"ok":1}

Errors and unusual responses

Response	Condition
`{"error":"not logged in"}`	No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
`{"error":"missing or invalid parameter: id"}`	Missing/nonpositive ID.
`{"error":"missing or invalid parameter: sig_field"}`	A required parameter is absent; email/subject/message use the same error pattern.
`{"error":"invalid quote id supplied - quote not found"}`	No active quote.
`{"error":"invalid email address?"}`	Invalid single recipient.
`{"error":"permission denied"}`	Required Quotes/Export permission is absent or legacy access restrictions apply.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

Requires Quotes Edit/View and an active visible quote. Validates one trimmed email address, a nonblank subject and an actual signature-type field ID on the quote’s Form. Message may be blank.
send_quote is canonical; send_report is a compatibility alias when send_quote is omitted. Only 0/1 values are accepted. The selected unarchived email template must be general or signature-request type.
Expiry uses a valid quote-signature-request-expiry-days override, then signature-request-expiry-days, otherwise seven days; valid values are 1–365. Token generation uses 16 secure random bytes encoded to the existing 32-character storage format.
Commits a durable signature request and creation history before sending its link. A failed insert/audit does not send email. If called inside an outer transaction, returns the request ID and a warning without sending before that transaction commits.
Requires a positive mail acknowledgement before recording request email_sent/email_id and merging signed_by_request into freshly locked quote metadata. Uncertain mail returns retry_safe=false and request_id; it does not mark the quote sent or replay mail.
A confirmed send followed by metadata/history failure returns saved success plus a no-resend warning. Repeated explicit requests can create separate signing requests; this is not a deduplication API.
No direct caller for this endpoint was found in the mobile app or its m-service intermediary.

Side effects

Creates and audits a durable request before mail, then saves sent markers only after positive acknowledgement. Mail and SQL are not distributed-atomic; uncertain results require mail-history inspection.

See it in Fieldmotion

CRM1

Quotes → Request a Signature opens quoteSignatureRequest. The dialog chooses a Form signature field, recipient, template and send_quote checkbox.

CRM2

The shared signature email dialog uses the compatible send_report alias; the backend normalizes it to send_quote. Signature field, Form and mail acknowledgement are validated.

Related endpoints

Quote_sendEmail sends ordinary quote mail.
Quotes_getDataTable enriches list rows with request signatures.