HiringCenter
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. 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.

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
  • stagestring
    Example: New Lead
  • 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.

  • limitinteger
    Example: 25
    Default: 25

List Prospects › Responses

OK

  • successboolean · required
  • itemsobject[] · required
  • paginationobject · required

    Pagination metadata. Fields are included only when that resource supports them.

    Example: {"nextPageToken":"eyJpZCI6InRhc2tfMDFIVjZXNldSNU44SzJNNFQ3WTlQMUMifQ==","totalCount":125}
Additional properties are allowed

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. If a match is found and the prospect was created more than 24 hours ago, the API also adds a note on the prospect and a task for the prospect's owner so your team can review the repeat submission. 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

    Optional stage ID to place the prospect in. When provided, this takes precedence over pipelineId.

  • 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","currentStageId":"9a3d7c1e4b2f48d6a5c0e1f9b7d2a346","pipelineId":"3d9a1c7e4b2f46d8a5c0e1f9b7d2a348","labels":["Hot","Inbound"],"title":"Sales Manager","company":"Northwind Health","createdAt":1717000000000,"updatedAt":1717003600000}
Additional properties are allowed

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

OK

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

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
AuthNotes