> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt) # Bulk Delete Users API documentation for the FusionAuth Bulk Delete Users API. # Bulk Delete Users This API is used to deactivate or delete multiple users in a single request. note 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 [!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication) Deactivate Users by User Id DELETE/api/user/bulk?userId={userId}&userId={userId} OpenAPI Spec [!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication) Permanently Delete Users by User Id DELETE/api/user/bulk?userId={userId}&userId={userId}&hardDelete=true OpenAPI Spec [!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication) Deactivate Users by Search Query String DELETE/api/user/bulk?queryString={queryString}&dryRun=false&limit=10000 OpenAPI Spec [!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication) Permanently Delete Users by Search Query String DELETE/api/user/bulk?queryString={queryString}&hardDelete=true&dryRun=false&limit=10000 OpenAPI Spec [!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication) Deactivate Users by Raw JSON Search Query DELETE/api/user/bulk?query={query}&dryRun=false&limit=10000 OpenAPI Spec [!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication) Permanently Delete Users by Raw JSON Search Query DELETE/api/user/bulk?query={query}&hardDelete=true&dryRun=false&limit=10000 OpenAPI Spec ### Request Parameters `dryRun`BooleanoptionalDefaults to false To preview the user Ids to be deleted by the request without applying the requested action set this value to `true`. `hardDelete`BooleanoptionalDefaults 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. `limit`IntegeroptionalDefaults 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. `query`StringoptionalAvailable 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](https://www.elastic.co/guide/en/elasticsearch/reference/6.3/nested.html) in the Elasticsearch mapping. Database search engine This parameter is not compatible with the database search engine, it may only be used when Elasticsearch is configured as the user search engine. `queryString`StringoptionalAvailable 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. caution FusionAuth adds wildcards to unscoped `queryString`s 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. Database search engine 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` `userId`UUIDoptional 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-TenantId`Stringoptional 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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information. ### Using request body [!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication) 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-TenantId`Stringoptional 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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information. #### Request Body `dryRun`BooleanoptionalDefaults to false To preview the user Ids to be deleted by the request without applying the requested action set this value to `true`. `hardDelete`BooleanoptionalDefaults 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. `limit`IntegeroptionalDefaults 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. `query`StringoptionalAvailable 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](https://www.elastic.co/guide/en/elasticsearch/reference/6.3/nested.html) in the Elasticsearch mapping. Database search engine This parameter is not compatible with the database search engine, it may only be used when Elasticsearch is configured as the user search engine. `queryString`StringoptionalAvailable 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. caution FusionAuth adds wildcards to unscoped `queryString`s 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. Database search engine 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` `userIds`Arrayoptional 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* ```json { "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* ```json { "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* ```json { "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* ```json { "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* ```json { "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* ```json { "dryRun": true, "hardDelete": true, "queryString": "email:*@fusionauth.io" } ``` *Example Request JSON searching by queryString for users belonging to a specific group with a limit* ```json { "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* ```json { "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](https://fusionauth.io/docs/apis/errors.md) 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](https://fusionauth.io/docs/apis/authentication.md). | | 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 `dryRun`Boolean Whether the request was a dry run or the requested action was applied. `hardDelete`Boolean Whether the requested action was deactivation or permanent deletion. `total`Integer The count of affected Users. `userIds`Array The list of affected User Ids. This field is omitted from the response when no users were affected by the request. *Example Response JSON* ```json { "dryRun": true, "hardDelete": true, "total": 2, "userIds": [ "00000000-0000-0001-0000-000000000000", "00000000-0000-0001-0000-000000000001" ] } ```