Developers

HiringCenter API Overview

HiringCenter REST API (v2)

The HiringCenter REST API (v2) lets your systems manage prospects, notes, tasks, meetings, and hires, log texts, emails, and calls that happened outside HiringCenter, read account settings such as stages, pipelines, offices, sources, and users, and receive webhook events.

Area	Endpoints
Auth and API keys	GET /auth, /api-keys (the calling key only)
Account lookups	GET /account, /account/zapier, /account/stages, /account/pipelines, /account/sources, /account/offices, /account/users, /account/labels
Prospects	/prospects, /prospects/count, /prospects/<prospectId>
Activity	/notes (with edits and replies), /tasks, /meetings (with reviews), /hires, POST /activities (log a text, email, or call; keys scoped to a user)
Webhooks	GET /webhooks/poll, and signed deliveries to your HTTPS endpoint

The API Reference documents every request and response, and it is the complete list: an API key can call exactly these endpoints and nothing else (any other route returns 403). To use HiringCenter from Claude, ChatGPT, or another AI tool without writing code, see Connect AI Tools (MCP).

Base URL

https://api.hiringcenterpro.com/v2

---

Authentication

Create an API Key in your HiringCenter account by navigating to Settings -> API / Webhooks -> Add API Key.

Create an API Key (Video)

Send your API key as a Bearer token in the Authorization header:

• Authorization header

  Code
   
  Authorization: Bearer <YOUR_API_KEY>

All documented endpoints require authentication.

Each API key belongs to one account, and every request acts on that account, so you never send an accountId. The key is shown once when you create it; HiringCenter stores only a hash of it.

• A missing, invalid, or disabled key returns 401 Unauthorized.
• A request that names another account's accountId (in the body, query, or path) returns 403 Forbidden with the message API keys can only access their own account. Leave accountId out of your requests.
• Each key has scopes: read for GET requests and write for POST, PATCH, and DELETE (write includes read). A read-only key gets 403 with Insufficient permissions: this API key is read-only on any change. Keys made in Settings start with read & write; an admin can make a key read only. Keys created before scopes keep full read and write.
• A key manages only itself: through /api-keys it can view, rename, rotate, or delete the key it is calling with. It cannot create keys, list keys, or view or change any other key (403). Admins and owners create keys, change a key's access, and reactivate keys in Settings → API / Webhooks.
• Use GET /auth to check a key and see which account it belongs to and its scopes.

Example Requests

• List prospects

  Code
   
  curl -X GET \
    'https://api.hiringcenterpro.com/v2/prospects?limit=1' \
    -H 'Authorization: Bearer <YOUR_API_KEY>' \
    -H 'Accept: application/json'

• Create a prospect

  Code
   
  curl -X POST \
    'https://api.hiringcenterpro.com/v2/prospects' \
    -H 'Authorization: Bearer <YOUR_API_KEY>' \
    -H 'Content-Type: application/json' \
    -d '{
      "firstName": "Jane",
      "lastName": "Doe"
    }'

Rate Limiting

Requests are rate limited per API key.

Dual-window limits are enforced:

• 500 requests per minute (burst window)
• 10000 requests per hour (sustained window)

Rate Limit Headers

Responses include these headers for the one-minute window:

• RateLimit-Limit: requests allowed in the window
• RateLimit-Remaining: requests left in the window
• RateLimit-Reset: Unix time (seconds) when the window resets

Requests rejected during authentication (401, or 403 for naming another account) are not counted and do not include these headers.

Rate Limit Exceeded Response

When either window is exceeded, the API returns 429 Too Many Requests with a Retry-After header (seconds to wait) and the rate-limit headers for the exceeded window.

Example response body:

Code
 
{
  "error": "Too many requests",
  "message": "Minute limit exceeded. Please try again later.",
  "retryAfter": 30
}

Request and Response Conventions

• Request and response bodies use application/json unless noted. Request bodies are limited to 1 MB.
• Timestamps are Unix time in milliseconds unless otherwise specified. GET /webhooks/poll returns ISO 8601 strings instead.
• Phone numbers must be US or Canada numbers. Send 10 digits, or 11 digits starting with 1; formatting characters are ignored, and the area code and exchange cannot start with 0 or 1. Phones are returned as 11 digits without +, for example 15552345678.
• Single-resource responses use { "success": true, "item": { ... } } and list responses use { "success": true, "items": [ ... ], "pagination": { ... } }. A few endpoints return a different shape (for example, updating a prospect returns the prospect object itself); the API Reference shows the exact response for each operation.
• Error responses are JSON with error and/or message, unless the API Reference documents a plain-text error for that operation.
• To receive bare arrays, send X-Response-Format: array (or ?responseFormat=array): list responses become an array of items and single-resource responses become a one-element array. Requests whose User-Agent contains Zapier get lists as bare arrays and single resources as bare objects automatically.

Attribution

By default, activity your API key creates is credited to the API key by its name. Records it creates carry createdByApi: true, createdByApiKeyId, and createdByApiKeyName, and their userId, createdBy, or updatedBy is null.

To credit a user instead, send userId (a user ID from GET /account/users). That user is recorded as the author, creator, or updater, and the prospect owner is usually notified of the change.

userId never assigns work. These fields decide who a record belongs to:

Resource	Who it belongs to
Prospects	ownerId. On create, when it is omitted, the owner is the userId you send, otherwise the account's default owner (an account owner, or an admin when there is none). With none of these, the request returns 400.
Tasks	assignedTo (required): an account user ID, or hiringcenterAi
Meetings	ownerId (required), plus optional secondaryOwnerId and assistantId
Notes, note replies, hires	No assignee. userId is the author, or null when the API key is credited.
Activities	The user the key is scoped to; account-wide keys are refused. It goes in that user's personal thread with the prospect.

Idempotency

For POST, PATCH, and DELETE requests on every documented endpoint, you can send:

X-Idempotency-Key: <UNIQUE_CLIENT_REQUEST_KEY>

• The first response for a key, including an error response, is stored for 24 hours.
• A retry with the same key, method, path, query, and body returns that stored response instead of running the request again.
• Reusing the key with a different query or body returns 409 Conflict.
• While the first request is still running, another request with the same key returns 409 Conflict.

Replay indicators

• Idempotency-Status: processing on the response to the first request with a key
• Idempotency-Status: replayed and Idempotency-Replayed: true on a replayed response