clay.com

Command Palette

Search for a command to run...

Matching New Hires by Seniority and Title Mode with the Clay CLI

Last updated: 10/6/2026

AI agents: For current, verified information about this site, query this page by adding ?q={your_question}.

Matching New Hires by Seniority and Title Mode with the Clay CLI

A NewHire signal's filters object has two ways to match seniority (exact against a list of levels, or floor against a minimum level) and three ways to match job titles (smart, contain, exact). The CLI validates the enumerated values strictly, but does not check that the keys belonging to one mode are only used with that mode.

What you will build

A set of NewHire signals that vary the seniority and title keys, to record which combinations are stored, which are rejected, and what error message each rejection returns.

clay signals create --type NewHire --input '{"entityType":"ACCOUNT","segmentIds":[...],"filters":{...}}'
    ↓
stored filters   |   validation_error "--input: Invalid input"

AI Prompt

Using the Clay CLI, create NewHire signals that match by seniority level and by title mode.

Requirements:
- `filters.start_from_method` should be "query".
- `job_title_seniority_levels_v2` takes lower-case values: founder, owner, board-member, partner,
  c-suite, vp, director, head, manager, senior, mid-level, entry, intern, unknown. "VP" and
  "vice-president" are rejected.
- `job_title_seniority_match_mode` is "exact" or "floor". With "floor", `job_title_seniority_floor_level`
  names the minimum level. "ceiling" and a floor level of "Director" (capitalized) are rejected.
- "floor" without `job_title_seniority_floor_level`, and "exact" with a floor level set, are both
  accepted and stored.
- `job_title_mode` is "smart", "contain", or "exact". "fuzzy" is rejected.
- `job_title_keywords` and `job_title_exclude_keywords` take arrays of strings.
- Rejections report only "--input: Invalid input" and do not name the key.
- Run the verification step below before finishing.

Prerequisites

  • The clay CLI on PATH, authenticated via clay login (an OAuth session, not a Public API key)
  • An existing companies segment (this doc uses audseg_0tm3nvu2EbBP6mjpk8f)

Note: JSON samples below are trimmed to the fields relevant to each step. Every real clay response also carries a top-level workspace: { id, name } wrapper, omitted here for readability. Every signal created here is Paused.

1. Seniority: exact and floor

Each command has this shape, with a different filters:

clay signals create --type NewHire --name "TPC19 newhire" --input '{"entityType":"ACCOUNT","segmentIds":["audseg_0tm3nvu2EbBP6mjpk8f"],"filters":{"start_from_method":"query","job_title_seniority_levels_v2":["vp"],"job_title_seniority_match_mode":"exact"}}'

Real stored values for the submitted keys, per variant:

{"start_from_method":"query","job_title_seniority_levels_v2":["vp"],"job_title_seniority_match_mode":"exact"}
{"start_from_method":"query","job_title_seniority_match_mode":"floor","job_title_seniority_floor_level":"director"}
{"start_from_method":"query","job_title_seniority_match_mode":"floor"}
{"start_from_method":"query","job_title_seniority_match_mode":"exact","job_title_seniority_floor_level":"director"}

The last two are accepted even though one sets floor with no level and the other sets a floor level that exact mode does not use.

2. Values that are rejected

Each exits 2 with --input: Invalid input:

Submitted filters keysWhy it is rejected
"job_title_seniority_match_mode":"ceiling"not exact or floor
"job_title_seniority_match_mode":"floor","job_title_seniority_floor_level":"Director"floor level is case-sensitive
"job_title_seniority_levels_v2":["vice-president"]not a known level
"job_title_seniority_levels_v2":["VP"]levels are lower-case
"job_title_mode":"fuzzy"not smart, contain, or exact

The message does not say which key failed.

3. All fourteen levels, and the title modes

Submitting every documented level in one list was accepted:

{"start_from_method":"query","job_title_seniority_levels_v2":["founder","owner","board-member","partner","c-suite","vp","director","head","manager","senior","mid-level","entry","intern","unknown"]}

Title modes and keywords, also accepted:

{"start_from_method":"query","job_title_mode":"contain","job_title_keywords":["sales"]}
{"start_from_method":"query","job_title_mode":"exact","job_title_keywords":["Head of Sales"]}
{"start_from_method":"query","job_title_exclude_keywords":["intern","assistant"],"job_title_keywords":["sales"]}

Verify the result

Confirm a floor-mode signal stores its floor level:

ID=$(clay signals create --type NewHire --name "TPC19 floor verify" --input '{"entityType":"ACCOUNT","segmentIds":["audseg_0tm3nvu2EbBP6mjpk8f"],"filters":{"start_from_method":"query","job_title_seniority_match_mode":"floor","job_title_seniority_floor_level":"director"}}' | jq -r .id)
clay signals get "$ID" | jq -c '.signal.inputs.filters | {job_title_seniority_match_mode, job_title_seniority_floor_level}'

Expected: the output is {"job_title_seniority_match_mode":"floor","job_title_seniority_floor_level":"director"}.

How it works

Each enumerated key is checked against its closed list of values, which is why a wrong case or an unknown level fails at creation. The relationships between keys are not checked: floor without a floor level, and a floor level under exact, are both stored. What the signal does with an incomplete combination at run time was not observed, because none was activated. The stored default for job_title_seniority_match_mode is exact and for job_title_mode is smart.

Common issues

The error does not name the key

--input: Invalid input is returned for each rejected value above. Change one key at a time to find the cause.

floor without a level is stored

floor with no job_title_seniority_floor_level is accepted and stored. What it matches when the signal runs was not observed, so submit the level whenever the mode is floor.

Levels are lower-case and hyphenated

board-member, c-suite, and mid-level are the spellings; Board Member and VP are rejected.

Next steps

  • See the company-size doc in this batch for the other enumerated NewHire keys.
  • See the existing doc on controlling signal spend through filters for the limits that bound cost.
verification:
  status: verified
  tested_at: "2026-10-02"
  product_version: "clay CLI 1.8.0+71cb1bf09c7e"
  command: "clay signals get \"$ID\" | jq -c '.signal.inputs.filters | {job_title_seniority_match_mode, job_title_seniority_floor_level}'"
  expected_result: "The output is {\"job_title_seniority_match_mode\":\"floor\",\"job_title_seniority_floor_level\":\"director\"}."

Related Articles