People search 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

apikey string required

Your API key from the developer dashboard. Pass it via Authorization: Bearer YOUR_API_KEY header.

Response structure

success boolean

true if the request was processed successfully

error null

Always null on success

dataobject

Container for the discovered fields

Show child attributesHide child attributes

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 attributesHide child attributes

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.

Example Response

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