HiringCenter API

Prospects

Endpoint:https://api.hiringcenterpro.com/v2

Create, update, list, and manage prospects

List Prospects

GET

https://api.hiringcenterpro.com/v2

/prospects

Accepts optional query filters, returns matching prospects, and includes a consistent list envelope with pagination metadata. Results are paginated with limit and pageToken; responses include pagination.nextPageToken when another page is available. When no matches are found, returns 200 with an empty items array and pagination.totalCount: 0. When multiple labels are provided, results include prospects that match any of those labels. Date filters apply to prospect createdAt.

List Prospects › query Parameters

emailstring
Example: avery.coleman@example.com
phonestring
Example: +15551234567
namestring
Example: Avery Coleman
titlestring
Example: Sales Manager
companystring
Example: Northwind Health
stageIdstring
Optional. Filter prospects by stage ID. Same identifier used on create/update and returned on prospect responses as stageId.
Example: 9a3d7c1e4b2f48d6a5c0e1f9b7d2a346
labelstyle: form · explode: true
Optional. Filter by label(s). Supports repeated query params (?label=Hot&label=Inbound) or a comma-separated value (?label=Hot,Inbound). Matches prospects that contain any provided label. Up to 10 labels.
createdAfter
Optional lower bound for prospect createdAt as Unix epoch milliseconds (integer) or ISO 8601 date string.
createdBefore
Optional upper bound for prospect createdAt as Unix epoch milliseconds (integer) or ISO 8601 date string.
limitinteger · max: 1000
Example: 25
Default: 25
pageTokenstring
Opaque pagination token returned from a prior GET /prospects response.
Example: eyJpZCI6InByb3NwZWN0XzAxSFY2VzhGSjJQN1IyTTVUOVkxUTRDIn0=
fieldsstring
Optional comma-separated list of top-level field names to include in each list item. Use this to reduce response payload size for large list requests. id is always included when present on the source document. Nested paths are not supported. Unknown field names or invalid syntax (for example nested selectors) return HTTP 400 with invalidFields and/or invalidSyntax in the error body.
Example: id,prospectId,hireDate

List Prospects › Responses

successboolean · required
itemsobject[] · required
paginationobject · required
Pagination metadata. Fields are included only when that resource supports them.
Example: {"nextPageToken":"opaque-page-token-example","hasMore":true,"totalCount":125}

Create or Update Prospect

POST

https://api.hiringcenterpro.com/v2

/prospects

Creates a new prospect, or matches an existing one by email or phone. update defaults to true. When a match is found and update is enabled, the existing prospect is updated with the fields you send. Omitted fields are left as-is; send null to clear a supported field. Set update to false if you only want to look up the existing record without changing it. For address fields (streetAddress, city, state, postalCode), only the fields you include are updated; omitted address fields are preserved. If phone is invalid, the request can still succeed; the response may include a warning in message and phone may be null.

Create or Update Prospect › Headers

X-Idempotency-Keystring · maxLength: 512
Optional. Client-generated key used to make mutation retries safe. Reuse the same key only when retrying the exact same request.
Example: idem_prospect_create_01HV6W0J7Y7A5Q3T4J6N8M2P

Create or Update Prospect › Request Body

firstNamestring · required
Prospect first name.
lastNamestring · required
Prospect last name.

updateboolean
Defaults to true. When true and a prospect already exists (matched by email or phone), that prospect is updated with the submitted fields. When false, the existing prospect is returned without applying changes. Omitted fields are preserved on update; send explicit null to clear supported fields.
Default: true
emailstring | null · email
Prospect email address. When updating a matched prospect, send null to clear the email.
phonestring | null
Prospect phone number. When updating a matched prospect, send null to clear the phone.
stageIdstring
Stage ID to place the prospect in. When provided, this takes precedence over pipelineId. Use the same stageId to filter GET /prospects and GET /prospects/count.
pipelineIdstring
Optional pipeline ID used only when stageId is omitted. The prospect is routed to that pipeline's configured default stage.
licenseStatusstring | null · enum
License status for the prospect. When updating a matched prospect, send null to clear the license status.
Enum values:
not_started
in_progress
licensed
labels
Optional labels to attach to the prospect. Accepts either a comma-separated string or an array of strings.
notesstring
Optional plain-text notes for the prospect profile.
titlestring | null
Prospect job title. When updating a matched prospect, send null to clear the title.
companystring | null
Prospect company name. When updating a matched prospect, send null to clear the company.
userIdstring
User id performing the create/update operation.
streetAddressstring | null
Prospect street address. When updating a matched prospect, send null to clear this address field.
citystring | null
Prospect city. When updating a matched prospect, send null to clear this address field.
statestring | null
Prospect state or region. When updating a matched prospect, send null to clear this address field.
postalCodestring | null
Prospect postal/zip code. When updating a matched prospect, send null to clear this address field.
officeIdstring | null
Optional office id to associate with the prospect. When updating a matched prospect, send null to clear the office association.
sourceIdstring | null
Existing source id to associate with the prospect. For matched-prospect updates, source changes are restricted by existing business rules; send null only when intentionally clearing an eligible source.
newSourceNamestring
New source name to create/use when sourceId is not provided.
resumeobject
Optional resume payload for parsing and storage.
muteWebhookboolean
If true, suppresses outbound webhook notifications for this write.
jobIdstring
Optional job id. When provided, links the prospect to a job and records an apply timestamp.
applicationQuestionsobject[]
Optional job application question responses (label, answer, and optional type/id per item).

Create or Update Prospect › Responses

Existing prospect returned or updated

successboolean · required
itemobject · required
Example: {"id":"c1a7e9d34b8f4c2aa6d15e0f7b3c9d42","message":null,"firstName":"Avery","lastName":"Coleman","email":"avery.coleman@example.com","phone":"+15551234567","currentStage":"New Lead","stageId":"9a3d7c1e4b2f48d6a5c0e1f9b7d2a346","pipelineId":"3d9a1c7e4b2f46d8a5c0e1f9b7d2a348","labels":["Hot","Inbound"],"title":"Sales Manager","company":"Northwind Health","createdAt":1717000000000,"updatedAt":1717003600000}

Count Prospects

GET

https://api.hiringcenterpro.com/v2

/prospects/count

Returns only the count of prospects matching the same optional filters as GET /prospects, without returning prospect documents. Date filters apply to prospect createdAt. limit and fields are ignored.

Count Prospects › query Parameters

emailstring
Example: avery.coleman@example.com
phonestring
Example: +15551234567
namestring
Example: Avery Coleman
titlestring
Example: Sales Manager
companystring
Example: Northwind Health
stageIdstring
Optional. Filter prospects by stage ID. Same identifier used on create/update and returned on prospect responses as stageId.
Example: 9a3d7c1e4b2f48d6a5c0e1f9b7d2a346
labelstyle: form · explode: true
Optional. Filter by label(s). Supports repeated query params or a comma-separated value. Up to 10 labels.
createdAfter
Optional lower bound for prospect createdAt as Unix epoch milliseconds (integer) or ISO 8601 date string.
createdBefore
Optional upper bound for prospect createdAt as Unix epoch milliseconds (integer) or ISO 8601 date string.

Count Prospects › Responses

successboolean · required
countinteger · required

Get Prospect by ID

GET

https://api.hiringcenterpro.com/v2

/prospects/{prospectId}

Accepts a required prospectId path parameter, fetches that specific prospect, and returns it in item when found.

Get Prospect by ID › path Parameters

prospectIdstring · required
Example: c1a7e9d34b8f4c2aa6d15e0f7b3c9d42

Get Prospect by ID › Responses

successboolean · required
itemobject · required
Example: {"id":"c1a7e9d34b8f4c2aa6d15e0f7b3c9d42","message":null,"firstName":"Avery","lastName":"Coleman","email":"avery.coleman@example.com","phone":"+15551234567","currentStage":"New Lead","stageId":"9a3d7c1e4b2f48d6a5c0e1f9b7d2a346","pipelineId":"3d9a1c7e4b2f46d8a5c0e1f9b7d2a348","labels":["Hot","Inbound"],"title":"Sales Manager","company":"Northwind Health","createdAt":1717000000000,"updatedAt":1717003600000}

Delete Prospect

DELETE

https://api.hiringcenterpro.com/v2

/prospects/{prospectId}

Accepts a required prospectId and deletes the matching prospect.

Delete Prospect › path Parameters

prospectIdstring · required
Example: c1a7e9d34b8f4c2aa6d15e0f7b3c9d42

Delete Prospect › Headers

X-Idempotency-Keystring · maxLength: 512
Optional. Client-generated key used to make mutation retries safe. Reuse the same key only when retrying the exact same request.
Example: idem_prospect_create_01HV6W0J7Y7A5Q3T4J6N8M2P

Delete Prospect › Responses

Deleted

successboolean · required
messagestring · required

Auth Notes

List Prospects

GET

https://api.hiringcenterpro.com/v2

/prospects

List Prospects › query Parameters

emailstring
Example: avery.coleman@example.com
phonestring
Example: +15551234567
namestring
Example: Avery Coleman
titlestring
Example: Sales Manager
companystring
Example: Northwind Health
stageIdstring
Optional. Filter prospects by stage ID. Same identifier used on create/update and returned on prospect responses as stageId.
Example: 9a3d7c1e4b2f48d6a5c0e1f9b7d2a346
labelstyle: form · explode: true
Optional. Filter by label(s). Supports repeated query params (?label=Hot&label=Inbound) or a comma-separated value (?label=Hot,Inbound). Matches prospects that contain any provided label. Up to 10 labels.
createdAfter
Optional lower bound for prospect createdAt as Unix epoch milliseconds (integer) or ISO 8601 date string.
createdBefore
Optional upper bound for prospect createdAt as Unix epoch milliseconds (integer) or ISO 8601 date string.
limitinteger · max: 1000
Example: 25
Default: 25
pageTokenstring
Opaque pagination token returned from a prior GET /prospects response.
Example: eyJpZCI6InByb3NwZWN0XzAxSFY2VzhGSjJQN1IyTTVUOVkxUTRDIn0=
fieldsstring
Optional comma-separated list of top-level field names to include in each list item. Use this to reduce response payload size for large list requests. id is always included when present on the source document. Nested paths are not supported. Unknown field names or invalid syntax (for example nested selectors) return HTTP 400 with invalidFields and/or invalidSyntax in the error body.
Example: id,prospectId,hireDate

List Prospects › Responses

successboolean · required
itemsobject[] · required
paginationobject · required
Pagination metadata. Fields are included only when that resource supports them.
Example: {"nextPageToken":"opaque-page-token-example","hasMore":true,"totalCount":125}

Create or Update Prospect

POST

https://api.hiringcenterpro.com/v2

/prospects

Create or Update Prospect › Headers

X-Idempotency-Keystring · maxLength: 512
Optional. Client-generated key used to make mutation retries safe. Reuse the same key only when retrying the exact same request.
Example: idem_prospect_create_01HV6W0J7Y7A5Q3T4J6N8M2P

Create or Update Prospect › Request Body

firstNamestring · required
Prospect first name.
lastNamestring · required
Prospect last name.

updateboolean
Defaults to true. When true and a prospect already exists (matched by email or phone), that prospect is updated with the submitted fields. When false, the existing prospect is returned without applying changes. Omitted fields are preserved on update; send explicit null to clear supported fields.
Default: true
emailstring | null · email
Prospect email address. When updating a matched prospect, send null to clear the email.
phonestring | null
Prospect phone number. When updating a matched prospect, send null to clear the phone.
stageIdstring
Stage ID to place the prospect in. When provided, this takes precedence over pipelineId. Use the same stageId to filter GET /prospects and GET /prospects/count.
pipelineIdstring
Optional pipeline ID used only when stageId is omitted. The prospect is routed to that pipeline's configured default stage.
licenseStatusstring | null · enum
License status for the prospect. When updating a matched prospect, send null to clear the license status.
Enum values:
not_started
in_progress
licensed
labels
Optional labels to attach to the prospect. Accepts either a comma-separated string or an array of strings.
notesstring
Optional plain-text notes for the prospect profile.
titlestring | null
Prospect job title. When updating a matched prospect, send null to clear the title.
companystring | null
Prospect company name. When updating a matched prospect, send null to clear the company.
userIdstring
User id performing the create/update operation.
streetAddressstring | null
Prospect street address. When updating a matched prospect, send null to clear this address field.
citystring | null
Prospect city. When updating a matched prospect, send null to clear this address field.
statestring | null
Prospect state or region. When updating a matched prospect, send null to clear this address field.
postalCodestring | null
Prospect postal/zip code. When updating a matched prospect, send null to clear this address field.
officeIdstring | null
Optional office id to associate with the prospect. When updating a matched prospect, send null to clear the office association.
sourceIdstring | null
Existing source id to associate with the prospect. For matched-prospect updates, source changes are restricted by existing business rules; send null only when intentionally clearing an eligible source.
newSourceNamestring
New source name to create/use when sourceId is not provided.
resumeobject
Optional resume payload for parsing and storage.
muteWebhookboolean
If true, suppresses outbound webhook notifications for this write.
jobIdstring
Optional job id. When provided, links the prospect to a job and records an apply timestamp.
applicationQuestionsobject[]
Optional job application question responses (label, answer, and optional type/id per item).

Create or Update Prospect › Responses

Existing prospect returned or updated

successboolean · required
itemobject · required
Example: {"id":"c1a7e9d34b8f4c2aa6d15e0f7b3c9d42","message":null,"firstName":"Avery","lastName":"Coleman","email":"avery.coleman@example.com","phone":"+15551234567","currentStage":"New Lead","stageId":"9a3d7c1e4b2f48d6a5c0e1f9b7d2a346","pipelineId":"3d9a1c7e4b2f46d8a5c0e1f9b7d2a348","labels":["Hot","Inbound"],"title":"Sales Manager","company":"Northwind Health","createdAt":1717000000000,"updatedAt":1717003600000}

Count Prospects

GET

https://api.hiringcenterpro.com/v2

/prospects/count

Count Prospects › query Parameters

emailstring
Example: avery.coleman@example.com
phonestring
Example: +15551234567
namestring
Example: Avery Coleman
titlestring
Example: Sales Manager
companystring
Example: Northwind Health
stageIdstring
Optional. Filter prospects by stage ID. Same identifier used on create/update and returned on prospect responses as stageId.
Example: 9a3d7c1e4b2f48d6a5c0e1f9b7d2a346
labelstyle: form · explode: true
Optional. Filter by label(s). Supports repeated query params or a comma-separated value. Up to 10 labels.
createdAfter
Optional lower bound for prospect createdAt as Unix epoch milliseconds (integer) or ISO 8601 date string.
createdBefore
Optional upper bound for prospect createdAt as Unix epoch milliseconds (integer) or ISO 8601 date string.

Count Prospects › Responses

successboolean · required
countinteger · required

Get Prospect by ID

GET

https://api.hiringcenterpro.com/v2

/prospects/{prospectId}

Accepts a required prospectId path parameter, fetches that specific prospect, and returns it in item when found.

Get Prospect by ID › path Parameters

prospectIdstring · required
Example: c1a7e9d34b8f4c2aa6d15e0f7b3c9d42

Get Prospect by ID › Responses

successboolean · required
itemobject · required
Example: {"id":"c1a7e9d34b8f4c2aa6d15e0f7b3c9d42","message":null,"firstName":"Avery","lastName":"Coleman","email":"avery.coleman@example.com","phone":"+15551234567","currentStage":"New Lead","stageId":"9a3d7c1e4b2f48d6a5c0e1f9b7d2a346","pipelineId":"3d9a1c7e4b2f46d8a5c0e1f9b7d2a348","labels":["Hot","Inbound"],"title":"Sales Manager","company":"Northwind Health","createdAt":1717000000000,"updatedAt":1717003600000}

Delete Prospect

DELETE

https://api.hiringcenterpro.com/v2

/prospects/{prospectId}

Accepts a required prospectId and deletes the matching prospect.

Delete Prospect › path Parameters

prospectIdstring · required
Example: c1a7e9d34b8f4c2aa6d15e0f7b3c9d42

Delete Prospect › Headers

X-Idempotency-Keystring · maxLength: 512
Optional. Client-generated key used to make mutation retries safe. Reuse the same key only when retrying the exact same request.
Example: idem_prospect_create_01HV6W0J7Y7A5Q3T4J6N8M2P

Delete Prospect › Responses

Deleted

successboolean · required
messagestring · required