# People search count

> Count matching people with the same filters as People search, for free.

## Introduction

The People Search Count endpoint returns the total number of profiles matching the same filters as [People search](https://docs.reversecontact.com/endpoints/search-people), without returning any profile. Use it to size a query before spending credits: [People search](https://docs.reversecontact.com/endpoints/search-people) costs 1 credit per profile delivered, while this endpoint is free.

The endpoint accepts exactly the filters of People search, without the pagination parameters: a count is a single number, so there is no page to request.

Like [Usage](https://docs.reversecontact.com/endpoints/usage), this endpoint **costs 0 credits**, but it is still a real request: it counts toward your rate limits.

## Authorization

| Name     | Type   | Required | Description                                                                                         |
| -------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| `apikey` | string | Yes      | Your API key from the developer dashboard. Pass it via `Authorization: Bearer YOUR_API_KEY` header. |

## Request body

All filters are **optional** and combined with **AND** logic, exactly as on [People search](https://docs.reversecontact.com/endpoints/search-people#request-body): scalar filters, the nested-object filters (`followersCount`, `currentCompanyEmployeeCountRange`, `totalExperienceMonths`, `location`, `experience`) the [position taxonomy](https://docs.reversecontact.com/endpoints/search-people#position-taxonomy) filters, and the [skills, languages, keywords and job change](https://docs.reversecontact.com/endpoints/search-people#skills-languages-keywords-and-job-changes) filters. See the People search page for the complete reference.

Filters are validated before the query runs: unknown field names, blank values and values outside a closed list return HTTP `422` with the offending field and suggested values. See [Search filter validation](https://docs.reversecontact.com/guides/errors-retries#search-filter-validation).

## Response structure

| Field     | Type    | Description                                      |
| --------- | ------- | ------------------------------------------------ |
| `success` | boolean | `true` if the request was processed successfully |
| `error`   | `null`  | Always `null` on success                         |

**data** (SearchCount): Total number of matching profiles

| Field   | Type   | Description                                       |
| ------- | ------ | ------------------------------------------------- |
| `count` | number | Total profiles matching the supplied filters, across all pages |

## Code examples

**Code Examples**

```bash [cURL]
curl -X POST https://api.reversecontact.com/v2/search/people/count \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currentFunction": "Marketing",
    "currentSeniority": ["Director", "VP"],
    "location": { "countryCode": "FR" }
  }'
```
```javascript [JavaScript]
const response = await fetch(
  "https://api.reversecontact.com/v2/search/people/count",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      currentFunction: "Marketing",
      currentSeniority: ["Director", "VP"],
      location: { countryCode: "FR" }
    })
  }
);

const payload = await response.json();
console.log(`${payload.data.count} matching people`);
```
```python [Python]
import requests

response = requests.post(
    "https://api.reversecontact.com/v2/search/people/count",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "currentFunction": "Marketing",
        "currentSeniority": ["Director", "VP"],
        "location": {"countryCode": "FR"}
    }
)

payload = response.json()
print(f"{payload['data']['count']} matching people")
```

## Example response

**Example Response**

```json [200 - Success]
{
  "success": true,
  "data": {
    "count": 1842
  },
  "error": null,
  "quotas": {
    "creditsConsumed": 0,
    "workspace": {
      "id": "ws_abc123",
      "credits": { "total": 10000, "used": 4521, "left": 5479 }
    }
  },
  "metadata": {
    "requestId": "req_c1o2u3n4t5",
    "executionTimeMs": 95
  }
}
```