Developers

API Quickstart

Get up and running in minutes

This quickstart walks through the main flow of a HiringCenter integration:

1. Set your API key
2. Verify the key
3. Look up the IDs you need: stages and users
4. Create a prospect
5. Add a note or a task for that prospect
6. Schedule a meeting and move the prospect to a new stage
7. Record a hire

Base URL:

https://api.hiringcenterpro.com/v2

The examples use curl. The optional jq lines show where each ID comes from.

---

1) Set your API key

Create an API key in HiringCenter: Settings -> API / Webhooks -> Add API Key

Then set these environment variables:

Code
 
export HIRINGCENTER_API_KEY="<YOUR_API_KEY>"
export HIRINGCENTER_BASE_URL="https://api.hiringcenterpro.com/v2"

Every request made with this key acts on the key's account. You never send an accountId; a request that names a different account returns 403.

---

2) Verify the key

GET /auth confirms the key is valid and shows which account it belongs to. Use it during setup or troubleshooting; it is not required before other requests.

Code
 
curl -sS "$HIRINGCENTER_BASE_URL/auth" \
  -H "Authorization: Bearer $HIRINGCENTER_API_KEY" \
  -H "Accept: application/json"

A successful response includes the key's accountId, accountName, and active status.

---

3) Look up stages and users

Prospects are placed in stages by stageId. Task assignees, meeting owners, and prospect owners are user IDs, and any write can take an optional userId to credit a user instead of your API key. Look these up once and reuse the IDs.

Code
 
# Stages: id and name, where name is "<pipeline> - <stage>"
curl -sS "$HIRINGCENTER_BASE_URL/account/stages" \
  -H "Authorization: Bearer $HIRINGCENTER_API_KEY"

# Users: id and name
curl -sS "$HIRINGCENTER_BASE_URL/account/users" \
  -H "Authorization: Bearer $HIRINGCENTER_API_KEY"

Save the IDs you will use:

Code
 
export STAGE_ID="<STAGE_ID>"        # items[].id from /account/stages
export USER_ID="<USER_ID>"          # items[].id from /account/users

# Or with jq, for example the first user:
export USER_ID="$(curl -sS "$HIRINGCENTER_BASE_URL/account/users" \
  -H "Authorization: Bearer $HIRINGCENTER_API_KEY" | jq -r '.items[0].id')"

GET /account with no include returns the whole account configuration (stages, pipelines, users, offices, sources, and identities) in one call. GET /account/pipelines, GET /account/offices, and GET /account/sources list the other IDs prospects use.

---

4) Create a prospect

Use POST /prospects (Create or Update Prospect). firstName and lastName are required. Send whatever contact details you have, such as email, phone, officeId, sourceId, and labels.

If a prospect with the same email (or, failing that, the same phone) already exists, the API matches it instead of creating a duplicate. Sending "update": false returns the existing prospect unchanged, so the response is always { "success": true, "item": ... }.

Code
 
curl -sS -X POST "$HIRINGCENTER_BASE_URL/prospects" \
  -H "Authorization: Bearer $HIRINGCENTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "firstName": "Jordan",
    "lastName": "Miller",
    "email": "jordan.miller@example.com",
    "phone": "+1 (555) 234-5678",
    "stageId": "'"$STAGE_ID"'",
    "ownerId": "'"$USER_ID"'",
    "labels": ["Quickstart"],
    "update": false
  }'

A new prospect returns 201; a match returns 200 with item.message set to Success: prospect already exists. Save item.id:

Code
 
export PROSPECT_ID="<item.id from the response>"

The phone is returned normalized as 15552345678. With the default "update": true, a matched prospect is updated with the fields you send, and the 200 response body is the updated prospect object itself (read id from the top level).

---

5) Add a note or a task

Add a note with POST /notes. If the prospect does not exist, the request returns 404 and nothing is saved. userId is optional: it makes that user the note's author. Without it, the note is credited to your API key by name.

Code
 
curl -sS -X POST "$HIRINGCENTER_BASE_URL/notes" \
  -H "Authorization: Bearer $HIRINGCENTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "prospectId": "'"$PROSPECT_ID"'",
    "userId": "'"$USER_ID"'",
    "body": "<p>Submitted the website form and asked about the downtown office.</p>"
  }'

Or create a task with POST /tasks. assignedTo (required) is the user who should do the task; dueAt (Unix milliseconds) defaults to now.

Code
 
curl -sS -X POST "$HIRINGCENTER_BASE_URL/tasks" \
  -H "Authorization: Bearer $HIRINGCENTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "prospectId": "'"$PROSPECT_ID"'",
    "assignedTo": "'"$USER_ID"'",
    "task": "Call Jordan about the downtown office",
    "dueAt": 1793300400000
  }'

Meetings (POST /meetings, with a required ownerId) and hires (POST /hires) work the same way with the prospectId.

---

6) Schedule a meeting and move the prospect forward

Book a meeting with POST /meetings. meetingDate (Unix milliseconds or an ISO 8601 string), timeZone, meetingType, and ownerId (the user who runs the meeting) are required.

Code
 
curl -sS -X POST "$HIRINGCENTER_BASE_URL/meetings" \
  -H "Authorization: Bearer $HIRINGCENTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "prospectId": "'"$PROSPECT_ID"'",
    "ownerId": "'"$USER_ID"'",
    "meetingDate": "2026-12-03T15:00:00-05:00",
    "timeZone": "America/New_York",
    "meetingType": "Phone Meeting",
    "durationMinutes": 30
  }'

Then move the prospect to the next stage with POST /prospects/<prospectId>. Only the fields inside updates change, and the response lists what changed in changes.

Code
 
export NEXT_STAGE_ID="<STAGE_ID>"   # another items[].id from /account/stages

curl -sS -X POST "$HIRINGCENTER_BASE_URL/prospects/$PROSPECT_ID" \
  -H "Authorization: Bearer $HIRINGCENTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "userId": "'"$USER_ID"'",
    "updates": { "stageId": "'"$NEXT_STAGE_ID"'", "labels": ["Meeting booked"] }
  }'

Mark the task from step 5 done with POST /tasks/<taskId> and {"complete": true}. Update or cancel the meeting later with POST /meetings/<meetingId> or DELETE /meetings/<meetingId>.

---

7) Record a hire

When the prospect joins, record it with POST /hires. hireDate accepts Unix milliseconds or an ISO 8601 date.

Code
 
curl -sS -X POST "$HIRINGCENTER_BASE_URL/hires" \
  -H "Authorization: Bearer $HIRINGCENTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "prospectId": "'"$PROSPECT_ID"'",
    "userId": "'"$USER_ID"'",
    "hireDate": "2026-12-15",
    "hireDescription": "Joined the downtown office"
  }'

List a prospect's records any time with GET /notes, GET /tasks, GET /meetings, or GET /hires and ?prospectId=<prospectId>.

---

The whole flow

1. GET /auth to verify the key (optional)
2. GET /account/stages and GET /account/users for IDs
3. POST /prospects to create or match the prospect, then save item.id
4. POST /notes or POST /tasks to record activity
5. POST /meetings to book a meeting, and POST /prospects/<prospectId> to move the stage
6. POST /hires to record the hire

Send an X-Idempotency-Key on every write so a retry after a network error does not create a second record.