Fieldmotion API Getting started

Contracts

Export CRM1 contract data

POST /a/Contracts_getExportData

Run CRM1’s password-protected two-stage contract export: select filtered IDs, then return requested fields for explicit batches.

When to use this endpoint

Use Contracts_getExportData only with Fieldmotion’s CRM1 contract CSV exporter. Send _ids=1 for selection, then submit returned IDs in retryable data batches.

For normal integration reads, prefer named-field contract endpoints.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler performs no additional page or role-permission check.

The lookup and any write use the authenticated tenant; an ID from another tenant cannot be addressed through this call.

Parameters

ParameterTypeRequiredDescription
passwordStringYesPlain export password checked against the tenant’s salted customer-export-password setting on every phase.
_idsStringYesExact 1 selects IDs. Any other value must be a nonempty JSON array for the data phase.
fieldsJSON array stringData phaseOrdered export field names. Response f0, f1, and so on follow this order.
name / number / notes / customer_nameStringsNoSelection-phase substring filters. The customer-name filter has a legacy overmatching bug described below.
activeInteger stringNoExact status when present and nonblank; 0 selects completed rows.
searchStringNoNumeric input matches contract ID exactly; other text searches contract name.
date_from / date_toDate stringsNoInclusive expiry range, applied when nonblank date_from is present. The handler reads date_to without independently requiring it.
non_expiringInteger stringNoExact 1 broadens the expiry range to include null/legacy zero dates.

Example request

// Phase 1
$selection = FM_api('Contracts_getExportData', [
	'password' => 'replace-with-export-password',
	'_ids' => '1',
	'active' => '1',
]);

// Phase 2
$rows = FM_api('Contracts_getExportData', [
	'password' => 'replace-with-export-password',
	'_ids' => json_encode([720]),
	'fields' => json_encode(['name', 'budget', 'cost', 'contract_type_name']),
]);

Example response

// Phase 1
{
  "ids": [720]
}

// Phase 2
[
  {
    "id": "720",
    "custom": "{}",
    "f0": "North Region Service Contract",
    "f1": "25000",
    "f2": 1925.25,
    "f3": "Planned service"
  }
]

Accepted ordinary fields are active, budget, cost, contract_type_id, contract_type_name, custasset, date_completed, date_started, edate, id, jobs, name, net, notes, number, profit, and tax. Dynamic custom:<key> values are also accepted.

net, profit, and tax are literal zero in this implementation. cost sums linked job costs and rounds to three decimals.

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":"incorrect password"}The password is missing or does not match the tenant export setting. This check occurs before other validation.
{"error":"missing or invalid parameter: _ids"}_ids is omitted.
{"error":"_ids should be a JSON array of numbers"}Data-phase IDs do not decode to a nonempty array.
{"error":"fields should be an array of requested field names"}Data-phase fields is absent, malformed, empty, or not an array.
{"error":"unknown field name: ..."}A non-custom requested field is outside the allowlist.

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

Behaviour and edge cases

  • Both phases exclude soft-deleted contracts. Neither phase defines ordering or pagination; the export widget controls batch size.
  • The jobs count and calculated cost use only type-6 legacy links, not direct contract_id jobs.
  • IDs are integer-converted. Duplicate IDs collapse in SQL; missing rows are omitted. Duplicate requested fields produce separate fN keys.
  • Custom fields are omitted from a row when the stored custom object lacks the key.

See it in Fieldmotion

CRM1

On Contracts, choose Export, pass the password dialog, and configure CSV columns. The widget calls this route first with _ids=1, then with ID/field batches.

CRM2

CRM2 uses Contracts_getDataTable for ID selection and Contracts_getExportDataTable for data; it does not normally call this CRM1 variant.

Related endpoints