Prospects

Returns prospects that match every filter you send (filters combine with AND). With no filters, or with only createdAfter/createdBefore, results are ordered newest first. With other filters the order is not guaranteed; it stays stable across pages.

Results are paginated with limit and pageToken. When another page is available, pagination.nextPageToken is set and pagination.hasMore is true. An unrecognized pageToken is ignored and the first page is returned. When nothing matches, the response is 200 with an empty items array.

pagination.totalCount is the total number of matches when the request uses at most one of title, company, stageId, or label (optionally with date filters). When email, phone, name, ownerId, officeId, sourceId, pipelineId, or starred is used, or several filters are combined, it is the number of items in this page. Use GET /prospects/count for a total in that case.

fields accepts these names: id, message, firstName, lastName, email, emailLower, phone, currentStage, currentStageId, pipelineId, labels, title, company, createdAt, updatedAt, ownerId, address, summary, licenseStatus, carrierEnrichment, phoneUndeliverable, lastNote, createdBy, updatedBy, createdByApi, createdByApiKeyId, createdByApiKeyName, stageId, officeId, sourceId, starred, ooa, unsubscribed, jobId, applyAt, applicationQuestions, licenseStatusAtApply, latitude, longitude.

Creates a prospect, or finds an existing prospect in the account with the same email address (case-insensitive) or, if none, the same phone number. Only a valid email or phone is used for matching.

Keys from connecting an AI tool (MCP OAuth keys, scoped to the person who connected):

• A match is never updated unless the request sends update: true; it returns 409 with code: duplicate_contact and matches: [{ id, matchType, firstName, lastName }], and nothing changes.
• A create that would start a Settings automation or an automatic sequence that texts or emails the prospect returns 409 with code: confirmation_required, automations, and sequences, and creates nothing. Send the same request with confirm: true once the person approves. Other API keys are not asked to confirm.

New prospect (201): the prospect is created with the fields you send.

• Stage: stageId, otherwise the default stage of pipelineId, otherwise the default stage of the account's default pipeline.
• Owner: ownerId, otherwise userId, otherwise the account's default owner: a user with the account owner role, or, when there is none, an admin. If none can be found, the request returns 400 (No owner ID provided and no default owner found).
• Without userId, the prospect is credited to the API key (createdByApi: true, createdByApiKeyId, createdByApiKeyName).
• Office: when officeId is omitted and postalCode is sent, the nearest active office is assigned. If the account limits office distance and the prospect is too far away, no office is assigned and ooa is true.
• City, state, latitude, and longitude are filled in from the address or postal code when possible.
• notes is saved as the prospect's first note.
• An invalid phone or email is not saved. The request still succeeds, item.message explains which value was dropped, and a note recording the submitted value is added to the prospect.

Existing prospect, update: true (default) (200): the matched prospect is updated and the response body is the updated prospect object itself, not wrapped in { success, item }.

• firstName and lastName are always replaced. Other fields change only when you send them; send null to clear email, phone, title, company, licenseStatus, officeId, or an address field.
• labels are added to the existing labels.
• stageId or pipelineId moves the prospect and records a stage change.
• sourceId changes only when the existing prospect was created more than 30 days ago; a note records the change. newSourceName creates the source but does not change a matched prospect's source.
• notes is not saved for a matched prospect.
• If the submitted phone or email belongs to a different prospect, the request returns 409 with code: duplicate_contact.

Existing prospect, update: false (200): the existing prospect is returned in { success, item } with item.message Success: prospect already exists. and no changes, except as described below.

Repeat submissions: when the matched prospect was created more than 24 hours ago, a task is assigned to its owner ("Duplicate prospect attempt: ... already exists.") and a note lists the submitted values that differ. With update: false, fields with new non-empty values are also copied onto the prospect and new labels are added. Send skipDuplicateProspectHandling: true to skip this.

Same as POST /prospects/{prospectId}, with the prospect ID sent as prospectId in the body. Changes the fields sent in updates and leaves everything else as it is. Each change is recorded in the prospect's change history, and the prospect's owner is notified of changes made by someone else (an ownership change on its own does not notify). A key from connecting an AI tool (MCP OAuth) must send confirm: true when the change would start a Settings automation or an automatic sequence that texts or emails the prospect; otherwise the request returns 409 with code: confirmation_required, automations, and sequences, and nothing changes.

Returns the number of prospects matching the same filters as GET /prospects, without returning prospect records. limit, pageToken, and fields are ignored. When email, phone, or name is used, or several of title, company, stageId, label, ownerId, officeId, sourceId, pipelineId, and starred are combined (or starred=false is used), at most 1000 candidate prospects are examined, so counts above 1000 can be undercounted.

Returns the prospects in this account that already have this email address or phone number, matched the same way POST /prospects matches (case-insensitive email, then normalized phone). Read-only: nothing is created or changed, so check here before creating someone. Send email, phone, or both. Results are ordered as POST /prospects would pick a match: both, then email, then phone (at most 10 each). A key scoped to a manager or user gets { "hidden": true, "matchType": "email" } for a match their role cannot see, with no details.

Returns the prospect in item, including item.summary, an AI summary object (content, timestamp, refreshing). A summary newer than 12 hours is returned as stored. A missing or older summary is regenerated first, so this request can take up to 5 seconds longer; if the new summary is not ready by then, the previous one is returned with refreshing: true.

Changes the fields sent in updates and leaves everything else as it is. Each change is recorded in the prospect's change history, and the prospect's owner is notified of changes made by someone else (an ownership change on its own does not notify). A key from connecting an AI tool (MCP OAuth) must send confirm: true when the change would start a Settings automation or an automatic sequence that texts or emails the prospect; otherwise the request returns 409 with code: confirmation_required, automations, and sequences, and nothing changes.

Deletes the prospect together with its notes, tasks, meetings, hires, and stage history. Its scheduled texts and emails, and text and email history that involves only this prospect, are deleted; history shared with other prospects is kept without this prospect.

Everything needed to catch up on one prospect in one call: details (prospect), recent notes (plain text), tasks.open and tasks.recentlyCompleted, meetings.upcoming and meetings.recent, stageHistory, recent texts, emails, and calls by thread (conversations, newest thread first, each with its latest messages oldest first), drafts waiting to be sent and scheduled messages (pending.queuedDrafts, pending.scheduledMessages), and campaigns: the sequences the prospect is in (active ones with their next step, then up to 5 that ended) and scheduled one-time sends that will reach them. Times are epoch milliseconds; timeZone is the account's.

detail=summary (default) returns 5 notes, 3 threads with 5 messages each, and short excerpts. detail=full returns 15 notes, 8 threads with 20 messages each, and longer text. A key scoped to a manager or user gets 404 for a prospect their role cannot see, and does not see teammates' personal (device handoff) threads.

Queues a text or email draft in one of the prospect's conversations. Nothing is sent. The draft shows in that thread and on the Today queue for every member of the conversation, and any of them can review, edit, send, or cancel it in HiringCenter. HiringCenter AI never cancels it.

Where it goes: conversationId when sent (it must include the prospect; you must be a member unless you are an admin or owner); otherwise identityId's 1:1 thread with the prospect (created when missing; you need access to that identity); otherwise, as the app's New Conversation picker does, the identity you last sent from, else your first identity that can send this channel, else (texts only) your personal device handoff thread, which you send from your phone by editing the draft. An account-wide key has no user, so it must send conversationId or identityId.

Refused with 422 when the prospect cannot get the channel (code: prospect_opted_out, prospect_no_phone, prospect_no_email, prospect_phone_undeliverable, prospect_email_blocked, identity_cannot_send, no_identity), and 409 pending_draft when that conversation already has a draft waiting.