> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt) # Search for Groups API documentation for the FusionAuth Search for Groups API. # Search for Groups version This API has been available since 1.45.0 This API is used to search for Groups and 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 [!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication) Search for Groups GET/api/group/search?name={name}&tenantId={tenantId} #### 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 Parameters `name`Stringoptional The case-insensitive string to search for in the Group name. This can contain wildcards using the asterisk character (`*`). If no wildcards are present, the search criteria will be interpreted as `*value*`. `numberOfResults`IntegeroptionalDefaults to 25 The number of results to return from the search. `orderBy`StringoptionalDefaults to name ASC The database field to order the search results as well as an order direction. The possible values are: * `id` - the unique Id of the Group * `insertInstant` - the [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the Group was created * `name` - the Group name * `tenant` - the name of the Tenant in which the Group belongs The order direction is optional. Possible values of the order direction are `ASC` or `DESC`. If omitted, the default sort order is `ASC`. For example, to order the results by the insert instant in a descending order, use `insertInstant DESC`. `startRow`IntegeroptionalDefaults to 0 The offset into the total results. In order to paginate the results, increment this value by the **numberOfResults** for subsequent requests. For example, if the total search results are greater than the page size designated by **numberOfResults**, set this value to `25` to retrieve results `26-50`, assuming the default page size. `tenantId`UUIDoptional Restricts the results to Groups belonging to the given Tenant. This parameter will be overridden if the request contains an `X-FusionAuth-TenantId` header, or if the supplied API key is scoped to a specific Tenant. [!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication) Search for Groups POST/api/group/search OpenAPI Spec When calling the API using a `POST` request you will send the search criteria in a JSON request body. #### 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 `search.name`Stringoptional The case-insensitive string to search for in the Group name. This can contain wildcards using the asterisk character (`*`). If no wildcards are present, the search criteria will be interpreted as `*value*`. `search.numberOfResults`IntegeroptionalDefaults to 25 The number of results to return from the search. `search.orderBy`StringoptionalDefaults to name ASC The database field to order the search results as well as an order direction. The possible values are: * `id` - the unique Id of the Group * `insertInstant` - the [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the Group was created * `name` - the Group name * `tenant` - the name of the Tenant in which the Group belongs The order direction is optional. Possible values of the order direction are `ASC` or `DESC`. If omitted, the default sort order is `ASC`. For example, to order the results by the insert instant in a descending order, use `insertInstant DESC`. `search.startRow`IntegeroptionalDefaults to 0 The offset into the total results. In order to paginate the results, increment this value by the **numberOfResults** for subsequent requests. For example, if the total search results are greater than the page size designated by **numberOfResults**, set this value to `25` to retrieve results `26-50`, assuming the default page size. `search.tenantId`UUIDoptional Restricts the results to Groups belonging to the given Tenant. This parameter will be overridden if the request contains an `X-FusionAuth-TenantId` header, or if the supplied API key is scoped to a specific Tenant. *Example JSON Request* ```json { "search": { "name": "Admins", "tenantId": "50435e55-6e95-4d54-96d0-9c953dd53eeb", "numberOfResults": 25, "orderBy": "insertInstant", "startRow": 0 } } ``` ## Response The response for this API contains the Groups matching the search criteria in paginated 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). | | 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. | ### Response Body #### Response Body `groups`Array The list of Group objects. `groups[x].data`Object An object that can hold any information about the Group that should be persisted. `groups[x].id`UUID The name of the Group. `group[x].insertInstant`Long The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Group was added to the FusionAuth database. `group[x].lastUpdateInstant`Long The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Group was updated in the FusionAuth database. `groups[x].name`String The name of the Group. `groups[x].roles`Map The roles assigned to this Group. The map key is the Application Id, the value is an array of Application Roles. `groups[x].roles[applicationId][x].description`String The description of the role. `groups[x].roles[applicationId][x].id`UUID The Application Role Unique Id `groups[x].roles[applicationId][x].name`String The name of the Group. `groups[x].roles[applicationId][x].isDefault`Boolean Whether or not the Role is a default role. A default role is automatically assigned to a user during registration if no roles are provided. `groups[x].roles[applicationId][x].isSuperRole`Boolean Whether or not the Role is a considered to be a super user role. This is a marker to indicate that it supersedes all other roles. FusionAuth will attempt to enforce this contract when using the web UI, it is not enforced programmatically when using the API. `groups[x].tenantId`UUID The unique Id of the Tenant. `total`Integer The total number of Groups matching the search criteria. Use this value along with the **numberOfResults** and **startRow** in the Search request to perform pagination. *Example Response JSON* ```json { "groups": [ { "data": { "description": "This group assigns members admin access to all applications.", "external": { "createdAt": 1503000771468 } }, "id": "1188edfc-cef3-4555-910e-181ddf6153c0", "insertInstant": 1595361142909, "lastUpdateInstant": 1595361143101, "name": "Company Admins", "roles": { "931fded0-f917-439d-b447-d7f21b37a134": [ { "id": "68259c40-0b4e-4245-8956-7e5af0959c2b", "isDefault": false, "isSuperRole": true, "name": "admin" } ], "07d1efe7-9a14-433d-8247-2235e67736f0": [ { "id": "00f24e72-52e2-4f55-8ea1-6a06bfe10df5", "isDefault": false, "isSuperRole": true, "name": "ADMIN" } ], "d23e9a51-2b20-4384-9c74-432e12219aad": [ { "id": "11a5b1b8-7ef5-476f-af7d-69e19796fa8b", "isDefault": false, "isSuperRole": true, "name": "Administrator" } ] }, "tenantId": "30663132-6464-6665-3032-326466613934" } ], "total": 1 } ```