# 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:

1. Lists hired applications.
2. Skips the ones it has already synced.
3. For each new one, reads the candidate and the job, and creates the employee in your HR system.
4. 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](https://hirehappy.io/docs/api/applications#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.

```python
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.

> [!NOTE]
> 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](https://hirehappy.io/docs/api/applications#update-application), which needs `applications:write`):

```bash
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 internal `rejection_reason`.
- **Withdrawals**: `status=withdrawn`, with the candidate's own `withdrawal_reason`.
- **A stage**, like everyone in Offer: `stage_id`, from [the job's stages](https://hirehappy.io/docs/api/job-stages#list-job-stages).
