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.

{
  "domain": "example.com",
  "radar_type": "company_job_openings",
  "webhook_url": "https://your-webhook.com/endpoint",
  "departments": ["Engineering"],
  "seniorities": ["Senior", "Manager"]
}

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.

{
  "domain": "example.com",
  "radar_type": "company_job_openings",
  "webhook_url": "https://your-webhook.com/endpoint"
  // Will receive all job openings updates
}

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 Valuesb

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

Departments

'Accounting', 'Administrative', 'Business Development', 'Consulting', 'Customer Success', 'Design', 'Education', 'Engineering', 'Finance', 'Human Resources', 'Information Technology', 'Legal', 'Manufacturing', 'Marketing', 'Media and Communication', 'Operations', 'Product Management', 'Project Management', 'Purchasing', 'Quality Assurance', 'Real Estate', 'Research', 'Sales', 'Support'

Seniorities

'Owner', 'CXO', 'Vice President', 'Director', 'Manager', 'Senior', 'Entry', 'Training', 'Partner'

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.

{
  "domain": "ramp.com",
  "radar_type": "company_new_hires",
  "webhook_url": "https://your-webhook.com/endpoint",
  "departments": ["Engineering", "Product Management"],
  "seniorities": ["Senior", "Manager"]
}

Advanced Filtering with `job_titles`

For more granular control, you can filter by job_titles using a boolean query string.

Important: When the job_titles field is used, it overrides any departments or seniorities fields in the same request. You cannot combine job_titles with the other filter fields.

Syntax Rules

Operators: Use AND, OR, and NOT to construct your logic.
Parentheses: Use () for grouping expressions.
Quoted Phrases: Multi-word job titles must be enclosed in double quotes. For example: "Product Manager".

Examples

Simple OR: Find a CEO or a CTO.

"CEO" OR "CTO"

Grouped Logic: Find a Sales Manager or an Account Executive.

("Sales Manager" OR "Account Executive")

Complex Logic with Negation: Find a Lead or Staff Engineer, but exclude anyone with "Manager" in their title.

("Lead Engineer" OR "Staff Engineer") AND NOT "Manager"

Combining Operators: Find a CEO or a Staff Engineer, but exclude any assistant roles.

("CEO" OR "Staff Engineer") AND NOT "Assistant"

This query first finds all records with "CEO" or "Staff Engineer" in the job title. From that result set, it then removes any record where the job title also contains the word "Assistant".

Would Match: Chief Executive Officer, Staff Engineer
Would Be Excluded: Executive Assistant to the CEO, Assistant Staff Engineer

Full Request Example

This request will track job openings for specific senior engineering roles, while explicitly excluding any management positions.

{
  "domain": "stripe.com",
  "radar_type": "company_job_openings",
  "webhook_url": "https://your-webhook.com/endpoint",
  "job_titles": "(\"Staff Engineer\" OR \"Principal Engineer\") AND NOT (\"Manager\" OR \"Director\")"
}

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.