HiringCenter API

Notes

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

Create, list, and manage notes

List Notes

GET

https://api.hiringcenterpro.com/v2

/notes

Returns notes ordered by createdAt (newest first) using the standard list envelope. prospectId, userId, and createdAfter/createdBefore are optional filters; with none, the most recent notes in the account are returned. When a page is full, pagination.nextPageToken is set; pass it as pageToken to get the next page.

List Notes › query Parameters

prospectIdstring
Optional. Only notes for this prospect.
Example: c1a7e9d34b8f4c2aa6d15e0f7b3c9d42
userIdstring
Optional. Only notes attributed to this user.
Example: b2e7a1d94c3f4a8eb6d05c1f9a7e2d45
createdAfter
Optional inclusive lower bound for createdAt as Unix epoch milliseconds/seconds or a date string.
createdBefore
Optional inclusive upper bound for createdAt as Unix epoch milliseconds/seconds or a date string. Must not be earlier than createdAfter.
limitinteger · min: 1 · max: 200
Page size.
Example: 25
Default: 50
pageTokenstring
Opaque pagination token returned from a prior GET /notes response.
Example: eyJjcmVhdGVkQXQiOjE3MTcwMDcyMDAwMDB9
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. Nested paths are not supported, and the accepted names depend on the endpoint. 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 Notes › Responses

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

Create Note

POST

https://api.hiringcenterpro.com/v2

/notes

Adds a note to a prospect. The note becomes the prospect's most recent note, mentioned users are notified, and when userId is set the prospect owner is notified that a note was added.

body is sanitized: only b, strong, i, em, u, a, h1-h6, br, and mention span (<span data-user-id="...">) tags are kept. Other tags are removed and their text kept. The sanitized body must not be empty and may be at most 20,000 bytes (413 otherwise).

Create Note › Headers

X-Idempotency-Keystring
Optional. Client-generated key that makes retries of this request safe. The first response for the key is stored for 24 hours and replayed for retries with the same method, path, query, and body. Reuse a key only when retrying the exact same request.
Example: idem_prospect_create_01HV6W0J7Y7A5Q3T4J6N8M2P

Create Note › Request Body

prospectIdstring · required
Id of an existing prospect the note belongs to.
bodystring · required
Note content (HTML or plain text). See the sanitizing rules above.

userIdstring
Optional account user the note is attributed to. When omitted, userId is null and the note is credited to the API key (createdByApiKeyName).
date
Optional note timestamp as Unix epoch milliseconds/seconds (integer), ISO 8601, or MM/DD/YYYY[ HH:mm[:ss]]. Defaults to now.
mentionsobject[]
Optional users mentioned in the note. Entries whose userId is not a user in the account are dropped.
pinboolean
If true, pins the note on the prospect.
Default: false
fileUrlstring · uri · maxLength: 2048
Optional public HTTPS URL of a file attached to the note. Local and private-network hosts are rejected.

Create Note › Responses

Created

successboolean · required
itemobject · required
Example: {"id":"d8b2c7a14e9f4d3ab6c05e1f9a7d2c48","body":"Left voicemail and sent a follow-up email.","createdAt":1717007200000,"prospectId":"c1a7e9d34b8f4c2aa6d15e0f7b3c9d42","userId":"b2e7a1d94c3f4a8eb6d05c1f9a7e2d45","createdBy":"b2e7a1d94c3f4a8eb6d05c1f9a7e2d45","createdByApi":true,"createdByApiKeyId":"8f4c2a19d7e34b6f9a1c5e2d7b3f8c4a","createdByApiKeyName":"Zapier production key","mentions":[{"userId":"b2e7a1d94c3f4a8eb6d05c1f9a7e2d45","displayName":"Jamie Lee"}],"pin":true,"fileUrl":null}

Get Note by ID

GET

https://api.hiringcenterpro.com/v2

/notes/{noteId}

Returns one note in item.

Get Note by ID › path Parameters

noteIdstring · required
Example: d8b2c7a14e9f4d3ab6c05e1f9a7d2c48

Get Note by ID › Responses

successboolean · required
itemobject · required
Example: {"id":"d8b2c7a14e9f4d3ab6c05e1f9a7d2c48","body":"Left voicemail and sent a follow-up email.","createdAt":1717007200000,"prospectId":"c1a7e9d34b8f4c2aa6d15e0f7b3c9d42","userId":"b2e7a1d94c3f4a8eb6d05c1f9a7e2d45","createdBy":"b2e7a1d94c3f4a8eb6d05c1f9a7e2d45","createdByApi":true,"createdByApiKeyId":"8f4c2a19d7e34b6f9a1c5e2d7b3f8c4a","createdByApiKeyName":"Zapier production key","mentions":[{"userId":"b2e7a1d94c3f4a8eb6d05c1f9a7e2d45","displayName":"Jamie Lee"}],"pin":true,"fileUrl":null}

Update Note

POST

https://api.hiringcenterpro.com/v2

/notes/{noteId}

Edits a note and returns the whole note in item. Send at least one of body, mentions, or pin (400 otherwise); fields you leave out are not changed.

body is sanitized with the same rules as POST /notes and must not be empty afterward (413 over 20,000 bytes). When the note is the prospect's most recent note, the prospect's lastNote preview is updated too.
mentions replaces the mention list. Entries whose userId is not a user in the account are dropped. Only users who were not already mentioned are notified. Adding hiringcenterAi to a note that did not mention it starts a HiringCenter AI run that answers in the note's thread, as a new note with that mention does; re-saving a note that already mentions it does not start another.
pin (boolean) pins or unpins the note.

The edit is recorded in updatedBy (from userId) or updatedByApiKeyId / updatedByApiKeyName.

Update Note › path Parameters

noteIdstring · required
Example: d8b2c7a14e9f4d3ab6c05e1f9a7d2c48

Update Note › Headers

X-Idempotency-Keystring
Optional. Client-generated key that makes retries of this request safe. The first response for the key is stored for 24 hours and replayed for retries with the same method, path, query, and body. Reuse a key only when retrying the exact same request.
Example: idem_prospect_create_01HV6W0J7Y7A5Q3T4J6N8M2P

Update Note › Request Body

bodystring
New note content (HTML or plain text).
mentionsobject[]
The note's mentioned users. Replaces the current list.
pinboolean
true pins the note; false unpins it.
userIdstring
Optional account user credited with the edit.

Update Note › Responses

successboolean · required
itemobject · required
Example: {"id":"d8b2c7a14e9f4d3ab6c05e1f9a7d2c48","body":"Left voicemail and sent a follow-up email.","createdAt":1717007200000,"prospectId":"c1a7e9d34b8f4c2aa6d15e0f7b3c9d42","userId":"b2e7a1d94c3f4a8eb6d05c1f9a7e2d45","createdBy":"b2e7a1d94c3f4a8eb6d05c1f9a7e2d45","createdByApi":true,"createdByApiKeyId":"8f4c2a19d7e34b6f9a1c5e2d7b3f8c4a","createdByApiKeyName":"Zapier production key","mentions":[{"userId":"b2e7a1d94c3f4a8eb6d05c1f9a7e2d45","displayName":"Jamie Lee"}],"pin":true,"fileUrl":null}

Delete Note

DELETE

https://api.hiringcenterpro.com/v2

/notes/{noteId}

Deletes a note. If it was the prospect's most recent note, the prospect's most recent note becomes the next newest one.

Delete Note › path Parameters

noteIdstring · required
Example: d8b2c7a14e9f4d3ab6c05e1f9a7d2c48

Delete Note › Headers

X-Idempotency-Keystring
Optional. Client-generated key that makes retries of this request safe. The first response for the key is stored for 24 hours and replayed for retries with the same method, path, query, and body. Reuse a key only when retrying the exact same request.
Example: idem_prospect_create_01HV6W0J7Y7A5Q3T4J6N8M2P

Delete Note › Responses

successboolean · required
messagestring · required

List Note Replies

GET

https://api.hiringcenterpro.com/v2

/notes/{noteId}/replies

Returns every reply in a note's thread, oldest first. pagination.hasMore is always false.

List Note Replies › path Parameters

noteIdstring · required
Example: d8b2c7a14e9f4d3ab6c05e1f9a7d2c48

List Note Replies › Responses

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

Reply to Note

POST

https://api.hiringcenterpro.com/v2

/notes/{noteId}/replies

Adds a reply to a note's thread. Mentioned users, the note's author, and the prospect owner are notified (each once, never the person replying).

content is sanitized with the same rules as a note body. The sanitized content must not be empty and may be at most 10,000 bytes (413 otherwise).

Reply to Note › path Parameters

noteIdstring · required
Example: d8b2c7a14e9f4d3ab6c05e1f9a7d2c48

Reply to Note › Headers

X-Idempotency-Keystring
Optional. Client-generated key that makes retries of this request safe. The first response for the key is stored for 24 hours and replayed for retries with the same method, path, query, and body. Reuse a key only when retrying the exact same request.
Example: idem_prospect_create_01HV6W0J7Y7A5Q3T4J6N8M2P

Reply to Note › Request Body

contentstring · required
Reply content (HTML or plain text).

userIdstring
Optional account user the reply is attributed to. When omitted, userId is null and the reply is credited to the API key (createdByApiKeyName).
mentionsobject[]
Optional users mentioned in the reply. Entries whose userId is not a user in the account are dropped.

Reply to Note › Responses

Created

successboolean · required
itemobject · required
A reply in a note's thread.

Prospects Agenda

HiringCenter API

Notes

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

Create, list, and manage notes

List Notes

GET

https://api.hiringcenterpro.com/v2

/notes

List Notes › query Parameters

prospectIdstring
Optional. Only notes for this prospect.
Example: c1a7e9d34b8f4c2aa6d15e0f7b3c9d42
userIdstring
Optional. Only notes attributed to this user.
Example: b2e7a1d94c3f4a8eb6d05c1f9a7e2d45
createdAfter
Optional inclusive lower bound for createdAt as Unix epoch milliseconds/seconds or a date string.
createdBefore
Optional inclusive upper bound for createdAt as Unix epoch milliseconds/seconds or a date string. Must not be earlier than createdAfter.
limitinteger · min: 1 · max: 200
Page size.
Example: 25
Default: 50
pageTokenstring
Opaque pagination token returned from a prior GET /notes response.
Example: eyJjcmVhdGVkQXQiOjE3MTcwMDcyMDAwMDB9
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. Nested paths are not supported, and the accepted names depend on the endpoint. 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 Notes › Responses

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

Create Note

POST

https://api.hiringcenterpro.com/v2

/notes

Adds a note to a prospect. The note becomes the prospect's most recent note, mentioned users are notified, and when userId is set the prospect owner is notified that a note was added.

Create Note › Headers

X-Idempotency-Keystring
Optional. Client-generated key that makes retries of this request safe. The first response for the key is stored for 24 hours and replayed for retries with the same method, path, query, and body. Reuse a key only when retrying the exact same request.
Example: idem_prospect_create_01HV6W0J7Y7A5Q3T4J6N8M2P

Create Note › Request Body

prospectIdstring · required
Id of an existing prospect the note belongs to.
bodystring · required
Note content (HTML or plain text). See the sanitizing rules above.

userIdstring
Optional account user the note is attributed to. When omitted, userId is null and the note is credited to the API key (createdByApiKeyName).
date
Optional note timestamp as Unix epoch milliseconds/seconds (integer), ISO 8601, or MM/DD/YYYY[ HH:mm[:ss]]. Defaults to now.
mentionsobject[]
Optional users mentioned in the note. Entries whose userId is not a user in the account are dropped.
pinboolean
If true, pins the note on the prospect.
Default: false
fileUrlstring · uri · maxLength: 2048
Optional public HTTPS URL of a file attached to the note. Local and private-network hosts are rejected.

Create Note › Responses

Created

successboolean · required
itemobject · required
Example: {"id":"d8b2c7a14e9f4d3ab6c05e1f9a7d2c48","body":"Left voicemail and sent a follow-up email.","createdAt":1717007200000,"prospectId":"c1a7e9d34b8f4c2aa6d15e0f7b3c9d42","userId":"b2e7a1d94c3f4a8eb6d05c1f9a7e2d45","createdBy":"b2e7a1d94c3f4a8eb6d05c1f9a7e2d45","createdByApi":true,"createdByApiKeyId":"8f4c2a19d7e34b6f9a1c5e2d7b3f8c4a","createdByApiKeyName":"Zapier production key","mentions":[{"userId":"b2e7a1d94c3f4a8eb6d05c1f9a7e2d45","displayName":"Jamie Lee"}],"pin":true,"fileUrl":null}

Get Note by ID

GET

https://api.hiringcenterpro.com/v2

/notes/{noteId}

Returns one note in item.

Get Note by ID › path Parameters

noteIdstring · required
Example: d8b2c7a14e9f4d3ab6c05e1f9a7d2c48

Get Note by ID › Responses

successboolean · required
itemobject · required
Example: {"id":"d8b2c7a14e9f4d3ab6c05e1f9a7d2c48","body":"Left voicemail and sent a follow-up email.","createdAt":1717007200000,"prospectId":"c1a7e9d34b8f4c2aa6d15e0f7b3c9d42","userId":"b2e7a1d94c3f4a8eb6d05c1f9a7e2d45","createdBy":"b2e7a1d94c3f4a8eb6d05c1f9a7e2d45","createdByApi":true,"createdByApiKeyId":"8f4c2a19d7e34b6f9a1c5e2d7b3f8c4a","createdByApiKeyName":"Zapier production key","mentions":[{"userId":"b2e7a1d94c3f4a8eb6d05c1f9a7e2d45","displayName":"Jamie Lee"}],"pin":true,"fileUrl":null}

Update Note

POST

https://api.hiringcenterpro.com/v2

/notes/{noteId}

Edits a note and returns the whole note in item. Send at least one of body, mentions, or pin (400 otherwise); fields you leave out are not changed.

body is sanitized with the same rules as POST /notes and must not be empty afterward (413 over 20,000 bytes). When the note is the prospect's most recent note, the prospect's lastNote preview is updated too.
mentions replaces the mention list. Entries whose userId is not a user in the account are dropped. Only users who were not already mentioned are notified. Adding hiringcenterAi to a note that did not mention it starts a HiringCenter AI run that answers in the note's thread, as a new note with that mention does; re-saving a note that already mentions it does not start another.
pin (boolean) pins or unpins the note.

The edit is recorded in updatedBy (from userId) or updatedByApiKeyId / updatedByApiKeyName.

Update Note › path Parameters

noteIdstring · required
Example: d8b2c7a14e9f4d3ab6c05e1f9a7d2c48

Update Note › Headers

X-Idempotency-Keystring
Optional. Client-generated key that makes retries of this request safe. The first response for the key is stored for 24 hours and replayed for retries with the same method, path, query, and body. Reuse a key only when retrying the exact same request.
Example: idem_prospect_create_01HV6W0J7Y7A5Q3T4J6N8M2P

Update Note › Request Body

bodystring
New note content (HTML or plain text).
mentionsobject[]
The note's mentioned users. Replaces the current list.
pinboolean
true pins the note; false unpins it.
userIdstring
Optional account user credited with the edit.

Update Note › Responses

successboolean · required
itemobject · required
Example: {"id":"d8b2c7a14e9f4d3ab6c05e1f9a7d2c48","body":"Left voicemail and sent a follow-up email.","createdAt":1717007200000,"prospectId":"c1a7e9d34b8f4c2aa6d15e0f7b3c9d42","userId":"b2e7a1d94c3f4a8eb6d05c1f9a7e2d45","createdBy":"b2e7a1d94c3f4a8eb6d05c1f9a7e2d45","createdByApi":true,"createdByApiKeyId":"8f4c2a19d7e34b6f9a1c5e2d7b3f8c4a","createdByApiKeyName":"Zapier production key","mentions":[{"userId":"b2e7a1d94c3f4a8eb6d05c1f9a7e2d45","displayName":"Jamie Lee"}],"pin":true,"fileUrl":null}

Delete Note

DELETE

https://api.hiringcenterpro.com/v2

/notes/{noteId}

Deletes a note. If it was the prospect's most recent note, the prospect's most recent note becomes the next newest one.

Delete Note › path Parameters

noteIdstring · required
Example: d8b2c7a14e9f4d3ab6c05e1f9a7d2c48

Delete Note › Headers

X-Idempotency-Keystring
Optional. Client-generated key that makes retries of this request safe. The first response for the key is stored for 24 hours and replayed for retries with the same method, path, query, and body. Reuse a key only when retrying the exact same request.
Example: idem_prospect_create_01HV6W0J7Y7A5Q3T4J6N8M2P

Delete Note › Responses

successboolean · required
messagestring · required

List Note Replies

GET

https://api.hiringcenterpro.com/v2

/notes/{noteId}/replies

Returns every reply in a note's thread, oldest first. pagination.hasMore is always false.

List Note Replies › path Parameters

noteIdstring · required
Example: d8b2c7a14e9f4d3ab6c05e1f9a7d2c48

List Note Replies › Responses

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

Reply to Note

POST

https://api.hiringcenterpro.com/v2

/notes/{noteId}/replies

Adds a reply to a note's thread. Mentioned users, the note's author, and the prospect owner are notified (each once, never the person replying).

content is sanitized with the same rules as a note body. The sanitized content must not be empty and may be at most 10,000 bytes (413 otherwise).

Reply to Note › path Parameters

noteIdstring · required
Example: d8b2c7a14e9f4d3ab6c05e1f9a7d2c48

Reply to Note › Headers

X-Idempotency-Keystring
Optional. Client-generated key that makes retries of this request safe. The first response for the key is stored for 24 hours and replayed for retries with the same method, path, query, and body. Reuse a key only when retrying the exact same request.
Example: idem_prospect_create_01HV6W0J7Y7A5Q3T4J6N8M2P

Reply to Note › Request Body

contentstring · required
Reply content (HTML or plain text).

userIdstring
Optional account user the reply is attributed to. When omitted, userId is null and the reply is credited to the API key (createdByApiKeyName).
mentionsobject[]
Optional users mentioned in the reply. Entries whose userId is not a user in the account are dropped.

Reply to Note › Responses

Created

successboolean · required
itemobject · required
A reply in a note's thread.

Prospects Agenda