> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt)

# Entity API

Learn about the APIs for creating, retrieving, updating and deleting entities, as well as searching them.

This feature is only available in paid plans. To learn more, see [our pricing page](https://fusionauth.io/pricing.md).

This page contains the APIs for managing Entities as well as searching them. [Entity core concepts](https://fusionauth.io/docs/get-started/core-concepts/entity-management.md) may also be helpful.

> **VERSION:** Available since version `1.26.0`

## Create an Entity

This API is used to create an Entity. Specifying an Id on the URI will instruct FusionAuth to use that Id when creating the Entity. Otherwise, FusionAuth will generate an Id for the Entity.

### Request

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Create an Entity without providing an Id. An Id will be automatically generated.

`POST /api/entity`

#### Request Headers

`X-FusionAuth-TenantId`

*   String
*   optional

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

When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request. 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.

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Create an Entity with the provided Id

`POST /api/entity/{entityId}`

#### Request Parameters

`entityId`

*   UUID
*   optional
*   Defaults to secure random UUID

The Id to use for the new Entity. If not specified a secure random UUID will be generated.

#### Request Body

`entity.data`

*   Object
*   optional

An object that can hold any information about the Entity that should be persisted. Please review the [limits on data field types](https://fusionauth.io/docs/get-started/core-concepts/limitations.md#data-type-changes-in-data-fields) as you plan for and build your custom data schema.

`entity.clientId`

*   String
*   optional

The OAuth 2.0 client Id. If you leave this blank during a POST, the value of the Entity Id will be used.

`entity.clientSecret`

*   String
*   optional

The OAuth 2.0 client secret. If you leave this blank during a POST, a secure secret will be generated for you. If you leave this blank during PUT, the previous value will be maintained. For both POST and PUT you can provide a value and it will be stored.

`entity.name`

*   String
*   required

A descriptive name for the Entity (i.e. "Raviga" or "Email Service").

`entity.type.id`

*   UUID
*   required

The Id of the Entity Type. Types are consulted for permission checks.

*Example Request JSON*

```json
{
  "entity": {
    "clientId": "092dbded-30af-4149-9c61-b578f2c72f59",
    "clientSecret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
    "data": {
      "companyType": "Legal"
    },
    "type": {
      "id": "092dbded-30af-4149-9c61-b578f2c72f57"
    },
    "name": "Raviga"
  }
}
```

#### Request Headers

`X-FusionAuth-TenantId`

*   String
*   optional

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

When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request. 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.

### Response

The response for this API contains the information for the Entity that was created.

*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). |
| 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. |

#### Response Body

`entity.data`

*   Object

An object that can hold any information about the Entity that should be persisted. Please review the [limits on data field types](https://fusionauth.io/docs/get-started/core-concepts/limitations.md#data-type-changes-in-data-fields) as you plan for and build your custom data schema.

`entity.clientId`

*   String

The OAuth 2.0 client Id.

`entity.clientSecret`

*   String

The OAuth 2.0 client secret.

`entity.id`

*   UUID

The unique Id of the Entity.

`entity.insertInstant`

*   Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Entity was added to the FusionAuth database.

`entity.lastUpdateInstant`

*   Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Entity was last updated in the FusionAuth database.

`entity.name`

*   String

A descriptive name for the Entity (i.e. "Raviga" or "Email Service").

`entity.tenantId`

*   UUID

The Id of the Tenant to which this Entity belongs.

`entity.type`

*   Object

The Entity Type of this Entity. Consult the [Entity Type documentation](https://fusionauth.io/docs/apis/entities/entity-types.md) for more details about the fields of this object.

*Example Response JSON for an Entity*

```json
{
  "entity": {
    "clientId": "092dbded-30af-4149-9c61-b578f2c72f59",
    "clientSecret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
    "data": {
      "companyType": "Legal"
    },
    "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
    "insertInstant": 1595361142909,
    "lastUpdateInstant": 1595361143101,
    "name": "Raviga",
    "tenantId": "30663132-6464-6665-3032-326466613934",
    "type": {
      "id": "4838d96a-4e7b-42c6-a4a1-ebc64952e1c8",
      "insertInstant": 1518962408732,
      "jwtConfiguration": {
        "enabled": false,
        "timeToLiveInSeconds": 60
      },
      "lastUpdateInstant": 1518962408732,
      "name": "Customers"
    }
  }
}
```

## Retrieve an Entity

This API is used to retrieve one Entity.

### Request

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Retrieve a single Entity by Id

`GET /api/entity/{entityId}`

#### Request Parameters

`entityId`

*   UUID
*   required

The Id of the Entity to retrieve.

#### Request Headers

`X-FusionAuth-TenantId`

*   String
*   optional

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.

### Response

The response for this API contains a single Entity.

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. The response will contain a JSON body. |
| 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. |

#### Response Body

`entity.data`

*   Object

An object that can hold any information about the Entity that should be persisted. Please review the [limits on data field types](https://fusionauth.io/docs/get-started/core-concepts/limitations.md#data-type-changes-in-data-fields) as you plan for and build your custom data schema.

`entity.clientId`

*   String

The OAuth 2.0 client Id.

`entity.clientSecret`

*   String

The OAuth 2.0 client secret.

`entity.id`

*   UUID

The unique Id of the Entity.

`entity.insertInstant`

*   Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Entity was added to the FusionAuth database.

`entity.lastUpdateInstant`

*   Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Entity was last updated in the FusionAuth database.

`entity.name`

*   String

A descriptive name for the Entity (i.e. "Raviga" or "Email Service").

`entity.tenantId`

*   UUID

The Id of the Tenant to which this Entity belongs.

`entity.type`

*   Object

The Entity Type of this Entity. Consult the [Entity Type documentation](https://fusionauth.io/docs/apis/entities/entity-types.md) for more details about the fields of this object.

*Example Response JSON for an Entity*

```json
{
  "entity": {
    "clientId": "092dbded-30af-4149-9c61-b578f2c72f59",
    "clientSecret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
    "data": {
      "companyType": "Legal"
    },
    "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
    "insertInstant": 1595361142909,
    "lastUpdateInstant": 1595361143101,
    "name": "Raviga",
    "tenantId": "30663132-6464-6665-3032-326466613934",
    "type": {
      "id": "4838d96a-4e7b-42c6-a4a1-ebc64952e1c8",
      "insertInstant": 1518962408732,
      "jwtConfiguration": {
        "enabled": false,
        "timeToLiveInSeconds": 60
      },
      "lastUpdateInstant": 1518962408732,
      "name": "Customers"
    }
  }
}
```

## Update an Entity

This API is used to update an existing Entity.

You must specify all of the properties of the Entity when calling this API with the `PUT` HTTP method. When used with `PUT`, this API doesn't merge the existing Entity and your new data. It replaces the existing Entity with your new data.

Utilize the `PATCH` HTTP method to send specific changes to merge into an existing Entity.

### Request

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Update an Entity by Id

`PUT /api/entity/{entityId}`

`PATCH /api/entity/{entityId}`

> **NOTE:** For backward compatibility, the `PATCH` method accepts the same media type (specified by a `Content-Type` of `application/json`) and body as the `PUT` request. You can also use the following media types for different behavior:
> 
> *   [JSON Patch/RFC 6902](https://www.rfc-editor.org/rfc/rfc6902): `application/json-patch+json`
> *   [JSON Merge Patch/RFC 7396](https://www.rfc-editor.org/rfc/rfc7396): `merge-patch+json`
> 
> For details, see the [PATCH documentation](https://fusionauth.io/docs/apis.md#the-patch-http-method).
> 
> Using a media type of `application/json` merges the provided request parameters into the existing object. As a result, all parameters are optional with `PATCH`: only provide the values you want to change. To remove a value, provide a `null` value. Patching an `Array` appends all values in the new list to the old list.

#### Request Parameters

`entityId`

*   UUID
*   required

The Id of the Entity to update.

#### Request Headers

`X-FusionAuth-TenantId`

*   String
*   optional

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

`entity.data`

*   Object
*   optional

An object that can hold any information about the Entity that should be persisted. Please review the [limits on data field types](https://fusionauth.io/docs/get-started/core-concepts/limitations.md#data-type-changes-in-data-fields) as you plan for and build your custom data schema.

`entity.clientId`

*   String
*   optional

The OAuth 2.0 client Id. If you leave this blank during a POST, the value of the Entity Id will be used.

`entity.clientSecret`

*   String
*   optional

The OAuth 2.0 client secret. If you leave this blank during a POST, a secure secret will be generated for you. If you leave this blank during PUT, the previous value will be maintained. For both POST and PUT you can provide a value and it will be stored.

`entity.name`

*   String
*   required

A descriptive name for the Entity (i.e. "Raviga" or "Email Service").

`entity.type.id`

*   UUID
*   required

The Id of the Entity Type. Types are consulted for permission checks.

*Example Request JSON*

```json
{
  "entity": {
    "clientId": "092dbded-30af-4149-9c61-b578f2c72f59",
    "clientSecret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
    "data": {
      "companyType": "Legal"
    },
    "type": {
      "id": "092dbded-30af-4149-9c61-b578f2c72f57"
    },
    "name": "Raviga"
  }
}
```

### Response

The response for this API contains the new information for the Entity that was updated.

*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 are trying to update 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. |

#### Response Body

`entity.data`

*   Object

An object that can hold any information about the Entity that should be persisted. Please review the [limits on data field types](https://fusionauth.io/docs/get-started/core-concepts/limitations.md#data-type-changes-in-data-fields) as you plan for and build your custom data schema.

`entity.clientId`

*   String

The OAuth 2.0 client Id.

`entity.clientSecret`

*   String

The OAuth 2.0 client secret.

`entity.id`

*   UUID

The unique Id of the Entity.

`entity.insertInstant`

*   Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Entity was added to the FusionAuth database.

`entity.lastUpdateInstant`

*   Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Entity was last updated in the FusionAuth database.

`entity.name`

*   String

A descriptive name for the Entity (i.e. "Raviga" or "Email Service").

`entity.tenantId`

*   UUID

The Id of the Tenant to which this Entity belongs.

`entity.type`

*   Object

The Entity Type of this Entity. Consult the [Entity Type documentation](https://fusionauth.io/docs/apis/entities/entity-types.md) for more details about the fields of this object.

*Example Response JSON for an Entity*

```json
{
  "entity": {
    "clientId": "092dbded-30af-4149-9c61-b578f2c72f59",
    "clientSecret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
    "data": {
      "companyType": "Legal"
    },
    "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
    "insertInstant": 1595361142909,
    "lastUpdateInstant": 1595361143101,
    "name": "Raviga",
    "tenantId": "30663132-6464-6665-3032-326466613934",
    "type": {
      "id": "4838d96a-4e7b-42c6-a4a1-ebc64952e1c8",
      "insertInstant": 1518962408732,
      "jwtConfiguration": {
        "enabled": false,
        "timeToLiveInSeconds": 60
      },
      "lastUpdateInstant": 1518962408732,
      "name": "Customers"
    }
  }
}
```

## Delete an Entity

This API is used to delete an Entity. You must specify the Id of the Entity on the URI.

### Request

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Delete an Entity By Id

`DELETE /api/entity/{entityId}`

#### Request Parameters

`entityId`

*   UUID
*   required

The Id of the Entity to delete.

#### Request Headers

`X-FusionAuth-TenantId`

*   String
*   optional

The unique Id of the tenant used to scope this API request. The tenant Id is not required on this request when only one tenant has been configured. If there is more than one tenant, the tenant Id is required.

Supply the tenant Id via this header or by using an API Key scoped to a tenant, which implicitly supplies the tenant Id.

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.

### Response

This API does not return a JSON response body.

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. |
| 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. |

## Search for Entities

This API is used to search for Entities. This API may be called using the `GET` or `POST` HTTP methods. Examples of each are provided below. The `POST` method is provided to allow for a richer request object without worrying about exceeding the maximum length of a URL. Calling this API with either the `GET` or `POST` HTTP method will provide the same search results given the same query parameters.

### Request

Which search query parameters are available and how they behave depends on the search engine type. Read more about [the different types of search engines](https://fusionauth.io/docs/lifecycle/manage-users/search.md).

### Database Search Engine

This is a good choice for [smaller installs, embedded scenarios, or other places where the additional capability of Elasticsearch is not required](https://fusionauth.io/docs/lifecycle/manage-users/search.md).

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Search for Entities by Id

`GET /api/entity/search?ids={uuid}&ids={uuid}?ids={uuid}&ids={uuid}`

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Search for Entities by a query string

`GET /api/entity/search?queryString={queryString}?queryString={queryString}`

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Search for Entities by a query string and sort the response

`GET /api/entity/search?queryString={queryString}&sortFields[0].name={name}&sortFields[0].order={order}?queryString={queryString}&sortFields[0].name={name}&sortFields[0].order={order}`

#### Request Parameters

`accurateTotal`

*   Boolean
*   optional
*   Defaults to false

Set this value equal to `true` to receive an accurate hit count on the API response.

By default the search engine will limit the hit count to 10,000 entities. This means that even if your query may match more than 10,000 entities, the returned total count will be 10,000. This is adequate for many use cases such as pagination and general purpose queries. If you are looking for an accurate entity count that can exceed 10,000 matches, you will want to set this value equal to `true`.

`ids`

*   UUID
*   optional

An Entity Id to retrieve. By specifying this URL parameter multiple times you can lookup multiple Entities.

Using this parameter is mutually exclusive with the **queryString** field and is not paginated or sorted using the **sortFields** field.

`numberOfResults`

*   Boolean
*   optional
*   Defaults to 25

The number of search results to return. Used for pagination.

`queryString`

*   String
*   optional

A query string that is used to search for Entities. Using this parameter is mutually exclusive with the **ids** field.

Database search limits effective queries to single search terms that may match the following fields on the Entities or their Entity Type:

*   `clientId`
*   `name`
*   `entityType.name`

The search matches against all of these fields and any entity with a matching field will be returned. The match is case-insensitive, and you may not search by prefix or suffix. Whitespace is not allowed in the search. Regular expressions may not be used. A value of `*` will match all records.

`startRow`

*   Integer
*   optional
*   Defaults to 0

The start row within the search results to return. Used for pagination.

`sortFields`

*   Array
*   optional

An array of sort fields used to sort the result. The order the sort fields are provided will be maintained in the sorted output.

`sortFields[x].name`

*   String
*   optional

The name of the field to sort.

Required if **sortFields** is provided.

The following field names are supported for the database search engine:

*   `clientId`
*   `insertInstant`
*   `lastUpdateInstant`
*   `name`
*   `tenantId`
*   `typeId`

`sortFields[x].order`

*   String
*   optional
*   Defaults to asc

The order to sort the specified field. Possible values are:

*   `asc`
*   `desc`

#### Request Headers

`X-FusionAuth-TenantId`

*   String
*   optional

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.

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Search for Entities using a JSON request body. This allows for larger requests than are possible using request parameters.

`POST /api/entity/search`

#### Request Headers

`X-FusionAuth-TenantId`

*   String
*   optional

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

`search.accurateTotal`

*   Boolean
*   optional
*   Defaults to false

Set this value equal to `true` to receive an accurate hit count on the API response.

By default the search engine will limit the hit count to 10,000 entities. This means that even if your query may match more than 10,000 entities, the returned total count will be 10,000. This is adequate for many use cases such as pagination and general purpose queries. If you are looking for an accurate entity count that can exceed 10,000 matches, you will want to set this value equal to `true`.

`search.ids`

*   UUID
*   optional

An Entity Id to retrieve. By specifying this URL parameter multiple times you can lookup multiple Entities.

Using this parameter is mutually exclusive with the **queryString** field and is not paginated or sorted using the **sortFields** field.

`search.numberOfResults`

*   Boolean
*   optional
*   Defaults to 25

The number of search results to return. Used for pagination.

`search.queryString`

*   String
*   optional

A query string that is used to search for Entities. Using this parameter is mutually exclusive with the **ids** field.

Database search limits effective queries to single search terms that may match the following fields on the Entities or their Entity Type:

*   `clientId`
*   `name`
*   `entityType.name`

The search matches against all of these fields and any entity with a matching field will be returned. The match is case-insensitive, and you may not search by prefix or suffix. Whitespace is not allowed in the search. Regular expressions may not be used. A value of `*` will match all records.

`search.startRow`

*   Integer
*   optional
*   Defaults to 0

The start row within the search results to return. Used for pagination.

`search.sortFields`

*   Array
*   optional

An array of sort fields used to sort the result. The order the sort fields are provided will be maintained in the sorted output.

`search.sortFields[x].name`

*   String
*   optional

The name of the field to sort.

Required if **sortFields** is provided.

The following field names are supported for the database search engine:

*   `clientId`
*   `insertInstant`
*   `lastUpdateInstant`
*   `name`
*   `tenantId`
*   `typeId`

`search.sortFields[x].order`

*   String
*   optional
*   Defaults to asc

The order to sort the specified field. Possible values are:

*   `asc`
*   `desc`

##### Request Body Examples

*Example Request JSON searching by ids*

```json
{
  "search": {
    "ids": [
      "a6e3ed2d-582b-4ec3-aa3f-4323c8f39fe9",
      "00000000-0000-0001-0000-000000000000"
    ]
  }
}
```

*Example Request JSON searching by queryString for entities with a matching name*

```json
{
  "search": {
    "numberOfResults": 25,
    "queryString": "api",
    "sortFields": [
      {
        "name": "name",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}
```

*Example Request JSON searching by queryString for entities with a clientId, name or type name containing piper.*

```json
{
  "search": {
    "numberOfResults": 25,
    "queryString": "piper",
    "sortFields": [
      {
        "name": "name",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}
```

*Example Request JSON to retrieve the first 50 entities, ordered by name, ascending.*

```json
{
  "search": {
    "numberOfResults": 25,
    "queryString": "*",
    "sortFields": [
      {
        "name": "name",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}
```

### Elasticsearch Search Engine

The Elasticsearch engine has [advanced querying capabilities and better performance](https://fusionauth.io/docs/lifecycle/manage-users/search.md).

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Search for Entities by Id

`GET /api/entity/search?ids={uuid}&ids={uuid}?ids={uuid}&ids={uuid}`

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Search for Entities by a query string

`GET /api/entity/search?queryString={queryString}?queryString={queryString}`

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Search for Entities by a query string and sort the response

`GET /api/entity/search?queryString={queryString}&sortFields[0].name={name}&sortFields[0].order={order}?queryString={queryString}&sortFields[0].name={name}&sortFields[0].order={order}`

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Search for Entities by a raw JSON query

`GET /api/entity/search?query={query}?query={query}`

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Search for Entities by a nextResults token

`GET /api/entity/search?nextResults={nextResults}?nextResults={nextResults}`

#### Request Parameters

`accurateTotal`

*   Boolean
*   optional
*   Defaults to false

Set this value equal to `true` to receive an accurate hit count on the API response.

By default the search engine will limit the hit count to 10,000 entities. This means that even if your query may match more than 10,000 entities, the returned total count will be 10,000. This is adequate for many use cases such as pagination and general purpose queries. If you are looking for an accurate entity count that can exceed 10,000 matches, you will want to set this value equal to `true`.

`ids`

*   UUID
*   optional

An Entity Id to retrieve. By specifying this URL parameter multiple times you can lookup multiple Entities.

Using this parameter is mutually exclusive with the **query** and **queryString** fields and is not paginated or sorted using **sortFields** field. Using this parameter will not hit the Elasticsearch index, instead it will cause entities to be retrieved by Id only.

`nextResults`

*   String
*   optional
*   Available since 1.48.0

The encoded token returned in the **nextResults** of a previous search response. Providing this token will return a result set for the page following the last result from the previous search response.

This parameter can be used to successfully page past the `max_result_window` limitation.

This parameter cannot be used with the **ids**, **query**, **queryString**, or **sortFields** parameters. The **startRow** parameter must be 0 or omitted.

See [Extended Pagination](https://fusionauth.io/docs/lifecycle/manage-users/search.md#extended-pagination) for more information.

`numberOfResults`

*   Boolean
*   optional
*   Defaults to 25

The number of search results to return. Used for pagination.

`query`

*   String
*   optional

The raw JSON Elasticsearch query that is used to search for Entities. The **ids**, **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 **grants** 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.

`queryString`

*   String
*   optional

The Elasticsearch query string that is used to search for Entities. The **ids**, **query**, and **queryString** parameters are mutually exclusive, they are listed here in order of precedence.

The match is case-insensitive. Whitespace is allowed in the search, but must be URL escaped; for example, using `%20` for a space character. Elasticsearch compatible regular expressions may be used, so you may search by prefix or suffix using the `*` wildcard.

You may search against specific fields like so: `name:*API`. This will match only entities with a name ending in a `API`. Here are [the available fields for matching](https://fusionauth.io/docs/reference/entity-fields.md).

> **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.

`startRow`

*   Integer
*   optional
*   Defaults to 0

The start row within the search results to return. Used for pagination.

`sortFields`

*   Array
*   optional

An array of sort fields used to sort the result. The order the sort fields are provided will be maintained in the sorted output.

`sortFields[x].missing`

*   String
*   optional
*   Defaults to \_last

The value to substitute if this field is not defined. Two special values may be used:

*   `_first` When the field is not defined sort this record first.
*   `_last` When the field is not defined sort this record last.

`sortFields[x].name`

*   String
*   optional

The name of the field to sort.

Required if **sortFields** is provided.

Due to how the search index is structured not all fields on the entity are sortable. The following field names are currently supported.

*   `clientId`
*   `insertInstant`
*   `lastUpdateInstant`
*   `name`
*   `tenantId`
*   `typeId`

`sortFields[x].order`

*   String
*   optional
*   Defaults to asc

The order to sort the specified field. Possible values are:

*   `asc`
*   `desc`

#### Request Headers

`X-FusionAuth-TenantId`

*   String
*   optional

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.

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Search for Entities using a JSON request body. This allows for larger requests than are possible using request parameters.

`POST /api/entity/search`

#### Request Headers

`X-FusionAuth-TenantId`

*   String
*   optional

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

`search.accurateTotal`

*   Boolean
*   optional
*   Defaults to false

Set this value equal to `true` to receive an accurate hit count on the API response.

By default the search engine will limit the hit count to 10,000 entities. This means that even if your query may match more than 10,000 entities, the returned total count will be 10,000. This is adequate for many use cases such as pagination and general purpose queries. If you are looking for an accurate entity count that can exceed 10,000 matches, you will want to set this value equal to `true`.

`search.ids`

*   UUID
*   optional

An Entity Id to retrieve. By specifying this URL parameter multiple times you can lookup multiple Entities.

Using this parameter is mutually exclusive with the **query** and **queryString** fields and is not paginated or sorted using **sortFields** field. Using this parameter will not hit the Elasticsearch index, instead it will cause entities to be retrieved by Id only.

`nextResults`

*   String
*   optional
*   Available since 1.48.0

The encoded token returned in the **nextResults** of a previous search response. Providing this token will return a result set for the page following the last result from the previous search response.

This parameter can be used to successfully page past the `max_result_window` limitation.

This parameter cannot be used with the **ids**, **query**, **queryString**, or **sortFields** parameters. The **startRow** parameter must be 0 or omitted.

See [Extended Pagination](https://fusionauth.io/docs/lifecycle/manage-users/search.md#extended-pagination) for more information.

`search.numberOfResults`

*   Boolean
*   optional
*   Defaults to 25

The number of search results to return. Used for pagination.

`search.query`

*   String
*   optional

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

It is necessary to use the **search.query** parameter when querying against **grants** 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.

`search.queryString`

*   String
*   optional

The Elasticsearch query string that is used to search for Entities. The **ids**, **query**, and **queryString** parameters are mutually exclusive, they are listed here in order of precedence.

The match is case-insensitive. Whitespace is allowed in the search, but must be URL escaped; for example, using `%20` for a space character. Elasticsearch compatible regular expressions may be used, so you may search by prefix or suffix using the `*` wildcard.

You may search against specific fields like so: `name:*API`. This will match only entities with a name ending in a `API`. Here are [the available fields for matching](https://fusionauth.io/docs/reference/entity-fields.md).

> **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.

`search.startRow`

*   Integer
*   optional
*   Defaults to 0

The start row within the search results to return. Used for pagination.

`search.sortFields`

*   Array
*   optional

An array of sort fields used to sort the result. The order the sort fields are provided will be maintained in the sorted output.

`search.sortFields[x].missing`

*   String
*   optional
*   Defaults to \_last

The value to substitute if this field is not defined. Two special values may be used:

*   `_first` When the field is not defined sort this record first.
*   `_last` When the field is not defined sort this record last.

`search.sortFields[x].name`

*   String
*   optional

The name of the field to sort.

Required if **sortFields** is provided.

Due to how the search index is structured not all fields on the entity are sortable. The following field names are currently supported.

*   `clientId`
*   `insertInstant`
*   `lastUpdateInstant`
*   `name`
*   `tenantId`
*   `typeId`

`search.sortFields[x].order`

*   String
*   optional
*   Defaults to asc

The order to sort the specified field. Possible values are:

*   `asc`
*   `desc`

##### Request Body Examples

*Example Request JSON searching by ids*

```json
{
  "search": {
    "ids": [
      "a6e3ed2d-582b-4ec3-aa3f-4323c8f39fe9",
      "00000000-0000-0001-0000-000000000000"
    ]
  }
}
```

*Example JSON searching by query for entities with a given name*

```json
{
  "search": {
    "numberOfResults": 25,
    "query": "{\"match\":{\"name\":{\"query\":\"email_api\"}}}",
    "sortFields": [
      {
        "missing": "_first",
        "name": "name",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}
```

*Example JSON searching by query for entity with custom entity data of audited equal to true*

```json
{
  "search": {
    "numberOfResults": 25,
    "query": "{\"match\":{\"data.audited\":{\"query\":\"true\"}}}",
    "sortFields": [
      {
        "missing": "_first",
        "name": "name",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}
```

*Example Request JSON searching by queryString for entities with a name matching a pattern*

```json
{
  "search": {
    "numberOfResults": 25,
    "queryString": "name:*api*",
    "sortFields": [
      {
        "missing": "_first",
        "name": "name",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}
```

*Example Request JSON searching by queryString for entities in 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
{
  "search": {
    "numberOfResults": 25,
    "queryString": "tenantId:39666465-6535-3731-3139-666363356438",
    "sortFields": [
      {
        "missing": "_first",
        "name": "name",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}
```

*Example Request JSON searching by nextResults for entities using a token returned in a previous search response*

```json
{
  "search": {
    "numberOfResults": 25,
    "nextResults": "eyJscyI6WyIxLjAxNzM5MTciLCJlbnRpdHktMSIsImE3OTA0NTZmLTFmZTUtNGE2ZS04MWNkLWZmOTA3MmJmMzRmYiJdLCJxcyI6IioiLCJzZiI6W119"
  }
}
```

### Response

The response contains the Entity objects that were found as part of the lookup or search. Both the database and Elasticsearch search engines return the response in the same format.

*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. |

#### Response Body

`total`

*   Long

The number of entities that matched the search criteria. The number of results in the response will be equal to the `numberOfResults` provided on the request, if not provided the default number of results will be returned.

This value may cap out at 10,000 even if more entities are found based upon the provided search query. Use the `accurateTotal` request parameter if you require this value to represent the actual number of matching entities in the search index when your query may match more than 10,000 entities.

`nextResults`

*   String
*   Available since 1.48.0

A token that can be used in subsequent search requests to page forward after the last result of the current response.

This value will not be returned when FusionAuth is configured to use the database search engine.

See [Extended Pagination](https://fusionauth.io/docs/lifecycle/manage-users/search.md#extended-pagination) for more information.

`entities[x]`

*   Array

The list of Entity objects.

`entities[x].data`

*   Object

An object that can hold any information about the Entity that should be persisted. Please review the [limits on data field types](https://fusionauth.io/docs/get-started/core-concepts/limitations.md#data-type-changes-in-data-fields) as you plan for and build your custom data schema.

`entities[x].clientId`

*   String

The OAuth 2.0 client Id.

`entities[x].clientSecret`

*   String

The OAuth 2.0 client secret.

`entities[x].id`

*   UUID

The unique Id of the Entity.

`entities[x].insertInstant`

*   Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Entity was added to the FusionAuth database.

`entities[x].lastUpdateInstant`

*   Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Entity was last updated in the FusionAuth database.

`entities[x].name`

*   String

A descriptive name for the Entity (i.e. "Raviga" or "Email Service").

`entities[x].tenantId`

*   UUID

The Id of the Tenant to which this Entity belongs.

`entities[x].type`

*   Object

The Entity Type of this Entity. Consult the [Entity Type documentation](https://fusionauth.io/docs/apis/entities/entity-types.md) for more details about the fields of this object.

*Example Response JSON for multiple Entities*

```json
{
  "entities": [
    {
      "clientId": "092dbded-30af-4149-9c61-b578f2c72f59",
      "clientSecret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
      "data": {
        "companyType": "Legal"
      },
      "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
      "insertInstant": 1595361142909,
      "lastUpdateInstant": 1595361143101,
      "name": "Raviga",
      "tenantId": "30663132-6464-6665-3032-326466613934",
      "type": {
        "id": "4838d96a-4e7b-42c6-a4a1-ebc64952e1c8",
        "insertInstant": 1518962408732,
        "jwtConfiguration": {
          "enabled": false,
          "timeToLiveInSeconds": 60
        },
        "lastUpdateInstant": 1518962408732,
        "name": "Customers"
      }
    }
  ],
  "nextResults": "eyJscyI6WyIxLjAxNzM5MTciLCJlbnRpdHktMSIsImE3OTA0NTZmLTFmZTUtNGE2ZS04MWNkLWZmOTA3MmJmMzRmYiJdLCJxcyI6IioiLCJzZiI6W119",
  "total": 1
}
```

## Flush the Search Engine

This API is used to issue a flush request to the FusionAuth Search. This will cause any cached data to be written to disk. In practice it is unlikely you'll find a need for this API in production unless you are performing search requests immediately following an operation that modifies the index and expecting to see the results immediately.

### Request

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Flushes the Search Engine

`PUT /api/entity/search`

### Response

The response does not contain a body. It only contains one of the status codes below.

*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). |
| 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. |