Fieldmotion API Getting started

Jobs: reports, email and links

Generate a Word job report

POST /a/Job_getAsDocx

Return the report service’s Word document payload for a job using a Word report form.

When to use this endpoint

Use the Word option in the job export dialog when the form uses report_type=1. This is a JSON payload to decode/save, not an immediate Word download stream.

Authentication and permissions

The handler first requires a routed tenant table prefix. Normal signed API-key or CRM-session authentication establishes it; the handler does not call Core_requireLogin.

It prefers authenticated tenant context, with a legacy session.userid fallback only after the initial tenant-prefix guard. No new integration should rely on a signature-only session to authorize a download. Normal dispatcher user/account/IP restrictions and session CSRF 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

ParameterTypeRequiredDescription
idInteger stringYesPositive active physical job ID.
urlPresence flag (legacy control)NoSets an unused local return variable. Does not produce a URL or change the JSON response.

Example request

$result = FM_api('Job_getAsDocx', [
	'id' => '1042',
]);

Example response

{"ok":1,"mimetype":"application/vnd.openxmlformats-officedocument.wordprocessingml.document","base64":"UEsDBAoA","filename":"Example customer - 12-10-2026 - 1042.docx"}

The base64 is an abbreviated ZIP/Word prefix. The service payload is passed through; filename is always replaced with the configured job report filename plus .docx. The handler does not independently verify returned Word MIME/content.

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":"no such job"}Job missing/deleted.
{"error":"not complete"}Stored is_complete converts to 0.
{"error":"this job cannot be converted to DOCX"}The form’s report_type is not 1.
{"error":"We are experiencing unexpected request volumes. Please try again in a few minutes"}Empty service output or any returned error; the specific service error is hidden here.

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

Behaviour and edge cases

  • All nonzero completion statuses pass; there is no override flag. No list filtering, pagination or extra role check applies.
  • The UI additionally hides Word export for meta.disable-doc-export or phpdocx_version=-1. The handler reads phpdocx_version but does not enforce these UI restrictions.
  • Releases the session lock and uses a host-local lockfile with a 120-second freshness window. Calls Report_generateCall(kind=job, api=1), without explicit PDF conversion.
  • Filename uses job-report-filename and the same tokens/date sanitization as Job_getAsPdf. Asset-name lookup accepts the physical or mobile asset ID; related lookup rows are not active-filtered.
  • Unlike the PDF helper, this handler has no explicit outsourced-copy rejection. Report service behavior can still determine the result.

Side effects

  • Calls report generation/caching and creates/removes a local generation lockfile. No sent marker, job history or business-field write is performed by this handler.

See it in Fieldmotion

CRM1

Open a job’s Choose Format dialog and select Word. jobExport.js offers it only for compatible form metadata and saves the returned base64 bytes; filter Job_getAsDocx.

CRM2

Open job Export, then Word when shown. The same UI checks report_type, disable-doc-export and phpdocx_version; jobExport.js calls Job_getAsDocx.

Related endpoints