> ## Documentation Index
> Fetch the complete documentation index at: https://testdocs.clodura.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Prospects and Enrich People Contact Data via API

> Search Clodura's database for contacts using powerful filters and enrich people records with professional details, location, and company context.

The Search Prospect endpoint lets you query Clodura's comprehensive contact database using a flexible combination of personal, professional, and company-level filters. You can narrow results by job title, seniority, department function, location, company size, industry, funding stage, technology stack, and more. The API is designed purely for **search and discovery** — it surfaces people records but does not directly return email addresses or phone numbers. To unlock those contact details, use the [Reveal Email](/api/people/reveal-email) and [Reveal Phone](/api/people/reveal-phone) endpoints after identifying your prospects here.

<Note>
  **Credit cost:** 1 export credit per non-empty record returned for contacts already viewed in Radar. Contacts not yet viewed in Radar incur no credits on the initial search query.
</Note>

<Warning>
  LinkedIn Sales Navigator URLs are not supported. Always supply standard `linkedin.com/in/` profile URLs.
</Warning>

## Endpoint

`POST /api/v1/search/people`

## Request

### Headers

| Header         | Value                |
| -------------- | -------------------- |
| `X-API-KEY`    | Your Clodura API key |
| `Content-Type` | `application/json`   |

### Body Parameters

<ParamField body="page" type="integer" required>
  Page number for paginated results. Accepted range: `1`–`100`.
</ParamField>

<ParamField body="perPage" type="integer" required>
  Number of records to return per page. Maximum: `100`.
</ParamField>

<ParamField body="personId" type="string">
  Clodura's unique identifier for a person. Use this to fetch or re-fetch a specific contact record directly.
</ParamField>

<ParamField body="firstName" type="string">
  First name of the person. Typically combined with `lastName` for name-based searches.
</ParamField>

<ParamField body="lastName" type="string">
  Last name of the person. Typically combined with `firstName`.
</ParamField>

<ParamField body="linkedinUrl" type="string">
  Standard LinkedIn profile URL for the person (e.g., `https://www.linkedin.com/in/kapilkhangaonkar/`). Sales Navigator URLs are not supported.
</ParamField>

<ParamField body="seniority" type="array">
  Filter by job seniority level. Accepted values: `Founder`, `Chairman`, `President`, `CEO`, `CXO`, `Vice President`, `Director`, `Head`, `Manager`, `Senior`, `Junior`, `Entry Level`, `Executive`.
</ParamField>

<ParamField body="personTitle" type="array">
  Job titles to filter by (e.g., `"marketing manager"`, `"sales rep"`). May return approximate matches unless `includeSimilarTitles` is set to `false`.
</ParamField>

<ParamField body="includeSimilarTitles" type="boolean">
  When `false`, enforces strict matching on `personTitle`. Defaults to `true` (approximate matching enabled).
</ParamField>

<ParamField body="functional" type="array">
  Filter by department or business function. Accepted values include: `Admin`, `Analytics`, `Engineering`, `Finance`, `HR`, `IT`, `Marketing`, `Operations`, `Product Management`, `Sales`, `Security`, `Support`, and more.
</ParamField>

<ParamField body="personCity" type="array">
  The person's current city of residence. Refer to the [supported cities list](https://kb.clodura.ai/assets/files/city-0e179bb959324f64595aefc1197c7b63.txt).
</ParamField>

<ParamField body="personState" type="array">
  The person's current state of residence. Refer to the [supported states list](https://kb.clodura.ai/assets/files/state-18aa91fd534fa5f0e375cab69820ba76.txt).
</ParamField>

<ParamField body="personCountry" type="array">
  The person's current country of residence. Refer to the [supported countries list](https://kb.clodura.ai/assets/files/country-bac0b920e008f616e8d3b86a9a593d6d.txt).
</ParamField>

<ParamField body="personLocationExclude" type="boolean">
  When `true`, excludes people in the specified location filters instead of including them.
</ParamField>

<ParamField body="contactEmailStatus" type="string">
  Filter by email verification status. Accepted values: `verified`, `unverified`, `unavailable`.
</ParamField>

<ParamField body="organizationId" type="string">
  Clodura's unique identifier for a company. Use the [Search Organizations](/api/company/search-organizations) endpoint to look up this value.
</ParamField>

<ParamField body="organizationName" type="string">
  The name of the employer organization. Use `organizationId` when possible for more precise matching.
</ParamField>

<ParamField body="companyDomain" type="array">
  One or more employer domain names (e.g., `google.com`, `clodura.ai`). Do not include `www.` or `@`. Maximum 10 domains per request.
</ParamField>

<ParamField body="companyEmployeeSize" type="array">
  Filter by headcount range. Accepted values: `0 - 1`, `2 - 10`, `11 - 50`, `51 - 200`, `201 - 500`, `501 - 1000`, `1001 - 5000`, `5001 - 10000`, `10000+`.
</ParamField>

<ParamField body="companyCountry" type="array">
  The company's headquarters country.
</ParamField>

<ParamField body="companyState" type="array">
  The company's headquarters state.
</ParamField>

<ParamField body="companyCity" type="array">
  The company's headquarters city.
</ParamField>

<ParamField body="includeAllOffice" type="boolean">
  When `true`, includes contacts from all office locations, not just HQ. Defaults to `false`.
</ParamField>

<ParamField body="excludeViewedPeople" type="boolean">
  When `true`, omits contacts you have already viewed or unlocked. Useful for discovering net-new leads. Defaults to `false`.
</ParamField>

<ParamField body="industry" type="array">
  Filter by industry sector. Refer to the [supported industries list](https://kb.clodura.ai/assets/files/industries-e4d3738a2ffe956b2ed7a739c4089370.txt).
</ParamField>

<ParamField body="industryKeywords" type="array">
  Keywords related to the industry to refine results further (e.g., `AI`, `FinTech`, `SaaS`).
</ParamField>

<ParamField body="revenue" type="array">
  Filter by estimated annual company revenue. Accepted values: `< 1M`, `1M-10M`, `11M-100M`, `101M-500M`, `501M-1B`, `1B+`.
</ParamField>

<ParamField body="fundingType" type="array">
  Filter by funding round type. Accepted values include: `Seed Round`, `Series A` through `Series J`, `Pre Seed Round`, `Venture Round`, `Angel Round`, `Private Equity Round`, `Post-IPO Equity`, and more.
</ParamField>

<ParamField body="fundingFromDate" type="date">
  Start date for filtering by funding events. Format: `YYYY-MM-DD`.
</ParamField>

<ParamField body="fundingToDate" type="date">
  End date for filtering by funding events. Format: `YYYY-MM-DD`.
</ParamField>

<ParamField body="businessModel" type="array">
  Filter by company business model. Accepted values: `Product`, `Services`, `Solutions`.
</ParamField>

<ParamField body="technologyParameters" type="array">
  Filter by technologies used by the company. Refer to the [supported technologies list](https://kb.clodura.ai/assets/files/technologies-7c729a9de68c94e8076bf96b79c73e0b.txt).
</ParamField>

<ParamField body="webKeywords" type="array">
  Keywords found on the company's website (e.g., `CRM`, `automation`, `cloud`).
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.clodura.ai/api/v1/search/people \
    --header 'X-API-KEY: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "personTitle": ["CEO"],
      "seniority": ["Founder", "CEO"],
      "companyDomain": ["clodura.ai"],
      "contactEmailStatus": "verified",
      "page": 1,
      "perPage": 25
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.clodura.ai/api/v1/search/people"

  headers = {
      "X-API-KEY": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  payload = {
      "personTitle": ["CEO"],
      "seniority": ["Founder", "CEO"],
      "companyDomain": ["clodura.ai"],
      "contactEmailStatus": "verified",
      "page": 1,
      "perPage": 25
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```
</CodeGroup>

## Response

A successful `200` response returns an array of matching people records.

<ResponseField name="personId" type="string">
  Clodura's unique identifier for this person. Use this value with [Reveal Email](/api/people/reveal-email) and [Reveal Phone](/api/people/reveal-phone).
</ResponseField>

<ResponseField name="firstName" type="string">
  The person's first name.
</ResponseField>

<ResponseField name="lastName" type="string">
  The person's last name.
</ResponseField>

<ResponseField name="linkedinUrl" type="string">
  URL of the person's LinkedIn profile.
</ResponseField>

<ResponseField name="seniority" type="array">
  Seniority levels associated with the person's current role.
</ResponseField>

<ResponseField name="personTitle" type="array">
  Job title(s) associated with the person.
</ResponseField>

<ResponseField name="functional" type="array">
  Department or functional area the person belongs to.
</ResponseField>

<ResponseField name="personCity" type="string">
  City of the person's current location.
</ResponseField>

<ResponseField name="personState" type="string">
  State of the person's current location.
</ResponseField>

<ResponseField name="personCountry" type="string">
  Country of the person's current location.
</ResponseField>

<ResponseField name="contactEmailStatus" type="string">
  Verification status of the person's email address: `verified`, `unverified`, or `unavailable`.
</ResponseField>

<ResponseField name="organizationId" type="string">
  Clodura's unique identifier for the person's current employer.
</ResponseField>

<ResponseField name="organizationName" type="string">
  Name of the person's current employer.
</ResponseField>

<ResponseField name="companyDomain" type="array">
  Domain name(s) associated with the employer.
</ResponseField>

<ResponseField name="companyEmployeeSize" type="string">
  Headcount range for the employer.
</ResponseField>

<ResponseField name="companyCountry" type="string">
  Country where the company's headquarters is located.
</ResponseField>

<ResponseField name="page" type="integer">
  The current page number returned.
</ResponseField>

<ResponseField name="perPage" type="integer">
  Number of records returned per page.
</ResponseField>

### Example Response

```json theme={null}
[
  {
    "personId": "3597524184265130552",
    "firstName": "Kapil",
    "lastName": "Khangaonkar",
    "linkedinUrl": "https://www.linkedin.com/in/kapilkhangaonkar/",
    "seniority": ["Founder"],
    "personTitle": ["CEO"],
    "functional": ["Admin"],
    "personCity": ["Pune"],
    "personState": ["Maharashtra"],
    "personCountry": ["India"],
    "contactEmailStatus": "verified",
    "organizationId": "2389402640191586304",
    "organizationName": "Clodura.AI",
    "companyDomain": ["clodura.ai"],
    "companyEmployeeSize": ["51-100"],
    "companyCountry": ["United States"],
    "page": 1,
    "perPage": 25
  }
]
```

## Webhook Tracking

The Search People API is asynchronous for email and phone reveals. When you submit a request to the [Reveal Email](/api/people/reveal-email) or [Reveal Phone](/api/people/reveal-phone) endpoints, the API immediately returns a `trackingId`. Use this ID with the `GET /api/v1/search/people/track/{trackingId}` endpoint to poll for results or have them delivered to your `webhookUrl`. See [Credit Usage](/api/people/credits) to monitor your remaining balance.

## Error Codes

| Status | Meaning                                                                                 |
| ------ | --------------------------------------------------------------------------------------- |
| `400`  | Bad request — check parameter values (e.g., domain count exceeds 10)                    |
| `401`  | Unauthorized — your API key is missing or invalid                                       |
| `402`  | Payment required — credits exhausted; upgrade your plan or add credits                  |
| `403`  | Forbidden — this endpoint requires a paid Clodura plan                                  |
| `404`  | No results found — try adjusting your filters                                           |
| `422`  | Unprocessable entity — invalid parameter combination or missing required parent filters |
| `429`  | Rate limit exceeded — slow down requests or upgrade your plan                           |