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

Accepts prospect profile fields, creates or updates a prospect, and returns the created or matched prospect in item. update defaults to true for this endpoint. When a matching prospect is found by email or phone and update is enabled, omitted request fields are left unchanged. To intentionally clear a supported field on the matched prospect, send that field with an explicit null value. For flat address fields (streetAddress, city, state, postalCode), only the submitted address fields are updated; omitted address fields are preserved. If phone is invalid, the request can still succeed; in that case the response includes a message warning 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

    When true, a matching existing prospect by email or phone is updated instead of simply being returned. Omitted fields are preserved; send explicit null values 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 used to link this prospect to a job.

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