# Business Unit Search Business Unit Search enables merchants to search across a large number of Business Units in a Project, supporting back-office use cases. The Business Unit Search API is designed to be ID-first—returning only Business Unit IDs—to provide the best performance. To fetch a Business Unit, use local caches or the [Get Business Unit by ID](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fbusiness-units%2F%7Bid%7D%3AGET) endpoint. In addition to the Merchant Center, the feature also lets you search for Business Units in other back-office applications. It is not intended for searching through Business Units in a storefront. A maximum of 10000 addresses per Business Unit can be indexed for Business Unit Search. Business Unit Search is deactivated for a Project, by default. To activate, use the [Change Business Unit Search status](https://docs.commercetools.com/api/projects/project.md#change-business-unit-search-status) update action on the Project API or index the Business Units in the [Merchant Center](https://docs.commercetools.com/docs/login.md) (by navigating to Customers > Business Unit List). If no calls have been made to the [Search Business Units](https://docs.commercetools.com/api/projects/business-unit-search.md#search-business-units) endpoint in the last 30 days, the feature is automatically deactivated for a Project and must be reactivated. ## Representations #### BusinessUnitSearchRequest See API type definition [BusinessUnitSearchRequest](https://docs.commercetools.com/api/projects/business-unit-search.md?urn=ctp%3Aapi%3Atype%3ABusinessUnitSearchRequest). #### BusinessUnitPagedSearchResponse See API type definition [BusinessUnitPagedSearchResponse](https://docs.commercetools.com/api/projects/business-unit-search.md?urn=ctp%3Aapi%3Atype%3ABusinessUnitPagedSearchResponse). ##### BusinessUnitSearchResult See API type definition [BusinessUnitSearchResult](https://docs.commercetools.com/api/projects/business-unit-search.md?urn=ctp%3Aapi%3Atype%3ABusinessUnitSearchResult). #### BusinessUnitSearchIndexingStatusResponse See API type definition [BusinessUnitSearchIndexingStatusResponse](https://docs.commercetools.com/api/projects/business-unit-search.md?urn=ctp%3Aapi%3Atype%3ABusinessUnitSearchIndexingStatusResponse). ##### BusinessUnitIndexingProgress See API type definition [BusinessUnitIndexingProgress](https://docs.commercetools.com/api/projects/business-unit-search.md?urn=ctp%3Aapi%3Atype%3ABusinessUnitIndexingProgress). ##### BusinessUnitIndexingStatus See API type definition [BusinessUnitIndexingStatus](https://docs.commercetools.com/api/projects/business-unit-search.md?urn=ctp%3Aapi%3Atype%3ABusinessUnitIndexingStatus). ## Search Business Units To check if an index is available, use the [Check if Business Unit Search index exists](https://docs.commercetools.com/api/projects/business-unit-search.md#check-if-business-unit-search-index-exists) endpoint. To check the indexing progress and status, use the [Get indexing status of Business Unit Search](https://docs.commercetools.com/api/projects/business-unit-search.md#get-indexing-status-of-business-unit-search) endpoint. See API endpoint definition [POST /\{projectKey}/business-units/search](https://docs.commercetools.com/api/projects/business-unit-search.md?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fbusiness-units%2Fsearch%3APOST). ## Get indexing status of Business Unit Search See API endpoint definition [GET /\{projectKey}/business-units/search/indexing-status](https://docs.commercetools.com/api/projects/business-unit-search.md?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fbusiness-units%2Fsearch%2Findexing-status%3AGET). ## Check if Business Unit Search index exists See API endpoint definition [HEAD /\{projectKey}/business-units/search](https://docs.commercetools.com/api/projects/business-unit-search.md?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fbusiness-units%2Fsearch%3AHEAD). ## Searchable Business Unit fields The following list contains the [Business Unit](https://docs.commercetools.com/api/projects/business-units.md#businessunit) fields that are supported in [simple expressions](https://docs.commercetools.com/api/search-query-language.md#simple-expressions) for a [BusinessUnitSearchRequest](https://docs.commercetools.com/api/projects/business-unit-search.md#businessunitsearchrequest). ### Number and date fields Use the following fields in [exact](https://docs.commercetools.com/api/search-query-language.md#exact), [exists](https://docs.commercetools.com/api/search-query-language.md#exists), and [range](https://docs.commercetools.com/api/search-query-language.md#range) expressions. Data type indicates the [type of field](https://docs.commercetools.com/api/search-query-language.md#types-of-fields) for the field. (a CSV formatted table follows. The first line are the column names.) Standard field,Data type,Query for `createdAt`,dateTime,Business Units created at a certain date and time. `lastModifiedAt`,dateTime,Business Units last modified at any of its fields at a certain date and time. `version`,long,Business Units with a certain version of the resource. Example: Find Business Units created in December 2023: ```json title="Request" { "query": { "range": { "field": "createdAt", "gte": "2023-12-01T00:00:00.000Z", "lt": "2024-01-01T00:00:00.000Z" } } } ``` ### Text fields Use the following text [type fields](https://docs.commercetools.com/api/search-query-language.md#types-of-fields) in [exact](https://docs.commercetools.com/api/search-query-language.md#exact), [fullText](https://docs.commercetools.com/api/search-query-language.md#fulltext), [prefix](https://docs.commercetools.com/api/search-query-language.md#prefix), [fuzzy](https://docs.commercetools.com/api/search-query-language.md#fuzzy), [wildcard](https://docs.commercetools.com/api/search-query-language.md#wildcard), and [exists](https://docs.commercetools.com/api/search-query-language.md#exists) query expressions. (a CSV formatted table follows. The first line are the column names.) Standard field,Query for `addresses.all`,[Business Units](https://docs.commercetools.com/api/projects/business-units.md#businessunit) with a certain string in the combination of all [Address](https://docs.commercetools.com/api/types.md#baseaddress) fields. `addresses.city`,Business Units with a certain string in the `city` field of all the Business Unit's addresses. `addresses.company`,Business Units with a certain string in the `company` field of all the Business Unit's addresses. `addresses.country`,Business Units with a certain string in the `country` field of all the Business Unit's addresses. `addresses.firstName`,Business Units with a certain string in the `firstName` field of all the Business Unit's addresses. `addresses.lastName`,Business Units with a certain string in the `lastName` field of all the Business Unit's addresses. `addresses.mobile`,Business Units with a certain string in the `mobile` field of all the Business Unit's addresses. `addresses.phone`,Business Units with a certain string in the `phone` field of all the Business Unit's addresses. `addresses.postalCode`,Business Units with a certain string in the `postalCode` field of all the Business Unit's addresses. `addresses.streetName`,Business Units with a certain string in the `streetName` field of all the Business Unit's addresses. `addresses.streetNumber`,Business Units with a certain string in the `streetNumber` field of all the Business Unit's addresses. `all`,Business Units with a certain string in any of the Business Unit's fields. Does not support [wildcard expressions](https://docs.commercetools.com/api/search-query-language.md#wildcard). `contactEmail`,Business Units with a certain contact email. `key`,Business Units with a certain key. `topLevelUnitKey`,Business Units with a certain top level unit key. `parentUnitKey`,Business Units with a certain parent unit key. `name`,Business Units with a certain name. Examples: Find Business Units with the name containing Plumbing (case insensitive): ```json title="Request" { "query": { "fullText": { "field": "name", "value": "plumbing" } } } ``` Find Business Units mentioning "example" in any field. This query will not only find "example" in fields like `name`, but also in `contactEmail` addresses like [email@example.com](mailto:email@example.com). ```json title="Request" { "query": { "fullText": { "field": "all", "value": "example" } } } ``` ### Keyword fields Use the following keyword [type fields](https://docs.commercetools.com/api/search-query-language.md#types-of-fields), containing unique IDs or keys, in [exact](https://docs.commercetools.com/api/search-query-language.md#exact), [prefix](https://docs.commercetools.com/api/search-query-language.md#prefix), [wildcard](https://docs.commercetools.com/api/search-query-language.md#wildcard), and [exists](https://docs.commercetools.com/api/search-query-language.md#exists) expressions. To query for multiple values of the same field or for several fields in the same request, combine the simple expressions with a [compound expression](https://docs.commercetools.com/api/search-query-language.md#compound-expressions). (a CSV formatted table follows. The first line are the column names.) Standard field,Query for `unitType`,a Business Unit with a specific [`unitType`](https://docs.commercetools.com/api/projects/business-units.md#businessunittype). `status`,a Business Unit with a specific [`status`](https://docs.commercetools.com/api/projects/business-units.md#businessunitstatus). `stores.key`,a Business Unit of a specific [Store](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AStore) identified by its `key`. `inheritedStores.key`,a Business Unit of a specific inherited [Store](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AStore) identified by its `key`. `storeMode`,a Business Unit with a specific [`storeMode`](https://docs.commercetools.com/api/projects/business-units.md#businessunitstoremode). `customerGroupAssignments.customerGroup.id` ,a Business Unit in a specific [CustomerGroup](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3ACustomerGroup) identified by its `id`. Example: Find Business Units with the unitType `Division` ```json title="Request" { "query": { "exact": { "field": "unitType", "value": "Division" } } } ``` ### Custom Fields In addition to the standard fields on a Business Unit, you can also search for its [Custom Fields](https://docs.commercetools.com/api/projects/custom-fields.md), if any. `custom.` queries for Business Units with a Custom Field of a specific name, and the [SearchFieldType](https://docs.commercetools.com/api/search-query-language.md#searchfieldtype) determines the data type of the field. The `ltext` [SearchFieldType](https://docs.commercetools.com/api/search-query-language.md#searchfieldtype) is not supported. To query `enum` and `lenum` [SearchFieldTypes](https://docs.commercetools.com/api/search-query-language.md#searchfieldtype), use the `key` of the enum value. Example: An exact query to find Business Units with an [enum type](https://docs.commercetools.com/api/projects/types.md#customfieldenumtype) Custom Field `accountPlan` to the enum key of `silver`. ```json title="Request" { "query": { "exact": { "field": "custom.accountPlan.key", "value": "silver", "fieldType": "enum" } } } ``` ## Related pages - [Section overview page](https://docs.commercetools.com/api.md) - [Previous page: Business Units](https://docs.commercetools.com/api/projects/business-units.md) - [Next page: Associate Roles](https://docs.commercetools.com/api/projects/associate-roles.md)