Fieldmotion API Getting started

Jobs: reports, email and links

Request a customer signature on a job

POST /a/Job_signatureRequest

Create and email a one-use customer signing request for a named signature field on a job.

When to use this endpoint

Choose a signature field from the job’s form, collect one recipient address, then request signing. The recipient follows the emailed public link; creating a request does not sign or complete the job.

Authentication and permissions

Signed API-key authentication or a logged-in CRM session is required. The handler uses the authenticated tenant and has no additional role/page check.

The dispatcher also applies user/account and IP restrictions. CRM sessions carrying a CSRF token must supply X-FMCSRF or _csrf; missing or incorrect tokens can be rejected before the handler runs.

Parameters

ParameterTypeRequiredDescription
idInteger stringYesPositive active physical job ID.
emailStringYesOne address that passes PHP FILTER_VALIDATE_EMAIL; comma-separated multiple addresses are rejected.
sig_fieldStringYesExact signature field name, not its stable field ID. Presence only is checked here; field existence/type is deferred until save.
send_reportInteger stringYesStored as an integer in request metadata. Nonzero requests a report email after successful signing; 0 disables it.
subjectStringYesPresence is required; empty is accepted by the handler. Forwarded as mail subject.
messageStringYesPresence is required; empty accepted. HTML is escaped and newlines converted to HTML breaks.
email_templateInteger stringNoDefault 0. Signature-request mail template selection; no template existence check here.
quote_idInteger stringNoPositive value added to email metadata for a related quote. It does not change the request into a quote signature or authorize/change that quote.

Example request

$result = FM_api('Job_signatureRequest', [
	'id' => '1042',
	'email' => 'customer@example.com',
	'sig_field' => 'Customer signature',
	'send_report' => '0',
	'subject' => 'Please sign the job report',
	'message' => 'Please review the report before signing.',
]);

Example response

{"ok":1}

Errors and unusual responses

ResponseCondition
{"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: email"}email absent; analogous presence errors name sig_field, send_report, subject or message.
{"error":"invalid job id supplied - job not found"}Job missing/deleted.
{"error":"invalid email address?"}email does not validate as one address.

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

Behaviour and edge cases

  • Expiry days come from signature-request-expiry-days, valid range 1–365 and fallback 7. A valid job-signature-request-expiry-days overrides the general setting. The request stores expiry_date and email text states that duration.
  • Customer view/save enforce pending status, expiry and stored request type. Tokens are sensitive bearer credentials; never publish a working token.
  • Creates a new request/token on every call; no deduplication or outstanding-request cancellation. The generated public link contains pid and md5 and addresses Job_signatureCustomerView.
  • The handler does not verify the chosen field, completion status, recipient ownership or quote relationship. CRM1 validates available signature fields and warns when send_report is selected for an incomplete job; those are UI checks.
  • No filtering, pagination or extra role restriction applies. Request creation and mail are not transactional.

Side effects

  • Creates a pending signature-request row with recipient, requesting user, field name, expiry and send_report flag; logs job history signature request.
  • Attempts type-7 Core_mail with an escaped message and public link. Sets job meta.signed_by_request=1 only when that key is absent, advancing last_edited/edited_uuid and invalidating the job cache then. Existing signed/request values are not reset.

See it in Fieldmotion

CRM1

From the jobs list, choose Request a Signature, select the form’s signature field and send. jobSignatureRequest.js posts Job_signatureRequest; email_template comes from type-8 templates and send_report from the checkbox.

CRM2

Open the job email widget’s Signature Request mode. widgetSendEmail.js posts Job_signatureRequest and can add quote_id; a separate Quote_signatureRequest call handles any requested quote signing.

Related endpoints