Docs

User Search Best Practices

When running user searches:

  • You'll need a token to make requests to the Management API. Check out Access Tokens for the Management API for more information.
  • 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 will 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.
  • Don't use existence queries (for example, "give me all users with a property regardless of its value").
  • Don't use full text search or partial searches.
  • Don't poll the search APIs.
  • Don't use large metadata fields (try to keep metadata fields to 2 KB or less).
  • If you are using user search engine v2, check out the section on migrating from v2 to v3.

The user search engine v3 is not available in Management API v1, which is deprecated. If you are using the Management API v1, you will need to upgrade to Management API v2 before being able to use the user search engine v3. See Management API v1 vs v2 for more information.