Fieldmotion API Getting started

Marketing

Retrieve lead sources by ID

POST /a/MarketingSources_getById

Fetch a selected batch of raw lead-source rows with an optional stored-field allowlist.

When to use this endpoint

Use MarketingSources_getById when an export or object cache already has source IDs and needs raw stored fields. It performs no search or pagination.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler requires login but performs no additional Marketing-page, create, edit, delete, or role-permission check.

All reads and writes use the authenticated tenant’s tables. CRM1 and CRM2 hide some controls through client-side permissions; these routes do not repeat those UI checks.

Parameters

ParameterTypeRequiredDescription
idsJSON array or native arrayYesSource IDs. Values are integer-converted and deduplicated. A scalar JSON number is rejected; send an array.
fieldsJSON arrayNoSubset of id, name, cdate, and last_edited. Unlike ids, this handler always JSON-decodes fields, so a native request array is not accepted.

Example request

$sources = FM_api('MarketingSources_getById', [
	'ids' => json_encode(['30124', '30125']),
	'fields' => json_encode(['id', 'name', 'last_edited']),
]);

Example response

[
  {"id":"30124","name":"Trade show","last_edited":"1760001000"}
]

cdate and last_edited are raw stored Unix timestamps, normally JSON strings. This differs from mapped detail routes, which format them as datetimes.

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: ids"}ids is absent.
{"error":"no ids in list"}The value does not decode to an array or the resulting array is empty.
{"error":"no fields selected"}Supplied fields is invalid JSON, not an array, or contains no allowed name.
[]No source matches the requested integer IDs.

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

Behaviour and edge cases

  • The table has no deleted or active filter.
  • Unknown fields are silently omitted when at least one allowed field remains.
  • The database query has no ordering; missing IDs are omitted and response position need not match request position.
  • The handler closes the PHP session before running the database query so concurrent requests are not held behind the session lock.

See it in Fieldmotion

CRM1

The CRM1 export widget calls this route when enriching selected lead-source IDs for exported customer/job data.

CRM2

No direct CRM2 caller was found; CRM2’s export and history widgets more often use MarketingSource_getRequestedDetails or the compact list.

Related endpoints