Endpoints // Utility

People search available fields

New

Discover the filters accepted by the People Search endpoint.

GET/v2/search/people/available-fields

Introduction

This endpoint returns metadata describing every filter accepted by People search and People search 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, this route uses GET, takes no request body, and costs 0 credits.

Looking for company filters? See Company search 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

dataobject

Container for the discovered fields

Show child attributes

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)

fieldsobject

One accepted search filter

Show child attributes

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

curl https://api.reversecontact.com/v2/search/people/available-fields \
  -H "Authorization: Bearer YOUR_API_KEY"

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));

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.

200 - Success

Example Response

{
  "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
  }
}