How to search for users not registered to a specific application?

FASupportBot

I need to identify users in FusionAuth who are not registered to a particular application. The User Search API supports querying for users with registrations, but how can I construct a query to find users that don't have a registration for a given application ID?

Specifically, I want to use the Elasticsearch query syntax to exclude users who have a registration matching a certain applicationId.

FASupportBot

You can use the User Search API with a must_not clause in the Elasticsearch query to exclude users registered to a specific application. Here's an example:

curl -X POST https://sandbox.fusionauth.io/api/user/search \
  -H 'Authorization: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "search": {
    "accurateTotal": true,
    "numberOfResults": 100,
    "startRow": 0,
    "query": "{\"bool\":{\"must_not\":[{\"nested\":{\"path\":\"registrations\",\"query\":{\"bool\":{\"must\":[{\"match\":{\"registrations.applicationId\":\"<your-application-id>\"}}]}}}}]}}"
  }
}'

Key points:

The must_not clause excludes users matching the nested query
The nested query targets the registrations path since registrations are nested objects in the Elasticsearch mapping
Inside the nested query, the must clause matches the specific applicationId
Replace <your-application-id> with the UUID of your target application
This returns users who either have no registrations at all, or have registrations to other applications but not the specified one

You can paginate through results using startRow and numberOfResults if you have a large user base.

Important: This approach requires the Elasticsearch search engine (not the database engine). You must use the search.query parameter with raw Elasticsearch JSON when querying against registrations, because it is defined as a nested datatype in the Elasticsearch mapping. The queryString parameter cannot be used for nested fields like registrations with expected results.

Tip: You can use the Admin UI → Users → Advanced → Show Elasticsearch Query toggle to build and test queries interactively before using them in the API.

How to search for users not registered to a specific application?

Related Documentation