Search for user profiles

Searches an entity type for all the users who meet the specified criteria. For example, you might search for all the users who haven't logged on since a specified date, or all the users whose accounts were created after a specified date.

When constructing a search query (by using the filter parameter), the following operators are supported, from highest to lowest precedence:

• is null, is not null (postfix)
• not, ! (prefix)
• >, >=, <, <= (infix)
• =, != (infix)
• and (infix)
• or (infix)

📘

Previous releases of this operation included the contains operator. This operator has been removed because its behavior was counterintuitive. If you use this operator now, you will get a 485 error.

When using the filter parameter, string values specified by operators must be surrounded by single quotes. Integer values work either with or without single quotes. If used with email, only a full email address can be used (for example, `fsmith@example.com). Note that you can't filter on a domain name (for example, akamai.com).

Refer to the Registration error codes page for details on error codes.

Important: Querying large datasets

When using the entity.find endpoint to search large sets of data (more than 100,000 records), queries should be optimized using natural database sorting by sorting on the id attribute. This has two benefits:

• Returns records created between when the time iteration begins and when the time iteration ends.
• Provides efficient and consistent performance querying and loading for each page of results.

The following tips will help you optimize your queries:

• Use the attributes parameter to limit the number of attributes returned for each record. This helps to minimize the size of the HTTP payload.

• Experiment with the max_results parameter to optimize for responses of less than 10 seconds.

• Include the timeout parameter (up to 60 seconds) if and only if you are unable to keep responses under 10 seconds by using the max_results parameter.

• If you don't care about the order in which your results are returned (for example, if you're returning only one user profile or if the sort order doesn't matter), it's recommended that you include the sort_on parameter and set the value to an empty array:

  sort_on='[]'

  This typically results in improved performance.

See Query or import large data sets for a sample Python script that returns each record created since January 1, 2016.

API client permissions

The following table indicates the API clients that can and can't be used to call this operation:

Authentication

This operation supports both Basic authentication (recommended) and janrain-signed authentication. See Get started for more information.

Base URL

The base URL for this operation is your Identity Cloud Capture domain; for example:

https://educationcenter.us-dev.janraincapture.com

Your Capture domain (also known as a Registration domain) can be found in Console on the Manage Application page.

Examples

Example 1: Return all the users in an entity type

This command returns user profile information for all the users in the user entity type, sorting the returned results by the lastUpdated attribute (the last time the user profile was modified). Note that the hyphen in front of lastUpdated means that the returned data is sorted in descending order (i.e., from the most-recently updated profile to the profile that has gone the longest amount of time without being updated). To sort in ascending order, leave off the hyphen.

curl -X POST -H "Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=" \
  --data-urlencode type_name=user \
  --data-urlencode sort_on='["-lastUpdated"]' \
  https://my-app.janraincapture.com/entity.find

Example 2: Find users with a birthday

This command returns user profile information for all the users who have included their birthday in their user profile (that is, profiles where the birthday attribute isn't set to a null value).

curl -X POST \
  -H "Authorization: c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=" \
  --data-urlencode type_name=user \
  --data-urlencode filter="birthday is not null" \
  https://my-app.janraincapture.com/entity.find

Example 3: Find users who identify as male

This command returns information for all the users who have set their gender attribute to male.

curl -X POST \
  -H "Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=" \
  --data-urlencode type_name=user \
  --data-urlencode filter="gender='male'" \
  https://my-app.janraincapture.com/entity.find

Example 4: Adding more than one condition to a filter

This command returns the display name and email address for all users who have a gender attribute equal to male and were born on December 19, 1989.

curl -X POST \
  -H "Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=" \
  --data-urlencode type_name=user \
  --data-urlencode filter="gender='male' and birthday='12-19-1989'" \
  https://my-app.janraincapture.com/entity.find

Example 5: Retrieve data for specific attributes

This command returns two attributes (displayName and email) for all the users in the user entity type.

curl -X POST \
  -H "Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=" 
  --data-urlencode type_name=user \
  --data-urlencode attributes='["displayName", "email"]' \
  https://my-app.janraincapture.com/entity.find

Example response

If your API call succeeds you'll get back the requested user profile attributes for all the users meeting your search criteria:

{
  "result_count": 6,
  "stat": "ok",
  "results": [
    {
      "displayName": "ian",
      "email": "ian@example.com"
    },
    {
      "displayName": "Rex",
      "email": "rex@example.com"
    },
    {
      "displayName": "sam",
      "email": "smann@example.com"
    },
    {
      "displayName": "alex",
      "email": "alex@example.com"
    },
    {
      "displayName": "john.j",
      "email": "jj@example.com"
    },
    {
      "displayName": "daniel",
      "email": "daniel@example.com"
    }
  ]
}

Parameters

All parameters need to be configured as x-www-form-urlencoded body parameters.

Notes on sorting your search results

By default, results are sorted in ascending order. To sort in descending order, place a minus sign (-) directly in front of the appropriate attribute. For example:

-displayName

If the sort order isn't important it's recommended that you include the sort_on parameter and set the value to an empty array:

sort_on='[]'

Doing this typically improves the speed of an unsorted query.

Search results are sorted by using the ASCII (American Standard Code for Information Interchange) sort order. This means that:

1. Strings beginning with a control code or a special character are sorted first.
2. Strings beginning with a number are sorted second.
3. Strings beginning with an uppercase letter are sorted third.
4. Strings beginning with a lowercase letter are sorted fourth.

For example, suppose your search result returns the following items: aardvark; +llama; Orangutan; 7zebra. Those items would be sorted like this:

• +llama
• 7Zebra
• Orangutan
• aardvark