Bulk Delete Users

This API is used to deactivate or delete multiple users in a single request.

This API has some limitations when FusionAuth is configured to use the database as the user search engine. These limitations are noted on the impacted request parameters below.

Request#

Deactivate Users by User Id

DELETE/api/user/bulk?userId={userId}&userId={userId}

OpenAPI Spec

Permanently Delete Users by User Id

DELETE/api/user/bulk?userId={userId}&userId={userId}&hardDelete=true

OpenAPI Spec

Deactivate Users by Search Query String

DELETE/api/user/bulk?queryString={queryString}&dryRun=false&limit=10000

OpenAPI Spec

Permanently Delete Users by Search Query String

DELETE/api/user/bulk?queryString={queryString}&hardDelete=true&dryRun=false&limit=10000

OpenAPI Spec

Deactivate Users by Raw JSON Search Query

DELETE/api/user/bulk?query={query}&dryRun=false&limit=10000

OpenAPI Spec

Permanently Delete Users by Raw JSON Search Query

DELETE/api/user/bulk?query={query}&hardDelete=true&dryRun=false&limit=10000

OpenAPI Spec

Request Parameters#

dryRunBooleanoptionalDefaults to false

To preview the user Ids to be deleted by the request without applying the requested action set this value to true.

hardDeleteBooleanoptionalDefaults to false

To Permanently delete a user from FusionAuth set this value to true. Once a user has been permanently deleted, the action cannot be undone. When this value is set to false the user is marked as inactive and the user will be unable log into FusionAuth. This action may be undone by reactivating the user.

limitIntegeroptionalDefaults to 10,000Available since 1.48.0

The maximum number of users to delete in one call.

You may use this parameter to process deletes in batches in order to limit individual request processing time and the number of user Ids on the response.

queryStringoptionalAvailable since 1.13.0

The raw JSON Elasticsearch query that is used to search for Users. The userId, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

It is necessary to use the query parameter when querying against registrations in order to achieve expected results, as this field is defined as a nested datatype in the Elasticsearch mapping.

This parameter is not compatible with the database search engine, it may only be used when Elasticsearch is configured as the user search engine.

queryStringStringoptionalAvailable since 1.13.0

The Elasticsearch query string that is used to search for Users to be deleted. The userId, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

FusionAuth adds wildcards to unscoped queryStrings in order to match the broadest set of results. Depending on the specifics of the system, a leading wildcard on a search term can significantly reduce search performance. In order to improve search performance, limit the search to a single field by specifying it in the queryString followed by a : to prevent the pre-processing by FusionAuth.

The Elasticsearch query string DSL is not supported for the database search engine. Database search limits effective queries to single search terms that may match the following fields on the User:

firstName
lastName
fullName
email
username

The following is an example bulk delete request with a queryString value that is compatible with the database search engine:

DELETE /api/user/bulk?queryString=jared%40fusionauth.io

userIdUUIDoptional

The Id of the User to delete. Repeat this parameter for each user to be deleted. The userId, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

Request Headers#

X-FusionAuth-TenantIdStringoptional

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Using request body#

Bulk delete using the request body. This allows for larger requests than are possible using request parameters.

DELETE/api/user/bulk

OpenAPI Spec

Request Headers#

X-FusionAuth-TenantIdStringoptional

The unique Id of the tenant used to scope this API request.

See Making an API request using a Tenant Id for additional information.

Request Body#

dryRunBooleanoptionalDefaults to false

To preview the user Ids to be deleted by the request without applying the requested action set this value to true.

hardDeleteBooleanoptionalDefaults to false

limitIntegeroptionalDefaults to 10,000Available since 1.48.0

The maximum number of users to delete in one call.

You may use this parameter to process deletes in batches in order to limit individual request processing time and the number of user Ids on the response.

queryStringoptionalAvailable since 1.13.0

The raw JSON Elasticsearch query that is used to search for Users. The userIds, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

It is necessary to use the query parameter when querying against registrations in order to achieve expected results, as this field is defined as a nested datatype in the Elasticsearch mapping.

This parameter is not compatible with the database search engine, it may only be used when Elasticsearch is configured as the user search engine.

queryStringStringoptionalAvailable since 1.13.0

The Elasticsearch query string that is used to search for Users to be deleted. The userIds, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

The Elasticsearch query string DSL is not supported for the database search engine. Database search limits effective queries to single search terms that may match the following fields on the User:

firstName
lastName
fullName
email
username

The following is an example bulk delete request with a queryString value that is compatible with the database search engine:

DELETE /api/user/bulk?queryString=jared%40fusionauth.io

userIdsArrayoptional

An array of User Ids to delete. The userIds, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

Example Request JSON searching by userIds

{
  "dryRun": true,
  "hardDelete": true,
  "userIds": [
    "5c1dc1a8-2fc8-4ae0-9372-e994be0f4341",
    "dbf59ee1-2d24-4ea0-b977-2b6e2a5350bf",
    "3e74294d-7de7-45a4-9592-4a198ddbdc73",
    "cfaf34a0-aa66-4d3a-af14-6dbc5f9fb577",
    "a2eb9268-e6f1-45f4-8eaa-50c0154983fe",
    "b1b42d6b-3b44-47fb-bb32-26e0c71c62d3",
    "8c91cb08-27df-4725-b3a8-98631bc8d9af",
    "54df878b-c0a1-4951-a63a-3cf2f97edd17",
    "946b3deb-25a5-4155-b137-bb5202d2ac98"
  ]
}

Example JSON for the query parameter to search for users with unverified registrations to a specific application

{
  "bool": {
    "must": [
      {
        "nested": {
          "path": "registrations",
          "query": {
            "bool": {
              "must": [
                {
                  "match": {
                    "registrations.applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32"
                  }
                },
                {
                  "match": {
                    "registrations.verified": false
                  }
                }
              ]
            }
          }
        }
      }
    ]
  }
}

Example JSON searching by query for users with unverified registrations to a specific application

{
  "dryRun": true,
  "hardDelete": true,
  "query": "{\"bool\":{\"must\":[{\"nested\":{\"path\":\"registrations\",\"query\":{\"bool\":{\"must\":[{\"match\":{\"registrations.applicationId\":\"3c219e58-ed0e-4b18-ad48-f4f92793ae32\"}},{\"match\":{\"registrations.verified\":false}}]}}}}]}}"
}

Example JSON for the query parameter to search for users with a specific role

{
  "bool": {
    "must": [
      [
        {
          "nested": {
            "path": "registrations",
            "query": {
              "bool": {
                "must": [
                  {
                    "match": {
                      "registrations.applicationId": "c50329fa-93e5-4618-8d9f-73d0ab069a54"
                    }
                  },
                  {
                    "match": {
                      "registrations.roles": "admin"
                    }
                  }
                ]
              }
            }
          }
        }
      ]
    ]
  }
}

Example JSON searching by query for users with with a specific role

{
  "dryRun": true,
  "hardDelete": true,
  "query": "{\"bool\":{\"must\":[[{\"nested\":{\"path\":\"registrations\",\"query\":{\"bool\":{\"must\":[{\"match\":{\"registrations.applicationId\":\"c50329fa-93e5-4618-8d9f-73d0ab069a54\"}},{\"match\":{\"registrations.roles\":\"admin\"}}]}}}}]]}}"
}

Example Request JSON searching by queryString for users with an email address matching a pattern

{
  "dryRun": true,
  "hardDelete": true,
  "queryString": "email:*@fusionauth.io"
}

Example Request JSON searching by queryString for users belonging to a specific group with a limit

{
  "dryRun": true,
  "hardDelete": true,
  "limit": 10000,
  "queryString": "memberships.groupId:7f318a9d-3de4-4ded-9b53-1d97fd730868"
}

Example Request JSON searching by queryString for users of a specific tenant. A global API key must be used, and you may not use the X-FusionAuth-TenantId header when the search parameters include tenantId

{
  "dryRun": true,
  "hardDelete": true,
  "queryString": "tenantId:39666465-6535-3731-3139-666363356438"
}

Response#

The response for this API contains the information for the Users that were affected by the request.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you requested doesn't exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.
504	One or more Webhook endpoints returned an invalid response or were unreachable. Based on the transaction configuration for this event your action cannot be completed. A stack trace is provided and logged in the FusionAuth log files.

Response Body#

dryRunBoolean

Whether the request was a dry run or the requested action was applied.

hardDeleteBoolean

Whether the requested action was deactivation or permanent deletion.

totalInteger

The count of affected Users.

userIdsArray<UUID>

The list of affected User Ids. This field is omitted from the response when no users were affected by the request.

Example Response JSON

{
  "dryRun": true,
  "hardDelete": true,
  "total": 2,
  "userIds": [
    "00000000-0000-0001-0000-000000000000",
    "00000000-0000-0001-0000-000000000001"
  ]
}