# People search available fields

> Discover the filters accepted by the People Search endpoint.

## Introduction

This endpoint returns metadata describing every filter accepted by [People search](https://docs.reversecontact.com/endpoints/search-people) and [People search count](https://docs.reversecontact.com/endpoints/search-people-count). It lets integrations (for example Clay) discover available inputs dynamically instead of hardcoding the filter list, so new search capabilities surface automatically as we release them.

For closed-vocabulary filters, such as the position taxonomy functions, sub-functions and seniorities, the `allowedValues` array lists every accepted value, so this endpoint is also the easiest way to read the full 386-entry sub-function list. On `currentSubFunction`, an `allowedValueGroups` object additionally says which function each sub-function belongs to, which is what a filter panel needs to offer them as a tree.

Like [Usage](https://docs.reversecontact.com/endpoints/usage), this route uses `GET`, takes no request body, and **costs 0 credits**.

> Looking for company filters? See [Company search available fields](https://docs.reversecontact.com/endpoints/search-companies-available-fields).

## Endpoint

| Method | URL                                   | Describes     |
| ------ | ------------------------------------- | ------------- |
| `GET`  | `/v2/search/people/available-fields` | People Search |

## Authorization

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

## Response structure

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

**data** (SearchFields): Container for the discovered fields

| Field    | Type     | Description                                       |
| -------- | -------- | ------------------------------------------------- |
| `object` | string   | Always `"search_fields"`                          |
| `entity` | string   | Always `"person"` for this endpoint               |
| `fields` | `Field[]` | List of accepted filters (see field shape below)  |

**fields** (Field): One accepted search filter

| Field          | Type      | Description                                                                       |
| -------------- | --------- | --------------------------------------------------------------------------------- |
| `name`         | string    | Filter name, used as a key in the search request body                             |
| `type`         | string    | `string`, `boolean`, `number`, `range`, `location`, `date-time`, `experience`, or `string \| string[]` |
| `required`     | boolean   | Whether the filter is mandatory (always `false` today; all filters are optional)  |
| `description`  | string    | Human-readable explanation of the filter                                          |
| `example`      | unknown   | Example value, when helpful (optional)                                            |
| `allowedValues`| `unknown[]` | Closed set of accepted values, when applicable, such as the position taxonomy lists (optional) |
| `properties`   | object    | Sub-field shapes for `range`, `location` and `experience` filters (optional)      |

## Code examples

**Code Examples**

```bash [cURL]
curl https://api.reversecontact.com/v2/search/people/available-fields \
  -H "Authorization: Bearer YOUR_API_KEY"
```
```javascript [JavaScript]
const response = await fetch(
  "https://api.reversecontact.com/v2/search/people/available-fields",
  {
    headers: {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
);

const data = await response.json();
console.log(data.data.fields.map((f) => f.name));
```
```python [Python]
import requests

response = requests.get(
    "https://api.reversecontact.com/v2/search/people/available-fields",
    headers={
        "Authorization": "Bearer YOUR_API_KEY"
    }
)

data = response.json()
print([f["name"] for f in data["data"]["fields"]])
```

## Example response

The response below is truncated to three fields: the catalog describes every filter accepted by People search.

**Example Response**

```json [200 - Success]
{
  "success": true,
  "data": {
    "object": "search_fields",
    "entity": "person",
    "fields": [
      {
        "name": "firstName",
        "type": "string",
        "required": false,
        "description": "Filter by first name",
        "example": "John"
      },
      {
        "name": "currentSeniority",
        "type": "string | string[]",
        "required": false,
        "description": "Current job-level taxonomy value",
        "allowedValues": [
          "CXO",
          "VP",
          "Director",
          "Head",
          "Manager",
          "Partner",
          "Owner / Founder",
          "Individual Contributor",
          "Intern",
          "Other"
        ]
      },
      {
        "name": "experience",
        "type": "experience",
        "required": false,
        "description": "Required past experience dimensions, AND-combined (maximum 10)",
        "properties": {
          "dimension": {
            "type": "string",
            "allowedValues": ["function", "subFunction", "seniority"]
          },
          "value": {
            "type": "string",
            "description": "Value from the selected dimension taxonomy"
          },
          "minMonths": {
            "type": "number",
            "description": "Minimum tenure in months (0-720)"
          }
        }
      }
    ]
  },
  "error": null,
  "quotas": {
    "creditsConsumed": 0,
    "workspace": {
      "id": "ws_abc123",
      "credits": { "total": 10000, "used": 4521, "left": 5479 }
    }
  },
  "metadata": {
    "requestId": "req_f1e2l3d4s5",
    "executionTimeMs": 3
  }
}
```