Skip to main content
Persona-based filtering allows you to receive only the most relevant records for your needs. By specifying filters when creating a radar, you can narrow down the data sent to your webhooks (or available via GET /v1/updates), reducing noise and focusing on the signals that matter most.
Note: webhook_url is optional in all examples below. Omit it to create a poll-only radar.
Filtering is supported for the following radar types:
  • company_new_hires
  • company_job_openings
  • company_promotions
  • company_social_posts_cxo
For other radar types, the filter fields (departments, seniorities, job_titles) will be ignored.

​
How to Use Filters

To apply a filter, include the filter fields directly in the body of your POST /v1/radars/companies request.
If you omit the filter fields (departments, seniorities, job_titles), TAMradar will return all updates without any filtering. This is useful when you want to receive all events for a given radar type.

​
Filtering by Department and Seniority

You can filter records by departments and/or seniorities.
  • departments: An array of strings specifying the departments to include.
  • seniorities: An array of strings specifying the seniority levels to include.
When you provide both departments and seniorities, they are combined with AND logic. A record must match at least one value from each specified filter (departments AND seniorities) to be included. If you provide only one key (e.g., only departments), only that filter will be applied.

​
Accepted Values

You must use one of the predefined values for these fields.

​
Departments

Note: Other is an output-only value returned by the classifier when no specific department matches. It cannot be used as a filter value.

​
Seniorities

Note: Other is an output-only value returned when no seniority matches. It cannot be used as a filter value.

​
Example: Department & Seniority

This request will create a radar that only sends webhook notifications for new hires who are at the Senior or Manager level within the Engineering or Product Management departments.

​
Advanced Filtering with job_titles

Use job_titles to filter results with a Boolean expression. Important: When job_titles is provided, it takes precedence over departments and seniorities. Those fields do not affect matching, so we recommend omitting them.

​
Matching types

Quotes mean containment: "Sales Operations" matches Senior Sales Operations Manager, but not Sales and Operations Manager. EXACT("Sales Operations Manager") matches only that complete normalized title, regardless of case. It does not match Senior Sales Operations Manager and does not expand aliases: EXACT("CEO") does not match Chief Executive Officer.

​
Boolean operators

Use OR for alternatives, AND to require multiple conditions, and NOT to exclude the term or group that follows it. AND NOT is AND followed by NOT, not a separate operator. One practical way to build a query is in three layers:
  1. Choose seniorities or leadership terms: (VP OR director OR manager OR head)
  2. Choose departments or roles: (marketing OR sales OR "revenue operations")
  3. Add exclusions: NOT (junior OR assistant)
Combine the layers with AND:
In plain language, this query says:
  • The title must match VP, director, manager, or head.
  • It must also match marketing, sales, or the phrase revenue operations.
  • It must not match junior or assistant.
If you already know the titles you want, list them directly with OR:
Because these are quoted phrases, they use containment. For example, "Marketing Manager" also matches Senior Marketing Manager. Use EXACT("Marketing Manager") when only the complete title should match. Standalone exclusions such as NOT interim are also valid. The API evaluates NOT, then AND, then OR, but we recommend parentheses whenever you mix operator types.

​
Syntax rules

  • Operators (AND, OR, NOT) must be uppercase. For example, use CEO OR CTO; CEO or CTO returns HTTP 400.
  • Single-word terms may be unquoted: CEO, lead, sales.
  • Multi-word phrases must use double quotes: "Marketing Manager", "Head of Product". Unquoted multi-word input returns a 400 error.
  • Phrase matching is containment, not exact equality: "Marketing Manager" matches Senior Marketing Manager and Marketing Manager, EMEA, but not Marketing Operations Manager.
  • EXACT must be uppercase and must contain exactly one double-quoted title: EXACT("Marketing Manager").
  • Matching is case-insensitive for title terms. Boolean operators and EXACT must still be uppercase.
  • Operator precedence: NOT binds tightest, then AND, then OR. Use parentheses whenever you mix different operator types to make intent explicit.
  • Each term must contain at least two searchable characters and may contain at most 100 characters.
  • The complete expression may contain at most 9,000 characters, with up to 32 nested Boolean groups.

​
Invalid expressions

These expressions return a validation error:

​
Request example

​
Validation behavior

Malformed job_titles expressions submitted through POST /v1/radars/companies return HTTP 400 with a job_titles error explaining what to correct. Bulk submissions are asynchronous. A structurally valid POST /v1/radars/bulk request is initially accepted with HTTP 202. If an item contains a malformed expression, the bulk processor later records an item-level failure with code 400 and a job_titles error.

​
Validation

All filter fields and values are validated upon submission. If your request contains invalid field values, unknown field names, or incorrectly formatted values, you will receive a 400 Bad Request response with a detailed error message explaining the issue. For more information about error responses, see our Error Handling guide. For detailed information about the API endpoint and request/response formats, see our Create Radar API Reference.