Retrieve opportunity layout details

When to use this endpoint

Use Opportunity_getLayoutDetails through CRM2’s layout renderer when an opportunity create/update layout requests stored details. For general batched reads, use Opportunity_getRequestedDetails.

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

Parameter	Type	Required	Description
`fields`	Native array	Yes	Mapped field keys to return. A JSON string is not decoded here. Supported keys are listed on `Opportunity_getRequestedDetails`; unknown keys are ignored and `id` is always added.
`widgetFormField`	Field name inside fields	No	When requested, the handler also reads `formID`/`formValues` and returns `{"formID":...,"formFields":...}` under this key.
`id / ids`	Integer string or native array	No	Restrict by one/many IDs. Without either, all matching non-deleted opportunities are returned. `id` takes precedence.
`Mapped field filters`	Scalar or native array	No	Any mapped non-composite field can also filter results: numeric values are integer-matched; text/JSON values are exact case-insensitive matches.
`order / advanceSearch`	Shared mapped controls	No	Optional mapped ordering and advanced conditions. There is no pagination or limit.

Example request

$rows = FM_api('Opportunity_getLayoutDetails', [
	'id' => '481',
	'fields' => ['id', 'customer', 'widgetFormField'],
]);

Example response

[
  {
    "id": "481",
    "customer": {"id": "1042"},
    "widgetFormField": {"formID": "12", "formFields": "{\"field-1\":\"Yes\"}"}
  }
]

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: fields"}`	`fields` is absent.
`Runtime type error`	`fields`, an ID list, composite filter, order, or advanced-search control has an unsupported scalar/JSON-string shape.

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

Behaviour and edge cases

Soft-deleted opportunities are excluded. A missing ID produces an empty array, not an error.
Epoch fields are returned as SQL datetime strings. Whole JSON columns such as formValues remain encoded strings, while requested JSON subpaths are extracted; user/customer/quote picker fields are reconstructed as objects containing id.
The helper temporarily adds formID and formValues for widgetFormField, then removes either field unless it was explicitly requested too.

See it in Fieldmotion

CRM1

CRM1 does not use CRM2 layout-detail routes.

CRM2

The shared layout renderer derives this route from table opportunity when opening the opportunity layout.

Related endpoints

Opportunity_getRequestedDetails exposes the same map without the widget alias.
Opportunity_updateData saves layout values.