# Search users

Search users scoped to the caller's active account. Requires EM_ACCOUNT.USER edit permission
on the active account. If accountIdentifier is supplied it must match the active account.

Endpoint: POST /users/action/search
Version: 1.0.0-beta
Security: bearerToken

## Query parameters:

  - `page` (integer)

  - `size` (integer)

  - `include` (string)
    Comma-separated values from optional response fields

## Request fields (application/json):

  - `accountIdentifier` (string)
    Account identifier. Callers are scoped to their active account; a mismatched value returns forbidden.

  - `email` (string)
    User's email address

  - `firstName` (string)
    User's first name

  - `lastName` (string)
    User's last name

  - `authSub` (string)
    Authentication subject identifier

  - `login` (string)
    User's login name

  - `status` (string)
    Ref.Data.USER_STATUS

  - `lastLoginFrom` (string)
    Lower bound of last login timestamp range (inclusive).

  - `lastLoginTo` (string)
    Upper bound of last login timestamp range (inclusive).

## Response 200 fields (application/json):

  - `page` (integer, required)

  - `size` (integer, required)

  - `totalPages` (integer, required)

  - `totalElements` (integer, required)

  - `content` (array, required)

  - `content.firstName` (string, required)
    Must not contain digits (0-9). Special characters are allowed. Same validation as legacy EMA UI.
    Example: "John"

  - `content.middleName` (string)
    Must not contain digits (0-9). Special characters are allowed. Same validation as legacy EMA UI.
    Example: "Jackson"

  - `content.lastName` (string, required)
    Must not contain digits (0-9). Special characters are allowed. Same validation as legacy EMA UI.
    Example: "Doe"

  - `content.email` (string, required)
    Example: "john.doe@example.com"

  - `content.jobTitle` (string, required)
    Example: "Portfolio Manager"

  - `content.telephone` (string)
    Example: "555-123-4567"

  - `content.authSubject` (string)
    Example: "auth0|asdfghjkl1234567890"

  - `content.login` (string)
    User login name. Required when editing an existing user.
    Example: "johndoe"

  - `content.address` (object, required)

  - `content.address.postalCode` (string, required)
    Example: "12345"

  - `content.address.city` (string, required)
    Example: "New York"

  - `content.address.country` (string, required)
    Ref.Data.COUNTRY

  - `content.address.addressLineOne` (string, required)
    Example: "5 Broadway"

  - `content.address.addressLineTwo` (string)
    Example: "5th floor"

  - `content.address.stateProvince` (string)
    Ref.Data.STATE_PROVINCE

  - `content.organizationRelationship` (string)
    Ref.Data.USER_ORGANIZATION_RELATIONSHIP

  - `content.roles` (array)
    Account-scoped entitlement roles only.
    Enum: "ACCOUNT_ADMIN", "ACCOUNT_MANAGER", "EXCHANGE_READ", "EXCHANGE_WRITE", "PORTFOLIO_READ", "PORTFOLIO_WRITE"

  - `content.account` (object)
    Optional property. Use include param.

  - `content.account.id` (integer, required)

  - `content.account.identifier` (string, required)
    Example: "0980A123"

  - `content.account.noOfUsers` (integer, required)

  - `content.account.status` (string, required)
    Ref.Data.ACCOUNT_STATUS
    Example: "APPROVED"

  - `content.account.maxUsers` (number, required)

  - `content.account.childAccounts` (array, required)

  - `content.account.registryLinks` (array, required)

  - `content.account.registryLinks.program` (string, required)
    Ref.Data.PROGRAM

  - `content.account.registryLinks.registryAccountId` (string, required)

  - `content.account.registryLinks.status` (string, required)
    Ref.Data.REGISTRY_LINK_STATUS

  - `content.account.registryLinks.lastSyncDate` (string,null)
    Incremental sync watermark (RFC 3339 date-time), equivalent to the server's sync time identifier used for incremental sync. Omitted or null when the registry link has never been synced.

  - `content.account.organization` (object, required)

  - `content.account.organization.iamOrgId` (string)

  - `content.account.organization.legalName` (string, required)
    Example: "RVCMC Sub Default"

  - `content.account.organization.structure` (string, required)
    Ref.Data.ORGANIZATION_LEGAL_STRUCTURE
    Example: "PRIVATELY_OWNED_CORP"

  - `content.account.organization.type` (string, required)
    Ref.Data.ORGANIZATION_TYPE
    Example: "BROKER"

  - `content.account.services` (array, required)
    Service accounts for this EMA account. Each item is an AccountService

  - `content.account.services.status` (string, required)
    Ref.Data.SERVICE_ACCOUNT_STATUS
    Example: "APPROVED"

  - `content.account.services.type` (string, required)
    Ref.Data.SERVICE_TYPE
    Example: "ACX"

  - `content.account.services.attributes` (any)
    Shape is determined by the parent service type (Ref.ServiceType), using mapping: ACX → AcxAccountServiceAttributes; SUBACCOUNT_SERVICE → SubaccountAccountServiceAttributes; CUSTODIAN_SERVICE → CustodianAccountServiceAttributes. If there are no service attributes (all other service types), do not display this object — omit attributes, or return attributes as an empty object.

  - `content.status` (string)
    Ref.Data.USER_STATUS

  - `content.lastLogin` (string)
    Last login timestamp

  - `content.isAdmin` (boolean)

## Response 400 fields (application/json):

  - `code` (string)
    Enum: "INVALID_REQUEST", "INVALID_PAGE_SIZE", "INVALID_PAGE_NUMBER"

  - `message` (string)

## Response 401 fields (application/json):

  - `message` (string)

## Response 500 fields (application/json):

  - `message` (string)