> For the complete documentation index, see [llms.txt](https://detected.gitbook.io/detected-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://detected.gitbook.io/detected-docs/search.md).

# Search

Search for entities across data providers, and retrieve the search options available for each type and country.

## Search for an entity

> Searches for a company or other entity using criteria such as its name, company number and address. We query several data providers and return the most relevant results. Each result is scored against your search criteria using fuzzy matching. Some providers also do fuzzy matching, and others do not. Each result shows which provider supplied it.\
> \
> \### Creating a profile from a search result\
> \
> You can create a profile directly from a search result. Send the \`lookup\_id\` from the response, and the \`response\_id\` of the result you want, to \`POST /profiles\`. See the examples on that endpoint.

```json
{"openapi":"3.0.0","info":{"title":"Detected API","version":"v2"},"tags":[{"name":"Search","description":"Search for entities across data providers, and retrieve the search options available for each type and country."}],"servers":[{"url":"https://api.detected.app/api/v2/public","description":"Production"}],"security":[{"AccessToken":[]}],"components":{"securitySchemes":{"AccessToken":{"type":"http","description":"The API uses OAuth 2.0. Request an access token from `POST /oauth/token` with the client ID and client secret of your integration client, and your account slug. Send the access token in the `Authorization` header of every request, in the format `Authorization: Bearer <access_token>`. The access token carries the scopes set on your integration client in the dashboard. Access tokens expire. When one expires, request a new one.","bearerFormat":"OAuth 2.0 access token","scheme":"bearer"}},"schemas":{"SearchRequest":{"title":"Search Request","required":["type","address"],"properties":{"type":{"description":"Entity type to search for.","type":"string","enum":["company","sole_trader","partnership","charity","government_entity","incorporated_syndicate","company_syndicate","syndicate","association","trust","fund","club","individual","joint_individual"],"nullable":false},"name":{"description":"Name of the company to search for. Required unless `company_number` is provided.","type":"string","nullable":false},"company_number":{"description":"Official company registration number or identifier used for searching.","type":"string","nullable":false},"address":{"description":"Address to search in.","required":["country_code"],"properties":{"country_code":{"description":"Country to search in, ISO 3166-1 alpha-2 country code.","type":"string","nullable":false},"city":{"description":"City. Required unless `company_number` is provided.","type":"string","nullable":false},"state":{"description":"State or region. Required when `country_code` is `US`, unless `company_number` is provided.","type":"string","nullable":false}},"type":"object","nullable":false}},"type":"object"},"SearchResponse":{"title":"Search Response","properties":{"data":{"description":"List of search results.","type":"array","items":{"properties":{"type":{"description":"Entity type of the result.","type":"string","enum":["company","sole_trader","partnership","charity","government_entity","incorporated_syndicate","company_syndicate","syndicate","association","trust","fund","club","individual","joint_individual"]},"name":{"description":"Company name.","type":"string"},"company_reference":{"description":"Company reference number, as supplied by the provider.","type":"string"},"provider":{"description":"Data provider that supplied the result.","type":"string"},"provider_reference":{"description":"Reference of the company at the provider.","type":"string"},"jurisdiction_code":{"description":"Jurisdiction code of the company, for example `gb`.","type":"string"},"company_type":{"description":"Type of company, for example `PRIVATE LIMITED COMPANY`.","type":"string"},"current_status":{"description":"Current status of the company, for example `Dissolved`.","type":"string"},"address":{"description":"Address of the company.","type":"string"},"vat_number":{"description":"VAT number of the company, if known.","type":"string","nullable":true},"province_code":{"description":"Province or region code of the company's address.","type":"string","nullable":true},"post_code":{"description":"Postcode of the company address.","type":"string"},"city":{"description":"City of the company address.","type":"string"},"confidence":{"description":"How closely the result matches your search criteria, as a score from 0 to 100.","type":"integer"},"response_id":{"description":"ID of this result. Send it, with `lookup_id`, to `POST /profiles` to create a profile from the result.","type":"integer"}},"type":"object"}},"status":{"description":"Outcome of the search: `EMPTY` if there are no results, `PARTIAL` if the results only partly match, or `MATCH` if there is a match.","type":"string","enum":["EMPTY","PARTIAL","MATCH"]},"lookup_id":{"description":"ID of this search. Send it, with the `response_id` of a result, to `POST /profiles` to create a profile from the result.","type":"integer"}},"type":"object"}},"headers":{"X-RateLimit-Limit":{"description":"Maximum number of requests allowed in the rate limit window.","schema":{"type":"number","nullable":false}},"X-RateLimit-Remaining":{"description":"Number of requests remaining in the current rate limit window.","schema":{"type":"number","nullable":false}},"Retry-After":{"description":"Number of seconds to wait before making another request. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}},"X-RateLimit-Reset":{"description":"Unix timestamp (in seconds) at which the rate limit resets. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}}},"responses":{"401":{"description":"Unauthorized. The access token is missing, invalid or has expired.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}},"404":{"description":"Not Found. The requested resource does not exist, or is not available to your account.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}},"422":{"description":"Unprocessable Content. The request was understood but failed validation. The response lists the fields that failed and why.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"},"example_field":{"description":"Validation errors for one field of the request body. The property name is the name of the field that failed validation (`example_field` is a placeholder).","type":"array","items":{"type":"string"}}},"type":"object"}}}},"429":{"description":"Too Many Requests. You have exceeded the rate limit. Wait for the number of seconds given in the `Retry-After` header before trying again.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}}}},"paths":{"/search":{"post":{"tags":["Search"],"summary":"Search for an entity","description":"Searches for a company or other entity using criteria such as its name, company number and address. We query several data providers and return the most relevant results. Each result is scored against your search criteria using fuzzy matching. Some providers also do fuzzy matching, and others do not. Each result shows which provider supplied it.\n\n### Creating a profile from a search result\n\nYou can create a profile directly from a search result. Send the `lookup_id` from the response, and the `response_id` of the result you want, to `POST /profiles`. See the examples on that endpoint.","operationId":"search","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}}}}}}
```

## Retrieve search type configuration

> Returns the search configuration for an entity type in a country: whether search is enabled, and which search fields you can use with \`POST /search\`.

```json
{"openapi":"3.0.0","info":{"title":"Detected API","version":"v2"},"tags":[{"name":"Search","description":"Search for entities across data providers, and retrieve the search options available for each type and country."}],"servers":[{"url":"https://api.detected.app/api/v2/public","description":"Production"}],"security":[{"AccessToken":[]}],"components":{"securitySchemes":{"AccessToken":{"type":"http","description":"The API uses OAuth 2.0. Request an access token from `POST /oauth/token` with the client ID and client secret of your integration client, and your account slug. Send the access token in the `Authorization` header of every request, in the format `Authorization: Bearer <access_token>`. The access token carries the scopes set on your integration client in the dashboard. Access tokens expire. When one expires, request a new one.","bearerFormat":"OAuth 2.0 access token","scheme":"bearer"}},"parameters":{"type":{"name":"type","in":"path","description":"Entity type, for example `company` or `sole_trader`. Use `GET /search/types` to list the available types.","required":true,"schema":{"type":"string","nullable":false}},"countryCode":{"name":"countryCode","in":"path","description":"Two-letter country code in ISO 3166-1 alpha-2 format, for example `GB`.","required":true,"schema":{"type":"string","nullable":false}}},"headers":{"X-RateLimit-Limit":{"description":"Maximum number of requests allowed in the rate limit window.","schema":{"type":"number","nullable":false}},"X-RateLimit-Remaining":{"description":"Number of requests remaining in the current rate limit window.","schema":{"type":"number","nullable":false}},"Retry-After":{"description":"Number of seconds to wait before making another request. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}},"X-RateLimit-Reset":{"description":"Unix timestamp (in seconds) at which the rate limit resets. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}}},"schemas":{"SearchTypeResponse":{"title":"Search Type Response","properties":{"company":{"$ref":"#/components/schemas/EntityTypeConfig"},"sole_trader":{"$ref":"#/components/schemas/EntityTypeConfig"},"partnership":{"$ref":"#/components/schemas/EntityTypeConfig"},"charity":{"$ref":"#/components/schemas/EntityTypeConfig"},"government_entity":{"$ref":"#/components/schemas/EntityTypeConfig"},"syndicate":{"$ref":"#/components/schemas/EntityTypeConfig"},"association":{"$ref":"#/components/schemas/EntityTypeConfig"},"trust":{"$ref":"#/components/schemas/EntityTypeConfig"},"fund":{"$ref":"#/components/schemas/EntityTypeConfig"}},"type":"object"},"EntityTypeConfig":{"title":"Entity Type Config","properties":{"type":{"description":"Entity type.","type":"string"},"label":{"description":"Display name of the entity type.","type":"string"},"search_enabled":{"description":"Whether search is enabled for the entity type.","type":"boolean"},"search_fields":{"description":"Search fields available for the entity type, keyed by field name.","properties":{"address.country_code":{"$ref":"#/components/schemas/SearchField"},"customer_reference":{"$ref":"#/components/schemas/SearchField"},"name":{"$ref":"#/components/schemas/SearchField"},"address.city":{"$ref":"#/components/schemas/SearchField"},"address.state":{"$ref":"#/components/schemas/SearchField"},"company_number":{"$ref":"#/components/schemas/SearchField"},"domain":{"$ref":"#/components/schemas/SearchField"}},"type":"object"}},"type":"object"},"SearchField":{"title":"Search Field","properties":{"is_required":{"description":"Whether the field is required to run the search.","type":"boolean"},"label":{"description":"Display name of the field.","type":"string"},"position":{"description":"Position of the field in the search form.","type":"integer"}},"type":"object"}},"responses":{"401":{"description":"Unauthorized. The access token is missing, invalid or has expired.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}},"404":{"description":"Not Found. The requested resource does not exist, or is not available to your account.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}},"429":{"description":"Too Many Requests. You have exceeded the rate limit. Wait for the number of seconds given in the `Retry-After` header before trying again.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}}}},"paths":{"/search/types/{type}/{countryCode}":{"get":{"tags":["Search"],"summary":"Retrieve search type configuration","description":"Returns the search configuration for an entity type in a country: whether search is enabled, and which search fields you can use with `POST /search`.","operationId":"search-type-country-config","parameters":[{"$ref":"#/components/parameters/type"},{"$ref":"#/components/parameters/countryCode"}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchTypeResponse"}}}},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"}}}}}}
```

## List search types

> Returns the entity types that can be searched, and whether search is enabled for each.

```json
{"openapi":"3.0.0","info":{"title":"Detected API","version":"v2"},"tags":[{"name":"Search","description":"Search for entities across data providers, and retrieve the search options available for each type and country."}],"servers":[{"url":"https://api.detected.app/api/v2/public","description":"Production"}],"security":[{"AccessToken":[]}],"components":{"securitySchemes":{"AccessToken":{"type":"http","description":"The API uses OAuth 2.0. Request an access token from `POST /oauth/token` with the client ID and client secret of your integration client, and your account slug. Send the access token in the `Authorization` header of every request, in the format `Authorization: Bearer <access_token>`. The access token carries the scopes set on your integration client in the dashboard. Access tokens expire. When one expires, request a new one.","bearerFormat":"OAuth 2.0 access token","scheme":"bearer"}},"headers":{"X-RateLimit-Limit":{"description":"Maximum number of requests allowed in the rate limit window.","schema":{"type":"number","nullable":false}},"X-RateLimit-Remaining":{"description":"Number of requests remaining in the current rate limit window.","schema":{"type":"number","nullable":false}},"Retry-After":{"description":"Number of seconds to wait before making another request. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}},"X-RateLimit-Reset":{"description":"Unix timestamp (in seconds) at which the rate limit resets. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}}},"schemas":{"SearchTypesResponse":{"title":"Search Types Response","properties":{"company":{"$ref":"#/components/schemas/EntityTypesConfig"},"sole_trader":{"$ref":"#/components/schemas/EntityTypesConfig"},"partnership":{"$ref":"#/components/schemas/EntityTypesConfig"},"charity":{"$ref":"#/components/schemas/EntityTypesConfig"},"government_entity":{"$ref":"#/components/schemas/EntityTypesConfig"},"incorporated_syndicate":{"$ref":"#/components/schemas/EntityTypesConfig"},"company_syndicate":{"$ref":"#/components/schemas/EntityTypesConfig"},"syndicate":{"$ref":"#/components/schemas/EntityTypesConfig"},"association":{"$ref":"#/components/schemas/EntityTypesConfig"},"trust":{"$ref":"#/components/schemas/EntityTypesConfig"},"fund":{"$ref":"#/components/schemas/EntityTypesConfig"},"individual":{"$ref":"#/components/schemas/EntityTypesConfig"},"joint_individual":{"$ref":"#/components/schemas/EntityTypesConfig"},"club":{"$ref":"#/components/schemas/EntityTypesConfig"}},"type":"object"},"EntityTypesConfig":{"title":"Entity Types Config","properties":{"label":{"description":"Display name of the entity type.","type":"string"},"search_enabled":{"description":"Whether search is enabled for the entity type.","type":"boolean"}},"type":"object"}},"responses":{"401":{"description":"Unauthorized. The access token is missing, invalid or has expired.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}},"429":{"description":"Too Many Requests. You have exceeded the rate limit. Wait for the number of seconds given in the `Retry-After` header before trying again.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}}}},"paths":{"/search/types":{"get":{"tags":["Search"],"summary":"List search types","description":"Returns the entity types that can be searched, and whether search is enabled for each.","operationId":"search-types-list","responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchTypesResponse"}}}},"401":{"$ref":"#/components/responses/401"},"429":{"$ref":"#/components/responses/429"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://detected.gitbook.io/detected-docs/search.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.