---
title: "POST /v1/searches"
method: POST
path: "/v1/searches"
tags: ["Search"]
---

# POST /v1/searches

`POST /v1/searches`

## Request

- Base URL: `https://usefind.ai/found`
- URL: `https://usefind.ai/found/v1/searches`
- Auth: API key in header `Authorization`

Starts a search.

## Request body

- object
  - `query` string: Search query.
  - `scope` 'person' | 'company': The scope of the search. Valid values are 'person' or 'company'.
  - `result_mode` 'exact' | 'best': The mode of the search. Valid values are 'exact' or 'best'.
  - `max_matches` number: The maximum number of results to return. optional for result_mode exact

## Response `202`

Search has been started.
Poll based on the details in the response for the status and latest information.

- object
  - `poll` object, required
    - `token` string, required
    - `path` string, required

## Other responses

- `422`: The search params were invalid.

## Changes

- **2024-10-08** `f1e4b85be4f9`: 2 breaking, 4 info
  - request property `result_mode` was restricted to a list of enum values
  - request property `scope` was restricted to a list of enum values
  - added the new `best` enum value to the request property `result_mode`
  - added the new `company` enum value to the request property `scope`
  - …2 more
- **2024-09-25** `f45934597cf4`: 2 breaking, 2 info
  - removed the media type `*/*` for the response with the status `202`
  - removed the media type `*/*` for the response with the status `422`
  - added the media type `application/json` for the response with the status `202`
  - added the media type `application/json` for the response with the status `422`

[Operation history](https://skmtc.dev/find-ai/apis/usefind-ai-params-in-body/changes/v1/searches/post.md)

---

[API](https://skmtc.dev/find-ai/apis/usefind-ai-params-in-body.md) - [All operations](https://skmtc.dev/find-ai/apis/usefind-ai-params-in-body/llms.txt) - [OpenAPI document](https://skmtc.dev/find-ai/apis/usefind-ai-params-in-body/revisions/f1e4b85be4f9?raw)
