User Search Best Practices

Here are some best practices for user search:

• You need a token to make requests to the Management API. To learn more, read Management API Access Tokens.

• To perform user search requests, the read:users scope is required.

• To get the latest search results, use an immediately consistent endpoint during authentication processes, such as Get Users by ID and Get Users by Email. Searches using these endpoints reflect the results of all successful write operations including those that occurred shortly prior to your request.

• Use a well-known schema for metadata:

  • Use consistent data types for properties.

  • Avoid dynamic property names.

  • Avoid large schema sizes and deep structures.

  • Avoid storing data you do not need for authentication and authorization purposes.

• Search queries time out (HTTP status code 503) if they're not completed in two seconds or less. Queries that take longer indicate that it's either an expensive query or that the query has an error resulting in it not completing quickly

• Don't use a search criteria that returns a large data set (more than 1000 results).

• Don't use existence queries (for example, "give me all users with a property regardless of its value").

• Don't poll the search APIs.

• Don't use large metadata fields (try to keep metadata fields to 2 KB or less).

• Using wildcard on searches can affect performance. In some cases, wildcard searches on large data sets can result in time out errors. We also recommend avoiding wildcards prefixed to the search term, while using them as suffixes yields better performance.

• Escape the space character to improve performance (e.g., q=name:John Doe should be written as q=name:John\ Doe).