Jobs: lookups and details
Retrieve and refresh a job’s customer snapshot
/a/Job_getCustomerDetails
Read the job’s historic customer/asset details, repairing its saved snapshot when required.
When to use this endpoint
Read the job’s historic customer/asset details, repairing its saved snapshot when required.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. These calls use the authenticated account’s data; the handler has no additional job-page, department, assignee or client-admin permission check unless stated below.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer string | Yes | Job ID, converted with intval; the result must be positive. This selects a physical job ID, not an app ID or job reference. |
refresh | Integer string | No | Only intval(refresh)===1 forces recomputation. Omitted/other values still allow automatic repair of invalid or stale snapshots. |
Example request
$result = FM_api('Job_getCustomerDetails', ['id' => '1042']);Example response
{"city":"","country":"GBR","county":"Antrim","landline":"02800000000","latitude":"54.5973","longitude":"-5.9301","mobile":"","name":"Northwind Service Centre","parent_id":0,"postcode":"BT1 1AA","state":"","street_address1":"1 Service Road","street_address2":"","town":"Belfast"}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"} | id is absent or nonpositive. |
{"error":"job does not exist"} | No active job matches, or its lookup fails. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Returns a decoded details object, not {customer_details:...}. Missing referenced data can produce an empty list. Fields vary for customers, assets and outsourced jobs; parent_id is normalized to a nonnegative integer when present.
- Blank/invalid JSON, missing/blank name or parent_id, or a positive parent without parent_name triggers repair. Numeric parent_id=0 is valid, not missing. A newer customer/asset last_edited can also trigger recomputation; otherwise a valid cached snapshot is reused.
- Historic resolution uses the job’s scheduled epoch plus 60 seconds; an unscheduled job here falls back to current time. Customer address/name/parent history is consulted, with current values as fallback where history is incomplete. Asset resolution follows historic movements/location, then owner fallback, and adds asset identity to the name.
- Outsourced-copy metadata can resolve customer data from the originating account, or its embedded customer snapshot. This is an explicit cross-account helper path, not arbitrary caller-supplied account selection.
- If both historic customer coordinates are zero/missing, available current customer coordinates fill the snapshot. It does not geocode or add address-history rows.
Side effects
- When details change or parent_id needs type normalization, updates job customer_details, last_edited and edited_uuid=Job_customerDetailsRefresh and requests the meetings cache marker.
- No customer address-history entry, notification or customer write is added. There is no transaction coupling the returned details to successful cache persistence.
See it in Fieldmotion
CRM1
In the scheduler, refresh job customer/location details. widgetScheduler.js sends Job_getCustomerDetails with refresh=1 for each selected job and replaces its displayed details.
CRM2
No direct CRM2 network caller was found. CRM2 mapped job lists use the same snapshot helpers indirectly; the explicit endpoint remains useful for diagnosing a stale snapshot.
Related endpoints
Job_getAddressreads a narrower current postal address without repairing a snapshot.Job_getLocationreads current coordinates, not the saved historic job details.