SmartRecruiters

Access

SmartRecruiters is BYOK-only. Connect your own SmartToken (minted in the SmartRecruiters Credential Manager) in Integrations; there is no managed-key fallback and the write costs 0 Hyreflow credits. list_departments is the free connection check: it verifies the key and returns the configured departments. There is no sandbox host — a test job is a real job in the account.

Create a job

create_job(payload) posts a job. Required: title, location, industry.id, function.id, experienceLevel.id.

• title (required) — 1–256 characters.
• location (required) — either full details or a predefined-location identifier (see below).
• industry.id / function.id / experienceLevel.id (all required) — ids from the account's own reference data (e.g. entry_level, associate, mid_senior_level, director, executive).
• typeOfEmployment.id — e.g. permanent, contract, part-time, intern.
• department.id — a configured department.
• refNumber — max 63 characters, must be unique — a reused one is refused.
• targetHiringDate, template (create a template instead of a job).
• compensation — {min, max, currency, period}; period is HOURLY, DAILY, WEEKLY, MONTHLY, YEARLY.
• jobAd.sections — companyDescription, jobDescription, qualifications, additionalInformation (each {title, text}, text max 24,999 chars), plus videos.urls.
• jobAd.language — {code, label, labelNative}; code required whenever language is sent.
• properties — [{id, value: {id, label}}], the company's own custom job properties.

location is one shape or the other

Send either full details — countryCode + city required, with optional region, regionCode, address, postalCode, longitude, latitude, remote, hybrid, hybridDescription — or a single identifier naming a predefined location. Those two sets are mutually exclusive; a payload with both is rejected. remote, hybrid and hybridDescription belong to BOTH shapes and stay legal with either.

hyreflow tools execute smartrecruiters_create_job --payload '{
  "title": "Senior Platform Engineer",
  "location": {"countryCode": "DE", "city": "Berlin", "remote": false},
  "industry": {"id": "internet"},
  "function": {"id": "engineering"},
  "experienceLevel": {"id": "mid_senior_level"}
}'

Publishing it

publish_job(job_id, payload) publishes the job's default ad. Every field is optional:

• visibility — PUBLIC or INTERNAL.
• aggregators — boolean, also push to job aggregators.
• includeInternal — boolean, publish internally alongside the public ad.
• delayPublicInDays — integer, hold the public posting back this many days.

hyreflow tools execute smartrecruiters_publish_job --payload '{"job_id": "<job id>", "visibility": "PUBLIC"}'

It answers 204 with no body, so an empty result is success. Publishing needs the vendor's jobs_publications_manage permission — a token that can create jobs cannot necessarily publish them — and is paced at 2 requests/second rather than 10. Four refusals are worth recognizing: PUBLISHED_JOB_AD_LIMIT_REACHED (the plan cap), NOT_AUTHORIZED_TO_PUBLISH_JOB (also fires when the job needs approval first), and COMPENSATION_REQUIRED / COMPENSATION_HIDDEN when the account's configuration disagrees with the job's compensation.

Gotchas

• SmartRecruiters silently ignores an unrecognized properties[].id or value — a typo returns 201 with the property missing. Read the created job back to confirm custom fields landed.
• Rejections come back with a typed error code (INDUSTRY_NOT_FOUND, CITY_NOT_FOUND, REF_NUMBER_ALREADY_EXISTS, COMPENSATION_INVALID_CURRENCY, …) naming the exact field — relay it rather than retrying blind.
• Paces at 10 requests/second.
• This is a write into the customer's own ATS — confirm the payload before executing.

What creating a job does NOT do

• The job is not published — publishing is publish_job, above, and there's no status field on create.
• The creator and hiring process come from the authenticated token and cannot be set here.