Candidates

Create candidate

Creates a candidate profile and optionally links it to a job/stage on creation. Common entrypoint for imports, inbound forms, and enrichment workflows.

post/candidates

Request

  • Base URL: https://api.100hires.com/v2
  • URL: https://api.100hires.com/v2/candidates
  • Auth: HTTP bearer

Request body

company_idinteger

Target company ID. Required only when the API key has access to multiple companies.

first_namestring

Candidate first name.

last_namestring

Candidate last name.

emailstring email

Candidate email address. Used for deduplication.

phonestring

Candidate phone number.

profileobject

Key-value map of profile field answers. Keys can be either question text (string) or question_id (integer from GET /questions). Library fields (First name, Last name, Email, Phone, etc.) and custom fields both support text-based keys. Example: {"Years of experience": "5"} or {"42": "5"}. Must be a JSON object — a JSON array or a plain string is rejected with 400 Validation Error. Every key must resolve to a question of the target company and every value must be acceptable for that question's type; otherwise the request is rejected with 400 Validation Error listing the offending keys in validation_errors.profile, and nothing is saved. Multi-value fields such as Email accept an array of values, e.g. {"Email": ["a@example.com", "b@example.com"]}. Yes/No questions take 1 or 0, as a number or as a string — send JSON false as 0, since a JSON false is indistinguishable from an empty value and is rejected.

job_idinteger

Job ID to create an application for this candidate. If omitted, candidate is created without an application.

stage_idinteger

Pipeline stage ID for the initial application. Requires job_id. If omitted with job_id, defaults to the first stage.

citystring

Candidate city. Used together with state/country to resolve timezone and location display in the profile header. If omitted or empty, taken from the candidate's 'City' profile answer when present.

statestring

Candidate state or region. If omitted or empty, taken from the candidate's 'State' profile answer when present.

countrystring

Candidate country name or ISO 3166-1 alpha-2 code (e.g. 'United States' or 'US'). If omitted or empty, taken from the candidate's 'Country' profile answer when present.

timezonestring

IANA timezone (e.g. 'America/Los_Angeles'). If omitted, resolved automatically from city/country. If provided alongside city, overrides the auto-resolved timezone.

Response

Created candidate

idinteger required

Unique identifier

aliasstring nullable

Short alphanumeric alias used in profile URLs. Use this to build candidate profile links — https://app.100hires.com/candidate/{alias}. Also accepted as {id} in API requests.

url_backofficestring uri

Absolute backoffice URL of the candidate in the 100Hires recruiter app. Use to render deep-links in agent UIs.

company_idinteger required

ID of the company this candidate belongs to

first_namestring nullable

Candidate's first name

last_namestring nullable

Candidate's last name

emailsstring[] nullable

List of candidate email addresses

phonesstring[] nullable

List of candidate phone numbers

ipstring nullable

IP address from which the candidate applied

created_atinteger required

Unix timestamp (seconds)

updated_atinteger required

Unix timestamp (seconds)

last_message_atinteger nullable

Unix timestamp (seconds) of the most recent message (email or SMS) sent to or received from this candidate. Null if no messages exist.

days_since_last_messageinteger nullable

Number of whole days since the last message. Computed at request time. Null if no messages exist.

Example response

{
  "alias": "dtGeby2",
  "url_backoffice": "https://app.100hires.com/candidate/dtGeby2"
}

Changes

No recorded changes to this operation across all 1 revision of this API.