Refari ATS Integration Guide

What it is and why it matters

Job adverts are the primary payload of the integration. For a job board to function, adverts must flow continuously from the partner ATS into Refari, where they are rendered across job board widgets, custom feeds, recruiter profile pages and integrated external boards. Without a reliable advert feed, none of the downstream presentation layers have anything to display.

A Refari advert is more than a title and a description. Each advert carries associated objects that drive distinct behaviours: location data (both simple and detailed) for list, search and map-style interfaces; work type data so adverts can be filtered and grouped; the owning recruiter, so the advert can be attributed and surfaced on recruiter profile pages (and the recruiter surfaced on the advert); and an optional link to a Job (Job Order), which Refari uses in conjunction with the Job Contact (hiring manager) to power the TopRec process.

Because these associations are by reference, all of those records must exist in Refari before the advert that references them can be created. In practice a partner seeds the supporting objects first, then posts adverts. The key dependency to call out: you must create a company record (a Job Company) before you can create an advert that references it.

How the integration works

The flow is dependency-ordered. Before posting an advert, ensure the referenced recruiter, category, work type, location(s) and (optionally) company, contact and work address exist. Then post with createJobAd. The is_internal flag restricts an advert to the internal job board when true. Adverts are retired with removeJobAd, which marks them expired rather than hard-deleting. Once an advert has been edited inside the Refari dashboard, Refari takes ownership and both update and delete return 403; treat that as an expected terminal state, not an error to retry.

Endpoints

What it is and why it matters

Many clients struggle to keep their website team pages current through a CMS. Refari team widgets remove that friction and, paired with the ATS integration, can make it largely automatic. When a new recruiter is added to the ATS, the ATS sends them to Refari; Refari automatically invites them to complete their profile, and as soon as they do, they appear on the website. Manager and Admin level users can moderate these profiles to keep them on brand.

The relationship runs across the whole lifecycle. When a recruiter is removed from the ATS, the ATS notifies Refari, which deactivates them and removes them from the website. Recruiters are also load-bearing elsewhere: they own job adverts and Job Orders, so an accurate recruiter list underpins correct attribution across the product. To support this, the integration needs the full set of recruiters and notification when recruiters are deleted. Deactivation is reversible.

How the integration works

Create with createRecruiter (this also assigns an existing recruiter to the agency where one matches, so a duplicate returns 400 "Recruiter already exists."). Creation triggers the profile invitation automatically. Resolve a recruiter to its Refari UUID via listRecruiter, filtering by external_id or email. Deletion is a soft deactivation that removes the recruiter from the website; reactivate via /restore/.

Endpoints

What it is and why it matters

Refari supports two layers of location information. The first is the categorised Location (a single location id or a locations array) drawn from the agency's taxonomy and used for list views, filtering and search. The second is detailed, structured location data: the Work Address, carrying street, city, state, country, country code and postal code. This is the precise, geocodable address attached to the underlying Job (Job Order).

Detailed location data matters for the more demanding distribution scenarios: feeds into integrated job boards, custom feeds, and clients who want a richer location schema on their own board. It is used heavily by multinational clients who need an unambiguous, fully-qualified address rather than a taxonomy label alone, and it underpins map-style interfaces.

Endpoints

What it is and why it matters

Candidate referral remains Refari's signature capability. For an integration partner it is the single most important reason to model the candidate and application objects correctly: when a referred candidate converts, the customer expects the referring person to be recognised, communicated with, and (where a reward applies) paid.

Referrals reach Refari in two broad shapes. Digital referrals are generated by Refari's own widgets and job boards on the customer's website and flow back to you. Traditional (direct) referrals are the older, human pattern: a candidate is introduced by phone or email, and a recruiter records the referrer's details on the candidate record in the ATS, which then push to Refari so referral-specific communications can run. The technology is deliberately backwards compatible with both.

How the integration works

There are three referral flavours to map:

1. Digital referral, candidate record only. Submitted through a referral widget; Refari creates a candidate with source = "referral". You read it via listCandidate / retrieveCandidate and the candidate_created / referral_created events, then mirror it into the ATS.
2. Digital referral, application. A job advert is shared via a referral URL and the candidate applies through that link. Refari attributes the application to the referrer and returns the referrer object on retrieveApplication.
3. Traditional / direct referral. The partner is the source of truth: when you create the candidate via createCandidate, include the referrer object (email, first_name and referral_date required). There is no separate referral endpoint.

Referrer attribution is handed back two ways: the near-real-time referral_created webhook (which since 2026-02-25 carries extended candidate data), and synchronously on the application detail via the referrer object alongside rating, source and ownership_expiration.

What it is and why it matters

In Refari, an application's status is not just a label, it is a trigger. The stages of an application's journey in the ATS (for example Applied, Screening, Internal Interview, External Interview, Offered, Placed) drive several core automations. Different ATS systems use different wording, so Refari does not impose a fixed vocabulary: it works from the customer's own status strings.

Two flagship features depend on these statuses. Referral Transparency keeps a referrer informed as their candidate progresses. TopRec, our sentiment analytics system, uses status changes as the moments at which to act. Because customers choose which status triggers which automation, Refari needs the real status values, presented as selectable triggers.

How the integration works

Push status with the free-text crm_status field on createApplication / updateApplication. To avoid pushing data Refari does not need, call getApplicationImportRules first: it returns the configured triggers grouped into toprec, referrer and progression status-match arrays. Compare an application's crm_status against these before creating. This is an optimisation, not a hard gate, and the response is cacheable (recommended TTL 2 hours).

Endpoints

What it is and why it matters

The candidate is the person record at the centre of the referral and application lifecycle. Every application and placement ultimately hangs off a candidate, and the candidate's source tells you how that person entered the system. Candidates created by Refari widgets are read and mirrored into the ATS; candidates the partner owns are pushed in with source = "crm".

Endpoints

What it is and why it matters

An application links a candidate to a job order and carries the status that drives Refari's referral and testimonial automations. The Applications endpoints are how a partner pushes pipeline activity into Refari, reads back referrer attribution and Refari-derived statuses, and (via import rules) decides what is worth pushing in the first place. candidate and job_order are Refari UUIDs, so both must already exist.

Endpoints

What it is and why it matters

A placement records that a referred or submitted candidate was successfully placed, and it is the object behind the Referral CSV report. For customers running referral reward schemes, placements close the loop: they are the confirmed outcome the report is built on. A placement is created against an existing application.

Endpoints

What it is and why it matters

Screener questions let customers capture structured, decision-ready information at the point of application rather than parsing it from free text later. Questions can be authored in either system: an ATS partner can push its existing question library to Refari, or the client can build questions in the Refari dashboard. Both converge on the same Refari Question objects.

What lifts this into the Silver tier is the data-mapping capability. Each question can be mapped, via the dashboard, back to a specific ATS field (for example user.notification_period). When a candidate answers, the captured value is returned on the application alongside that mapping hint, so the integration knows exactly where to write the answer in the ATS. Questions are reusable building blocks, attached to one or more Job Ads through the advert's questions array, and in a near-future release they will compose into whole data-capture forms.

How the integration works

1. Create questions in Refari (addQuestions) or reuse existing ones (listQuestions). Each has an answer_type of text, list or file.
2. Attach question UUIDs to a Job Ad via the advert's questions array on create or update.
3. Optionally configure, in the dashboard, a mapping from each question to a target ATS field.
4. On retrieveApplication, captured responses appear in the answers array, each with question_text, answer_data and the optional mapping. Where mapping is set, write answer_data to the named field.

Endpoints

Questions are consumed by createJobAd / partialUpdateJobAd (the questions UUID array) and surfaced back through retrieveApplication (the answers array).

What it is and why it matters

Webhooks turn a one-directional feed (adverts out, applications back) into a genuine two-way conversation. Instead of polling Refari for changes, the partner registers an endpoint and Refari pushes an HTTP request the moment something happens, so the two systems stay in step in near real time.

The breadth of events is what makes this a Gold-tier capability. Beyond applications and candidate changes, webhooks expose what candidates and referrers actually do on the careers site and across Refari's tools: job alerts, AI suggestions, referrals, testimonial requests and responses, feedback, saved jobs, talent alerts and social shares. Recruiters can use these signals to add timely notes to candidate records, trigger nurture workflows, or surface engagement directly in the ATS.

How the integration works

1. Register with createWebhook, specifying the events and the url. Optionally include an authorization header value Refari will send with every notification.
2. Refari POSTs to your URL on each subscribed event. The body is { id, event, created, data }.
3. Verify authenticity via the X-Refari-Signature header: it holds the BLAKE2 signature of the entire raw request body keyed with your apiKey. Verify against the raw bytes before parsing.
4. Respond 2xx. Any non-200 or timeout is retried up to 10 times; more than 10 consecutive errors suspends the webhook (status becomes suspended). Re-enable by patching status back to active.

Available events

application_created · candidate_created · candidate_updated · candidate_ad_created · job_alert_created · job_alert_deleted · suggestion_created · referral_created · testimonial_request_sent · testimonial_created · testimonial_revised · feedback_created · saved_job_created · saved_job_deleted · job_order_job_url_updated · talent_alert_created · talent_alert_deleted · talent_alert_suggestion_created · socialise_created

Notification body

Every notification shares the same envelope. Most events send an empty data object and act as a trigger to fetch full state; socialise_created and referral_created carry rich inline payloads.

{
  "id": "ee4950cc-e62c-4b73-93ab-cc95c8aaf45c",
  "event": "application_created",
  "created": "2021-06-04T08:05:23.342140Z",
  "data": {}
}

referral_created data (candidate block extended 2026-02-25 with job_title, company_name, linkedin_profile_url, phone, resume, resume_name):

{
  "candidate": {
    "id": "a1b2c3d4-...", "first_name": "John", "last_name": "Doe",
    "email": "john.doe@example.com", "job_title": "Software Engineer",
    "company_name": "Acme Corp", "linkedin_profile_url": "https://linkedin.com/in/johndoe",
    "phone": "+61400000000", "resume": "https://api.refari.co/media/resumes/resume.pdf",
    "resume_name": "resume.pdf"
  },
  "referrer": { "first_name": "Jane", "last_name": "Smith", "email": "jane.smith@example.com" },
  "message": "I recommend this candidate.",
  "job": { "id": "f1e2d3c4-...", "title": "Senior Developer" },
  "source": "agency", "ownership_expiration": "2026-03-25T12:00:00Z"
}

Endpoints

What it is and why it matters

Partner Actions embed Refari's most powerful capabilities directly inside the partner's ATS. Rather than asking a recruiter to leave their system of record, a Partner Action is a configured deep-link that drops them straight into the right Refari screen for a specific object, with the context already loaded: socialising an advert, generating a trackable job link, opening the job in the widget, making post-production edits, viewing all adverts for a job order, creating a job alert, creating a candidate ad, or creating a referral.

This is the Platinum tier because it is the deepest form of integration: Refari functionality appears to live inside the partner platform, the recruiter experiences a single joined-up workflow, and these features are often strong enough to help win business in sales presentations.

How the integration works

1. Create a Partner Action with createPartnerAction, supplying the obj_type and the external_id of the target object. The response returns the Refari id, which becomes the action_id in the deep-link.
2. Configure a matching action in your ATS whose URL follows the structure for that obj_type.
3. When a user triggers the action, your ATS builds the URL with the live action_id and external_id (plus candidate fields where required) and opens it; Refari resolves the object and renders the screen.

Common parameters: action_id is always required. external_id is required for Job Ad and Job Order actions and optional for Candidate actions (if provided and the candidate exists, the existing record is used).

Object types & target URLs

Job Ad actions · object must already exist in Refari · base https://app.refari.co/dashboard/job-ads/?action_id={action_id}&external_id={external_id}

Job Order actions · object must already exist · base https://app.refari.co/dashboard/jobs/?action_id={action_id}&external_id={external_id}

Candidate actions · require first_name, last_name, email; external_id optional · query ?action_id=&first_name=&last_name=&email=&external_id=

Endpoints