Structured filters

Filters are exact conditions on named fields. A request made of filters means the same thing every time you send it. This page lists every field, operator and value format.

Shape

filters is an object with one key, all, which holds a list of conditions. A record must meet every condition in the list.

{
  "filters": {
    "all": [
      { "field": "company.headquarters.country", "operator": "in", "value": ["US"] },
      { "field": "company.employee_count", "operator": "between", "value": [10, 200] },
      {
        "related": {
          "relationship": "open_jobs",
          "where": { "all": [{ "field": "title", "operator": "in", "value": ["SDR"] }] }
        }
      }
    ]
  }
}

A condition is one of two things:

A field condition: { "field", "operator", "value" }.
A related condition: { "related": { "relationship", "where" } }, about the company’s job listings or recent hires.

Conditions are combined with AND. For OR on a single field, list the alternatives in one in condition. Grouping conditions with any or not is not supported.

Operators

Operator	Meaning	Value
`in`	Is any of these	A list of strings. A single string is also accepted.
`matches`	Text describes this	A non-empty string
`eq`	Equals	A number, or a money object
`gt`, `gte`	Greater than, at least	A number, or a money object
`lt`, `lte`	Less than, at most	A number, or a money object
`between`	Within a range, inclusive	A two-item list: `[low, high]`
`within_last_days`	Happened in the last N days	A whole number from 1 to 36500

Each field accepts only the operators listed for it below. Relative windows such as within_last_days are counted from when the search started.

Company fields

Field	Type	Operators	Value
`company.industry`	List	`in`	LinkedIn industry names, case-insensitive: `["Dentists", "Software Development"]`
`company.business_description`	Text	`matches`	What the company does: `"payments infrastructure for lenders"`
`company.headquarters.country`	List	`in`	Two-letter ISO country codes: `["US", "CA"]`. Common country names are accepted and converted.
`company.headquarters.state`	List	`in`	US state names or codes: `["Texas"]` or `["TX"]`. Other regions as written.
`company.employee_count`	Number	`eq` `gt` `gte` `lt` `lte` `between`	`50`, or `[10, 200]`
`company.annual_revenue`	Money	`eq` `gt` `gte` `lt` `lte` `between`	`{ "amount": 1000000, "currency": "USD" }`
`company.total_funding`	Money	`eq` `gt` `gte` `lt` `lte` `between`	`{ "amount": 5000000, "currency": "USD" }`
`company.founded_year`	Number	`eq` `gt` `gte` `lt` `lte` `between`	`2015`, or `[2015, 2020]`
`company.last_funding_date`	Days	`within_last_days`	`180`
`company.last_funding_round`	List	`in`	Round slugs: `["series_a", "series_b"]`
`company.type`	List	`in`	Company types: `["Privately Held"]`
`company.technologies`	List	`in`	Product or vendor names: `["Salesforce", "Snowflake"]`. Matches companies using any of them.

Rules

A list field can appear once per request. Put every value in one in list.
A number or money field can appear more than once. The ranges are intersected: gte 50 and lte 200 together mean 50 to 200. Ranges that cannot both be true are rejected.
Money values use currency: "USD". Other currencies are not supported.
An unknown industry name is rejected with the problem named in details. If an industry is not in the list, describe it with company.business_description or a criterion instead.

Money ranges

For between on a money field, give two money objects:

{
  "field": "company.total_funding",
  "operator": "between",
  "value": [
    { "amount": 5000000, "currency": "USD" },
    { "amount": 50000000, "currency": "USD" }
  ]
}

Company types

Privately Held, Public Company, Nonprofit, Partnership, Self-Employed, Sole Proprietorship, Educational Institution, Government Agency. Case-insensitive.

Funding rounds

All round slugs

angel, pre_seed, seed, series_a, series_b, series_c, series_d, series_e, series_f, series_g, series_h, series_i, series_j, series_unknown, convertible_note, corporate_round, debt_financing, equity_crowdfunding, product_crowdfunding, grant, initial_coin_offering, non_equity_assistance, private_equity, secondary_market, post_ipo_debt, post_ipo_equity, post_ipo_secondary, undisclosed.Natural spellings are normalized: "Series A" becomes series_a.

A related condition asks about records that belong to a company: its job listings or its recent hires. All conditions in where must be true of the same record. For example, one job listing must have both the title and the posting date you asked for.

`open_jobs`

The company has at least one open job that matches.

Inner field	Operator	Required	Value
`title`	`in`	Yes	Job titles
`posted_at`	`within_last_days`	No	Days. Without it, any open job counts, however long ago it was posted.

{
  "related": {
    "relationship": "open_jobs",
    "where": {
      "all": [
        { "field": "title", "operator": "in", "value": ["Sales Development Representative", "SDR"] },
        { "field": "posted_at", "operator": "within_last_days", "value": 30 }
      ]
    }
  }
}

`new_hires`

Someone with a matching title joined the company within the window. Promotions inside the company do not count.

Inner field	Operator	Required	Value
`title`	`in`	Yes	Job titles
`started_at`	`within_last_days`	Yes	Days

{
  "related": {
    "relationship": "new_hires",
    "where": {
      "all": [
        { "field": "title", "operator": "in", "value": ["Chief Revenue Officer", "CRO"] },
        { "field": "started_at", "operator": "within_last_days", "value": 90 }
      ]
    }
  }
}

Each relationship can appear once per request.

“Hiring” and “hired” are different questions. open_jobs finds companies with a vacancy now. new_hires finds companies where someone has already started.

Person fields

People search accepts these fields, plus every company field above. Company fields describe the person’s current employer.

Field	Type	Operators	Value
`person.title`	List	`in`	Job titles: `["VP Sales", "Head of Sales"]`
`person.seniority`	List	`in`	`owner`, `c_suite`, `vp`, `head`, `director`, `manager`, `senior`, `entry`
`person.department`	List	`in`	Functions, such as `sales`, `marketing`, `engineering`, `operations`, `finance`, `product`
`person.location.country`	List	`in`	Two-letter ISO country codes for where the person is
`person.location.state`	List	`in`	State or region where the person is

People search

{
  "filters": {
    "all": [
      { "field": "person.seniority", "operator": "in", "value": ["vp", "c_suite"] },
      { "field": "person.department", "operator": "in", "value": ["sales"] },
      { "field": "company.industry", "operator": "in", "value": ["Software Development"] },
      { "field": "company.employee_count", "operator": "between", "value": [50, 500] }
    ]
  }
}

Related conditions (open_jobs, new_hires) describe the employer and work in people search too: “VPs of sales at companies hiring SDRs”.

Filters and criteria together

Use filters for everything a field can express and criteria for the rest. A search can have up to 10 criteria.

{
  "filters": {
    "all": [
      { "field": "company.industry", "operator": "in", "value": ["Dentists"] },
      { "field": "company.headquarters.state", "operator": "in", "value": ["Texas"] }
    ]
  },
  "criteria": [
    { "text": "independently owned, not part of a dental support organization", "kind": "attribute" }
  ],
  "limit": 20
}

Validation errors

An invalid filter returns 400 invalid_request. details names each problem by its path:

{
  "error": {
    "code": "invalid_request",
    "message": "filters.all.0: unknown field 'company.size'",
    "request_id": "req_8f2a61c09d4e7b3a5f10c2d8",
    "details": [
      { "field": "filters.all.0", "message": "unknown field 'company.size'" },
      { "field": "filters.all.2", "message": "operator 'eq' is not supported for company.industry; use one of: in" }
    ]
  }
}

Message	Fix
`unknown field`	Use a field from this page.
`operator ... is not supported for ...`	Use an operator listed for that field.
`appears more than once`	Merge the values into one `in` list.
`'any' groups are not supported`	Use `all`, with alternatives in an `in` list.

Not sure how to express something? Send it in plain language to Parse and read the filters it produces.

Get started

Concepts

Capabilities

Guides

Shape

Operators

Company fields

Rules

Money ranges

Company types

Funding rounds

`open_jobs`

`new_hires`

Person fields

Filters and criteria together

Validation errors

​Shape

​Operators

​Company fields

​Rules

​Money ranges

​Company types

​Funding rounds

​Related conditions

​open_jobs

​new_hires

​Person fields

​Filters and criteria together

​Validation errors

​Related

Shape

Operators

Company fields

Rules

Money ranges

Company types

Funding rounds

Related conditions

`open_jobs`

`new_hires`

Person fields

Filters and criteria together

Validation errors

Related