User accounts and profiles
Read one user metadata value
/a/User_getMeta
Fetch one top-level tenant user preference without loading the complete user record.
When to use this endpoint
Use with User_setMeta for preferences such as dashboard configuration or app stylesheet URLs. The key is literal, not a dotted JSON path.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. Session requests use the dispatcher’s CSRF protection when configured; signed requests follow the API-key authentication flow.
The handler requires an authenticated tenant and adds no administrator, Users page or self-only permission check. This describes this legacy route; permissions enforced by other User update routes do not automatically apply here.
The dispatcher applies configured TeamAccess user-record scope before the handler. An explicit target outside that scope returns an error; omitted targets use the current user for the scope check. Active/deleted filtering and additional target checks are described below.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | String | Yes | Literal top-level metadata key. Omitted, empty and the string 0 are rejected by the initial truthiness check; whitespace is not trimmed. |
id | Integer string | No | Defaults to the current user if omitted or integer-converted to zero. A negative value is retained for the lookup rather than defaulted. |
Example request
$result = FM_api('User_getMeta', [
'name'=>'dashboard',
]);Example response
{
"dashboard": null
}The property name is the requested key. Null can mean absent key or a saved null value.
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: name"} | name is omitted, null or falsy. |
{"error": "user does not exist"} | Tenant lookup returns no user. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Reads only the tenant users metadata; it does not merge or fall back to global identity metadata. A missing key returns that key with null, not a missing-user error. Stored strings containing JSON remain strings.
- No self-only or Users page-read guard is present in the handler, and no active/deleted filter is added. Configured TeamAccess may restrict the target before the lookup.
- Getter does not trim name, while User_setMeta trims it. Passing surrounding whitespace can therefore read a different key from the key written by the setter.
- No collection filtering, pagination, ordering or batch result is provided. Parameters on this page describe the supported scalar/encoded input; malformed nested values are not a supported contract.
Side effects
- Read-only. No edit markers, activity logs or metadata changes.
See it in Fieldmotion
CRM1
Open the CRM1 Dashboard to observe User_getMeta name=dashboard. The Purchase Order page reads limit_po_value; the app stylesheet dialog reads app_css_url for a selected user.
CRM2
The app stylesheet dialog in fmTools reads User_getMeta with the selected user id and name=app_css_url. Filter this exact request in developer tools.
Related endpoints
User_setMeta— Merge one ordinary preference into both identity stores.User_setCustom— Use the custom_values namespace for configured profile fields.