--- type: api title: Suggest a user profile description: **All methods and paths for this operation:** url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-security-suggest-user-profiles resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-security-suggest-user-profiles products: - Elasticsearch --- # Suggest a user profile Availability: 8.2+ ## Paths - `POST` (also `GET`) `/_security/profile/_suggest` - [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#apikeyauth) - [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#basicauth) - [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#bearerauth) ## Description Get suggestions for user profiles that match specified search criteria. NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice. ## Required authorization * Cluster privileges: `read_security` ## Query String Parameters - `data` (union string | [] string) A comma-separated list of filters for the `data` field of the profile document. To return all content use `data=*`. To return a subset of content, use `data=` to retrieve content nested under the specified ``. By default, the API returns no `data` content. It is an error to specify `data` as both the query parameter and the request body field. One of: `string` or `string[]` ## Request Body `application/json` - `name` (string) — optional A query string used to match name-related fields in user profile documents. Name-related fields are the user's `username`, `full_name`, and `email`. - `size` (number · default: 10) — optional The number of profiles to return. - `data` (union string | [] string) — optional A comma-separated list of filters for the `data` field of the profile document. To return all content use `data=*`. To return a subset of content, use `data=` to retrieve content nested under the specified ``. By default, the API returns no `data` content. It is an error to specify `data` as both the query parameter and the request body field. - `hint` ({} Hint) — optional Extra search criteria to improve relevance of the suggestion result. Profiles matching the spcified hint are ranked higher in the response. Profiles not matching the hint aren't excluded from the response as long as the profile matches the `name` field query. - `uids` ([] string) — optional A list of profile UIDs to match against. - `labels` (map string to string | string[]) — optional A single key-value pair to match against the labels section of a profile. A profile is considered matching if it matches at least one of the strings. ## Response `application/json` - `total` ({} TotalUserProfiles) Metadata about the number of matching profiles. - `value` (number) - `relation` (string RelationName) - `took` (number) The number of milliseconds it took Elasticsearch to run the request. - `profiles` ([] UserProfile) A list of profile documents, ordered by relevance, that match the search criteria. - `uid` (string) - `user` ({} UserProfileUser) - `email` (union string) — nullable One of: `string` - `full_name` (union Name | string) — nullable - `realm_name` (string Name) - `realm_domain` (string Name) - `roles` ([] string) - `username` (string) - `data` (map string to object) - `labels` (map string to object) - `enabled` (boolean) ## Code Examples #### Console ```console POST /_security/profile/_suggest { "name": "jack", "hint": { "uids": [ "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0", "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0" ], "labels": { "direction": ["north", "east"] } } } ``` #### JavaScript ```javascript const response = await client.security.suggestUserProfiles({ name: "jack", hint: { uids: [ "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0", "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0", ], labels: { direction: ["north", "east"], }, }, }); ``` #### Python ```python resp = client.security.suggest_user_profiles( name="jack", hint={ "uids": [ "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0", "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0" ], "labels": { "direction": [ "north", "east" ] } }, ) ``` #### curl ```curl curl -X POST "$ELASTICSEARCH_URL/_security/profile/_suggest" \ -H "Authorization: ApiKey $ELASTIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "jack", "hint": { "uids": [ "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0", "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0" ], "labels": { "direction": [ "north", "east" ] } } }' ``` #### Java ```java client.security().suggestUserProfiles(s -> s .hint(h -> h .uids(List.of("u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0","u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0")) .labels("direction", List.of("north","east")) ) .name("jack") ); ``` #### C# ```c# var response = await client.Security .SuggestUserProfilesAsync(d1 => d1 .Hint(d2 => d2 .Labels(new Dictionary>() { { "direction", ["north", "east"] } }) .Uids("u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0", "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0") ) .Name("jack") ); ``` #### PHP ```php $resp = $client->security()->suggestUserProfiles([ "body" => [ "name" => "jack", "hint" => [ "uids" => array( "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0", "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0", ), "labels" => [ "direction" => array( "north", "east", ), ], ], ], ]); ``` #### Ruby ```ruby response = client.security.suggest_user_profiles( body: { "name": "jack", "hint": { "uids": [ "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0", "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0" ], "labels": { "direction": [ "north", "east" ] } } } ) ``` ## Response Examples #### Suggest user profiles response example1 A successful response from `GET /_security/saml/metadata/saml1`. It contains the SAML metadata that was generated for the SAML realm as an XML string. ```json { "metadata" : "" } ```