Schemas

Short category or reason phrase for the failure, for example Validation error.

Human-readable explanation of what went wrong.

Included as false by some endpoints.

Seconds to wait before retrying. Returned with 429 responses.

Request field names that must be provided for the request to succeed.

Machine-readable code for specific failures, for example duplicate_contact.

Optional validation details (shape varies by endpoint).

API key ID (the <keyId> part of an hc_<keyId>.<secret> key).

Name given to the key when it was created.

Account the key belongs to.

Permissions stored on the key: the scopes read and write, or older names (prospects:read, ...) on keys created before scopes. Older keys may still list a keys scope, which no longer does anything.

Unix timestamp in milliseconds

Account name when available.

The user a key is scoped to (keys created by connecting an AI tool through MCP). Every request with the key acts as this user. null for an account-wide key.

What the key may do: read (GET) and write (other methods; includes read). Keys created before scopes are shown with what they keep: read and write.

Opaque token for the next page when cursor pagination is supported. null when there are no more results.

True when another page is available for cursor-paginated endpoints. Prefer this over inferring solely from nextPageToken nullity.

Total matching items when available for this resource. Some endpoints can only report the number of items in the current page; see each operation.

A prospect record. Responses return the fields below when they are set on the record. Other fields may appear; ignore fields you do not use.

Id of the logged message.

The user it was logged for. Outbound texts and emails are credited to this user.

The user's personal (Manual Log / Device Handoff) thread with the prospect, where it was saved.

When it happened (the request's date, or the time of the request), as Unix epoch milliseconds.

The text, the email body, or the call notes (plain text). Empty for a call logged without notes.

Emails only. Outbound email or Inbound email when none was sent.

Calls only.

A text, email, or call logged with POST /activities. It is a message in the user's personal thread with the prospect.

A reply in a note's thread.

Pagination metadata. Fields are included only when that resource supports them; some list endpoints return an empty object.

Pagination metadata. Fields are included only when that resource supports them; some list endpoints return an empty object.

Pagination metadata. Fields are included only when that resource supports them; some list endpoints return an empty object.

Pagination metadata. Fields are included only when that resource supports them; some list endpoints return an empty object.

Pagination metadata. Fields are included only when that resource supports them; some list endpoints return an empty object.

Pagination metadata. Fields are included only when that resource supports them; some list endpoints return an empty object.

IANA time zone of the account, for example America/New_York.

Stage definitions for every pipeline.

All offices, including inactive ones (inactive: true).

The account's labels, trimmed, de-duplicated, and sorted alphabetically (ignoring case).

Active users on the account.

Active identities (the account phone numbers and email addresses used to contact prospects).

Account configuration. id, name, and timeZone are always present; the other sections are included when requested with include (all sections by default).

Pagination metadata. Fields are included only when that resource supports them; some list endpoints return an empty object.

Pagination metadata. Fields are included only when that resource supports them; some list endpoints return an empty object.

Only on POST /prospects create and lookup responses: Success: prospect created. or Success: prospect already exists., followed by a warning when the submitted phone or email was invalid and was not saved.

Only on POST /prospects create and lookup responses. Always false.

Email address. An empty string or null means none.

Lowercased email address, used for matching.

11-digit US/Canada phone number without +, for example 15552345678.

Stage ID for the prospect. Use the same value on create/update and on list/count filters.

Same value as stageId (older name).

Display name of the prospect's stage. Read-only; set and filter stage with stageId.

Pipeline of the current stage.

User ID of the prospect owner.

Latitude looked up from the address or postal code.

Longitude looked up from the address or postal code.

Out of area. True when the account limits office distance and the prospect is farther than that from the nearest active office.

Job the prospect applied to.

Unix timestamp in milliseconds of the latest job application.

Opt-outs by channel. true means the prospect does not want to be contacted that way.

Phone line details looked up when the phone number is saved.

Present when Twilio rejected the prospect's phone for texting and no line type was found for it. Texts to that number are refused until the phone changes. It applies only while phone still equals phoneUndeliverable.phone.

Most recent note on the prospect.

True when the prospect was created with muteWebhook, which suppresses its outbound webhooks.

User recorded as the creator.

True when the prospect was created through the API.

User recorded on the latest update.

Field change history. Update responses return only the entries added by that update.

Unix timestamp in milliseconds

Unix timestamp in milliseconds

AI summary of the prospect, returned by GET /prospects/{prospectId}. timestamp is when the summary was written (Unix milliseconds). A summary newer than 12 hours is returned as stored with refreshing: false. A missing or older summary is regenerated first, and the request waits up to 5 seconds; if it is not ready by then, the previous summary (or null content) is returned with refreshing: true.

Stored resume details when a resume was uploaded.

Only on POST /prospects create responses that included resume.

Only on POST /prospects create responses whose resume could not be saved. The prospect is still created.

Ignored when empty.

Ignored when empty.

New email address. null or an empty string clears it. An invalid address returns 400. An address already used by another prospect in the account returns 409 with code: duplicate_contact.

New US/Canada phone number. null or an empty string clears it. A value that is not a valid number returns 400 (field: phone) and the stored phone is kept. A number already used by another prospect returns 409 with code: duplicate_contact. A new number is looked up to refresh carrierEnrichment.

Moves the prospect to this stage (and its pipeline) and records the stage change. Moving to a stage named Hired also creates a hire record when the prospect has none.

Moves the prospect to the default stage of this pipeline. Ignored when stageId is sent.

Labels to add. Existing labels are kept. Accepts a comma-separated string or an array of strings.

Labels to remove. Accepts a comma-separated string or an array of strings. When both labels and removeLabels are sent, only removeLabels is applied.

Address fields to change. Omitted fields are kept; null or an empty string clears a field. The coordinates are looked up again from the new address.

New owner user ID (from GET /account/users). When the request includes userId, that user must be an admin or owner of the account, or the prospect's current owner; otherwise the request returns 403.

Office ID from GET /account/offices. null clears it.

Source ID from GET /account/sources. null clears it.

Job ID to link. Ignored when empty.

Job application time, Unix milliseconds.

Out-of-area flag.

Opt-outs by channel. Only the channels you send change. true stops HiringCenter from texting, emailing, or calling the prospect on that channel. The API can opt a prospect out but never back in: setting a channel that is opted out to false (or sending unsubscribed: null) returns 403 with code: resubscribe_not_allowed. Only a person signed in to HiringCenter can opt someone back in.

Replaces the stored application answers (up to 50). An empty array clears them.

Adds a note to the prospect. HTML is sanitized.

Resume file to attach to the prospect. Saving the file also adds a note with a link to it. The whole request body must fit within the 1 MB limit, so the base64 data must be under about 750 KB of file.

Original file name.

File type.

Optional file size in bytes. Files over 10 MB are rejected.

Note content as sanitized HTML. Only b, strong, i, em, u, a, h1-h6, br, and mention span tags are kept; other tags (including p and div) are removed and their text kept.

Unix timestamp in milliseconds

User the note is attributed to, or null when the note was created without a userId (credited to the API key in createdByApiKeyName).

Same as userId for notes created through the API.

True when the note was created through the API.

Id of the API key that created the note.

Name of the API key that created the note.

Present and true when HiringCenter AI wrote the note.

Account users mentioned in the note. Mentions of users who are not in the account are dropped.

True when the note is pinned on the prospect.

HTTPS link to a file attached to the note.

Note the reply belongs to.

Reply content as sanitized HTML (same allowed tags as a note body).

Unix timestamp in milliseconds

User the reply is attributed to, or null when created without a userId.

True when the reply was created through the API.

User id of the assignee, or hiringcenterAi for a task assigned to HiringCenter AI.

User who created the task, or null when created without a userId.

Unix timestamp in milliseconds

Unix timestamp in milliseconds. Set once the task has been updated or completed.

Unix timestamp in milliseconds

Unix timestamp in milliseconds, or null while the task is open.

Present and true when HiringCenter AI created the task.

True when the task was created through the API.

Id of the API key that created the task.

Name of the API key that created the task.

User who last updated the task, when known.

Unix timestamp in milliseconds

IANA time zone name, for example America/New_York.

Meeting type label. The app uses In-Person Meeting, Phone Meeting, Virtual Meeting, and Other.

Optional second owner.

Optional assistant.

Meeting length in minutes.

True when the meeting was created through the API.

Id of the API key that created the meeting.

Name of the API key that created the meeting.

Present and true when HiringCenter AI created the meeting.

Unix timestamp in milliseconds

Unix timestamp in milliseconds

The meeting's review, recorded after the meeting in the app or with POST /meetings/{meetingId}. null until the meeting has been reviewed.

Unix timestamp in milliseconds

true when the hire is marked as ignored (the app's "Ignore this hire" option).

User the hire is attributed to, or null when created without a userId (credited to the API key in createdByApiKeyName).

True when the hire was created through the API.

Unix timestamp in milliseconds

Unix timestamp in milliseconds

11-digit phone number without +, or an empty string.

not_started, in_progress, licensed, or an empty string.

Identifier to use in requests (for example pipelineId, sourceId, or officeId).

Same value as id.

id when the identifier is the record ID. name when the record has no ID and its name is used instead.

Display name.

Key id. Use it as keyId in /api-keys/{keyId} paths.

Key id. Same value as id for keys in the hc_<keyId>.<secret> format.

Empty string when no description is set.

Account the key belongs to.

Stored permissions (scopes, or older names on older keys).

v2 keys have the form hc_<keyId>.<secret> and can be rotated. legacy keys were issued before that format and cannot be rotated; replace them with a new key.

True when the key can authenticate requests.

Last four characters of the current secret, for telling keys apart. Null for older keys.

What the key may do (see ApiKeyScope). Older keys are shown with what they keep.

Unix timestamp in milliseconds.

Unix timestamp in milliseconds of the last authenticated request. Updated at most once per minute.

Unix timestamp in milliseconds when the key was deleted. Null for active keys.

Unix timestamp in milliseconds when deletion was requested. Null for active keys.

Unix timestamp in milliseconds after which a deleted key is permanently removed and can no longer be reactivated (30 days after deletion). Null for active keys.

Reserved. Null for keys created through this API.

Reserved. Null for keys created through this API.

Reserved. False for keys created through this API.

Reserved. False for keys created through this API.

The user the key is scoped to, for keys created by connecting an AI tool through MCP (every request acts as that user). null for account-wide keys, including every key created through this API.

mcp_oauth for keys created by connecting an AI tool; otherwise null.

Name of the AI tool that was connected (for example Claude), for mcp_oauth keys.

The new full API key (hc_<keyId>.<secret>). The key id is unchanged. It is returned only in this response, so store it securely now.

Permissions stored on the key (see ApiKey).

Unix timestamp in milliseconds when the key was first created.

API key metadata. The secret is never included; only its last four characters.

API key metadata. The secret is never included; only its last four characters.