Jobs: reports, email and links
Generate a PDF or HTML job report
/a/Job_getAsPdf
Return generated job report data as PDF JSON, HTML JSON, or a streamed PDF.
When to use this endpoint
Use after a job is complete to download its report. The default result contains base64 bytes for the client to save. Use html=1 to inspect the generated report rather than expecting a PDF-shaped response.
Authentication and permissions
Signed API-key authentication or a logged-in CRM session must establish positive authenticated user and tenant IDs. The handler explicitly rejects a signature-only share session; its private generation helper is not a public authorization bypass.
Uses the authenticated tenant, releases the PHP session lock, and performs no additional role/finance check. Normal dispatcher user/account/IP restrictions and CRM-session CSRF requirements still apply.
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
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer string | Yes | Positive active physical job ID. |
html | Integer string | No | Default 0. Nonzero requests HTML and forces report-cache bypass in the report service. Returns html rather than PDF base64. |
pdf | Integer string | No | Default 0; forwarded as the report-service PDF-generation control. This is not the response-streaming flag. |
output | Integer string | No | Exactly 1 streams decoded PDF bytes with the returned MIME type and exits instead of JSON. Ignored for an HTML result. |
override_is_complete | Presence flag (legacy control) | No | Any present value, even 0, bypasses the zero-status completion guard. Internal/diagnostic control; ordinary integrations should complete/review jobs instead of relying on it. |
Example request
$result = FM_api('Job_getAsPdf', [
'id' => '1042',
]);Example response
{"ok":1,"mimetype":"application/pdf","base64":"JVBERi0xLjQK","filename":"Example customer - 12-10-2026 - 1042.pdf"}The base64 prefix is abbreviated, not a complete PDF. The report-service object can contain additional fields; the CRM helper replaces filename.
HTML mode returns an object containing html and filename ending .html, without requiring base64. output=1 on a non-HTML response returns binary, not JSON.
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":"job does not exist","id":1042} | Job is missing/deleted. |
{"error":"not complete"} | Stored is_complete converts to 0 and override_is_complete is absent. |
{"error":"cannot generate a job report from an outsourced client. reports must be sent from the original job creator account instead"} | Job is an outsourced copy with meta.outsourcing.link_from. |
{"error":"REPORTSERVER_URL not defined"} | Report service is not configured. |
{"error":"report generate route unavailable"} | Report generation returned no decodable object. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- There is no paging or list filtering. Missing/deleted jobs are rejected, but any nonzero is_complete value passes the legacy status guard; this is not restricted to status 1.
- A host-local per-tenant/job lockfile delays generation while a lock younger than 120 seconds exists. This is a file-age convention, not a distributed lock.
- Uses Report_generateCall with api=1, html, pdf and document_title; output error/error2 becomes a JSON error. Non-HTML non-PDF service output goes through the PDF converter.
- job-report-filename defaults to {{CUSTOMER}} - {{DATE}} - {{ID}}. Supported substitutions include CUSTOMER, CUSTOMER_STREET_ADDRESS1, CUSTOMER_JOB_REF, CUSTOMER_ACCOUNT_NUMBER, DATE, FORM_NAME, ID, JOB_REF, USER_NAME and ASSET_NAME in double braces. Slashes/backslashes become underscores; date formatting follows tenant settings. Fallback conversion requires strict base64 containing PDF bytes with a %PDF- header and %%EOF marker; malformed, empty or failed conversion returns Unable to convert job document to a valid PDF.
- Customer-name/address tokens use stored/historic customer details when appropriate. Asset jobs use the asset name; the assigned-user name can be resolved through an outsourced destination. Report/form edits and report-service cache freshness affect generated content.
- Request url and skip_cache are not forwarded by this endpoint. html=1 is the inspected fresh-preview path, not a promise of a general cache-control API.
Side effects
- Calls the report service and can generate/cache documents or convert Word output to PDF. Creates/removes its local lockfile; does not set report_sent, pdf_sent or invoice_sent.
See it in Fieldmotion
CRM1
Open a job’s Export/Choose Format dialog and select PDF download or HTML preview. jobExport.js calls Job_getAsPdf; preview supplies html=1. Bulk PDF/ZIP actions use the same route repeatedly.
CRM2
Open the job Export dialog and Download PDF. jobExport.js calls Job_getAsPdf and saves base64 using mimetype/filename. Bulk PDF/ZIP actions also use this endpoint.
Related endpoints
Job_getAsDocxretrieves the Word report for a compatible form.Job_printproduces a separate basic HTML summary, not the configured report.Job_emailReportsends the generated report by mail.