Guides
Sync hires to your HR system
Create new hires in your HRIS or payroll as soon as they're hired in HireHappy, and hire from your own systems.
When a candidate is hired in HireHappy, your HR system (Personio, BambooHR, Workday, your own) needs them as an employee. This guide keeps the two in step with a small job you run on a schedule.
You'll need a key with applications:read, candidates:read and jobs:read.
How it works
An application is hired when the team moves it to its job's last stage, or marks it hired. A sync job:
- Lists hired applications.
- Skips the ones it has already synced.
- For each new one, reads the candidate and the job, and creates the employee in your HR system.
- Remembers it, so it isn't synced twice.
There are no webhooks yet, so run it on a schedule: every 15 minutes to an hour suits most teams.
The sync job
Hired applications are few, even in big organizations, so list them all each time (List applications with status=hired) rather than tracking where you left off. The list is ordered by when each application was made, not when it was hired, so a hire from an old application could be anywhere in it.
import os
import httpx
client = httpx.Client(
base_url="https://api.hirehappy.io/v1",
headers={"Authorization": f"Bearer {os.environ['HIREHAPPY_API_KEY']}"},
)
def hired_applications():
offset = 0
while True:
body = client.get(
"/applications",
params={"status": "hired", "limit": 100, "offset": offset},
).raise_for_status().json()
yield from body["items"]
offset += body["limit"]
if offset >= body["total"]:
return
def sync(synced: set[str]) -> None:
"""`synced`: the application ids already in the HR system, kept by you."""
for application in hired_applications():
if application["id"] in synced:
continue
candidate = client.get(f"/candidates/{application['candidate_id']}").raise_for_status().json()
job = client.get(f"/jobs/{application['job_id']}").raise_for_status().json()
create_employee( # Your HR system's API.
first_name=candidate["first_name"],
last_name=candidate["last_name"],
email=candidate["email"],
phone=candidate["phone"],
job_title=job["title"],
location=job["location"],
hired_at=application["updated_at"], # Its last change: the hire, when synced soon after.
external_id=application["id"],
)
synced.add(application["id"])Keep synced somewhere that lasts, like a table in your database. Better still, store the application id on the employee in your HR system (most have an external ID field), so the HR system itself knows who's synced.
An application stops being hired if the team moves it back into the pipeline, say after a hire made by mistake. Your job won't see it in the list any more. Decide whether that should undo anything on your side; usually a person should look at it.
Hiring from your own systems
The other direction works too: when an offer is signed in your HR system, mark the application hired in HireHappy (Update an application, which needs applications:write):
curl -X PATCH https://api.hirehappy.io/v1/applications/APPLICATION_ID \
-H "Authorization: Bearer $HIREHAPPY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "hired"}'This moves the application to its job's last stage and starts onboarding, as hiring in the app does: the new hire is welcomed by email to their onboarding page.
Other things to sync
The same pattern works for other moments:
- Rejections, for reporting:
status=rejected, with the internalrejection_reason. - Withdrawals:
status=withdrawn, with the candidate's ownwithdrawal_reason. - A stage, like everyone in Offer:
stage_id, from the job's stages.