prospect/get

Tool: read

list prospects with optional filtering and pagination.

Returns a paginated list of prospects for the authenticated organization. Use email for an exact email-to-ID lookup; use search for name/email fuzzy search. Returns the full prospect object per item; see schemas/prospect.

search does NOT index company — it searches name and email only. To find by company, fetch and filter client-side.

Finding bounced contacts (bounce recipe): 1) detect via bounceCount on campaign/get_by_id; 2) enumerate with this operation's sendingStatus filter (e.g. sendingStatus: "BounceHard", optionally scoped with includeCampaignIds.campaignIds: [<id>]); 3) suppress via blacklist/post_emails. The upstream status param filters CRM status, not sendingStatus — filtering it by BounceHard matches nothing.

To list a campaign's prospects: includeCampaignIds.campaignIds: [100243], or the shorthand campaignId: 100243 for the common single-campaign case. There is no "not enrolled in any campaign" filter — read the account's campaign ids from campaign/get and pass them all to excludeCampaignIds.campaignIds.

sendingActive (on the prospect object) is not enrolment. A prospect not enrolled in any campaign can still read sendingActive: true. To check membership, filter here with includeCampaignIds.campaignIds: [<id>] — that's the membership lookup, not a field on the prospect itself.

Finding your newest prospects (recency recipe): this operation pages oldest-first and has no sort/recency param. To reach prospects you just added: 1) read pagination.totalItems from any page (e.g. page: 1); 2) compute the last page — ceil(totalItems / limit) (pass limit: 30 to minimize round-trips); 3) fetch that page, and the one before it too if a recent insert landed mid-page. search doesn't help here either — see the caveat above, it indexes name/email only, not creation time.

Argument names are literal keys, dots included — pass "includeCampaignIds.campaignIds", not a nested includeCampaignIds object.

Arguments

name	type	req	notes
email	string	–	Exact email match; use for email-to-ID lookup
status	string	–	Filter by CRM status — values: see schemas/prospect. Shares that value list with `sendingStatus` but matches a different field, so send/reply outcomes (`Interested`, `BounceHard`, …) can return 0 items here — filter those with `sendingStatus`
sendingStatus	string	–	Filter by send outcome (e.g. `BounceHard`; values: see schemas/prospect). Runs as a bounded search: each call returns up to `limit` matches (≤ 30) after scanning up to ~5000 prospects, and can take several seconds on large prospect lists; cursor paging only (`startingAfter`, not `page`), and a call may return few or no matches before the data is exhausted — continue with `pagination.nextCursor` until `exhausted: true`. See schemas/pagination
tags	string	–	Filter by tags (comma-separated tag names)
search	string	–	Search name and email (does NOT index company)
validationStatus	string	–	one of: Unvalidated, Valid, Invalid, CatchAll, Disposable, Unknown
includeCampaignIds.campaignIds	array	–	Include only prospects in these campaigns, e.g. `[100957]` — a real array, not a stringified one like `"[100957]"`
includeListIds.listIds	array	–	Include only prospects in these lists, e.g. `[105037]`
excludeCampaignIds.campaignIds	array	–	Exclude prospects in these campaigns; pass every campaign id to approximate "not enrolled in any campaign"
excludeListIds.listIds	array	–	Exclude prospects in these lists
page	integer	–	Page number (1-indexed, default 1)
limit	integer	–	limit default 10, max 30; see schemas/pagination
startingAfter	integer	–	Cursor for next page (prospectId from previous response)

Response

200 — { items: prospect[], pagination }: see schemas/prospect for item fields; see schemas/pagination for pagination shape. Deltas: none.

Errors: 400, 401, 406, 422, 429, 500 — shared schema: schemas/errors.

Invoke

Call read with name: "prospect/get".