User accounts and profiles
Resolve users by exact names
/a/Users_listByNames
Translate imported display names into existing user IDs.
When to use this endpoint
Use for import mappings after collecting name strings. Duplicate user names can match multiple records; this is not a unique-name resolver.
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.
Configured TeamAccess row scope is applied in the queries. Ordinary collection requests do not need artificial record IDs. Explicit IDs still pass dispatcher record authorization; unavailable IDs can be rejected there rather than silently omitted.
Login is required. No additional page permission is imposed by this handler.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
names | JSON or native string list | Yes | Flat list of exact names, trimmed before matching. [] returns []; unmatched values are omitted. Duplicate names can resolve multiple user records. |
Example request
$result = FM_api('Users_listByNames', [
'names'=>json_encode(['Alex Morgan']),
]);Example response
[
{
"id": "1042",
"name": "Alex Morgan"
}
]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 parameter: names"} | names absent/null. |
{"error": "invalid parameter: names"} | names is not a flat string list. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Filters current-parent users and excludes any present is_tmp metadata value. Inactive users remain eligible.
- No pagination or ORDER BY. Unmatched names are omitted and [] returns [] before SQL. Native and JSON flat string lists are accepted; JSON objects/nested values are rejected.
- Names are trimmed before matching; database collation controls case sensitivity. Invalid values return invalid parameter: names without echoing the supplied value.
Side effects
- Reads data without changing business records, edit markers, activity history or notifications. Shared setting reads can populate their normal settings cache.
See it in Fieldmotion
CRM1
CRM1 import translation calls Users_listByNames through widgetImport’s name-to-ID mapping.
CRM2
CRM2 import widgets submit JSON.stringify of distinct display names to the same route.
Related endpoints
Users_getById— Fetch a selected, allowlisted projection after obtaining IDs.Users_list— Read the basic selectable user list and its explicit scope predicate.