List Accounts
The accounts your network reaches, with their heat and fit
is_excluded is true only in the moments after you exclude its company,
until the list catches up.
Heat and fit are two different questions
Heat is timing: is anything happening at this account? Fit is quality: is this the kind of account you want? Neither moves the other. A coldA+ is a
good account nobody is talking to; a burning D is activity at an account
outside your targeting. Rank on both, which is what the default order does:
heat first, then fit, then the latest signal.
Heat
temperature is one of four bands. A signal is a LinkedIn engagement or a
CRM activity (email, call, meeting, note) at the account.
cold. The band
is worked out when you read it, so an account cools on its own as its last
signal ages, without waiting for a refresh.
The evidence ships with the band:
last_signal_at: the latest signal from either source.last_signal_source:linkedinorcrm.last_signal_type: the engagement or CRM activity type of that signal, when known.signals_30d: how many signals landed in the last 30 days, both sources.has_open_deal: an open CRM deal is resolved to this account.
The grade
fit_grade is A+ to D, and it is the fraction of your configured
criteria this account meets, banded:
unknown.
fit_score is not comparable across workspaces. It is a fraction of what
that workspace configured, so 0.8 on a workspace with four criteria and 0.8
on one with one criterion are not the same claim. Compare grades within a
workspace, never between.fit_reasons ships with the grade and names what scored: the matched ICP’s
title, then each criterion met (["Mid-market SaaS", "Target account", "Tier 1", "Industry"]). Nothing downstream has to reconstruct the reasoning.
fit_breakdown goes further: every configured criterion, met or not, with the
points it is worth and the points the account earned. fit_score is the earned
points over the points available.
When a grade changes
A grade is refreshed by the change that affects it:- Change your targeting (a tier set on an account, an ICP edited, a tier added or reordered) and the affected grades are recomputed on that request. Set a tier with Set Account State.
- New accounts your network reaches are graded at the next refresh of your accounts, along with anything whose targeting inputs moved with it. That is also when a change to the target list reaches the grade, because whether an account is a target is part of that refresh.
Which id to use
Each row carriesclustr_account_id, the account’s Clustr ID. Use it wherever a
route asks for an account, including Set An Account’s Tags
and Set Account State.
The row also keeps two earlier ids for integrations built before Clustr IDs, and they are not
interchangeable: id is the company’s LinkedIn numeric id, and company_id is the id the tag and
account state routes took.
A row’s tags are the account’s tags, each carrying the group_id of
the field it came from.
Competitor activity
With the Competitor Monitoring add-on, an account a watched competitor has touched carriescompetitor_activity: the
same object the Accounts table’s Competitors columns read. It is absent when no
competitor has engaged a counted person at the account, and on every row
without the add-on.
competitor (any, or competitor ids), competitor_pressure
(hot, warming, active, cooling, dormant, none),
competitor_last_touch (7d, 30d, 90d, older, never),
competitor_side (defense, attack), competitor_active_days and
competitor_pitch_days. Sort on it with sort=lastCompetitorActivity,
lastCompetitorPitch, competitorPitches or pressure_path (competitor
pressure times the best path’s strength); accounts no competitor touched sort
last. Without the add-on, these filters and sorts answer 403.
Last CRM activity
The latest activity logged in your CRM against the account’s contacts:last_crm_activity_type: its type (EMAIL,CALL,MEETING, …).last_crm_activity_at: when it happened.last_crm_activity_provider: the CRM it was logged in,hubspotorsalesforce.crm_activity_count: how many activities are logged in all.
Smaller rows with include
Leave include out and every row is whole, as it has always been. When you only
need the flat fields (name, domain, heat, fit grade, counts, the warmest
connector), send include=none for the base row alone, or name the heavy parts
you want back, comma-separated:
null. An unknown value is a
400 that lists the allowed ones.
Paging
Pages arepage_size rows (default 50, at most 200). has_more is true while
another page exists; there is no total count.
Authorizations
Headers
Query Parameters
heat (default): hottest first, then best fit, then latest signal.
fit: best grade first. path: warmest entry path first. recency:
latest LinkedIn or CRM signal first. With Competitor Monitoring:
lastCompetitorActivity (latest competitor touch first),
lastCompetitorPitch (latest pitch first), competitorPitches
(most pitches in 30 days first) and pressure_path (competitor
pressure times the best path's strength); accounts no competitor
touched sort last. order flips any of them.
Best path strength bands to keep, each written low-high on the 0 to
1 scale of best_strength: 0-0.25 (weak), 0.25-0.5 (fair),
0.5-0.75 (good) and 0.75-1 (strong). A band starts at its low
value and runs up to its high value, and a band ending at 1 includes
a perfect score. Repeat the parameter for several; an account in any
band is kept.
Deprecated: a tag filter. Former status ids (uuid) are translated
through the status -> tag map into the account tags they became; the
literal none means no account tag and
composes with ids ("New or X"). Equivalent to tag / tag_group_empty.
Repeatable, or one comma-separated value; OR-within. Anything else is a 400.
Narrow to accounts that are a STRONG match for one of these Company ICPs, by ICP id (uuid). Repeatable, or one comma-separated value; OR-within. A non-uuid value is a 400.
Not the same filter as icp_fit: that one asks whether the account is
strong (or partial, or neither) for ANY of the tenant's ICPs, which is a
superset. This one names the ICP, and is what the ICP · <title> view
means. Both compose, and both are honoured by /v2/accounts/counts.
Narrow to accounts in one of these heat bands. A signal is a LinkedIn
engagement or a CRM activity. burning (an open CRM deal, or a signal in
the last 14 days and another within 30), warm (a signal in the last 30
days), cool (a signal in the last 90 days), cold (otherwise; path
strength does not count). Repeatable, or one comma-separated value;
OR-within. Unknown values match nothing.
any: accounts a watched competitor has touched. Competitor ids (uuid):
accounts one of THESE competitors has touched, as the Competitors column
shows them. any with ids is any. Repeatable, or one comma-separated
value; OR-within. Any other value is a 400; without the Competitor
Monitoring add-on, a 403.
Accounts that are a customer of a watched competitor (Confirmed or Likely, not
rejected), as the Customer of column shows them: any, or competitor ids (uuid).
Repeatable, or one comma-separated value; OR-within. Any other value is a 400;
without the Competitor Monitoring add-on, a 403.
The Renewal date column: the date entered on the competitor customer, else the start of
its estimated window. passed, 90d, 180d, 365d (within the next 3, 6 or 12
months) or later. Repeatable, or one comma-separated value; OR-within. Any other
value is a 400; without the Competitor Monitoring add-on, a 403.
Accounts by when a competitor last engaged someone there (the Last touch
column): 7d, 30d, 90d (within that many days; the windows overlap),
older (over 90 days), never (no competitor activity). Repeatable, or
one comma-separated value; OR-within. Any other value is a 400; without
the Competitor Monitoring add-on, a 403.
Optional. Leave it out for the full row, as before. Name the heavy parts you want back, comma-separated, or none for the base row alone.
top_connectors: the row's best connectors, each with photo, title, strength and the path through.connectors: every connectorconnector_countcounts, by id and name.crm_activities: the account's recent CRM activities.crm_activity_countand the last activity's type and date stay on the base row.fit_breakdown: every criterion behindfit_grade, met or not.
none, top_connectors, connectors, crm_activities, fit_breakdown Response
Typed result envelope. Each row also carries temperature
(burning | warm | cool | cold), the heat band the temperature
parameter filters on. The envelope carries updating: true while
a settings change is being applied in the background: the rows are
the previous numbers until it finishes. Omitted otherwise.
It carries next_cursor whenever a further page exists: pass it back
as cursor for the next page. Omitted on the last page.