Syncing Candidates
How the ATS sync works, what data flows in automatically, and how to handle sync errors.
Once your ATS is connected and live, Hire2Hero automatically keeps your candidates, placements, and clients in sync. This guide explains what syncs, how often, and what to do when something doesn't.
This guide assumes you've already completed the Connecting Your ATS setup flow and clicked Go Live.
How sync works
Hire2Hero polls your ATS for changes every 5 minutes. Each polling cycle:
- Hire2Hero fetches the list of events from your ATS's subscription service — new records, updates, and deletions since the last poll.
- For each event, Hire2Hero fetches the full record and maps it to internal fields using your configured field mappings.
- If the record is new, it's created in Hire2Hero. If it already exists, it's updated. Deletions are reflected in the record's status.
Changes you make in your ATS appear in Hire2Hero within 5 minutes. There is no manual sync button — the polling cycle handles it automatically.
What gets synced
The following entity types are synced from your ATS:
| Entity | What it maps to in Hire2Hero | Required |
|---|---|---|
| Candidate | Candidate profile (name, email, optional hire date, ATS ID) | Name, email |
| Placement | Placement record (title, dates, rates, approver, billing contact) | Title, candidate, start/end dates, pay/bill rates, billing contact, approving contact |
| Client Corporation | Client company record | Name |
| Billing Client Contact | Billing contact on the placement | — |
| Approving Client Contact | Approving contact on the placement | — |
| Job Order | Source job order for the placement | — |
When Hire2Hero syncs a placement, it automatically syncs the associated candidate, billing contact, and approving contact if they haven't been pulled in yet. You don't need to worry about entity dependencies — Hire2Hero resolves them in order.
Field mapping
The data that flows from your ATS into each Hire2Hero field is determined by the field mappings you configured during setup (Steps 3–7 of the ATS setup flow). To adjust a mapping after go-live, return to Settings → ATS Integration and update the relevant configuration step.
Candidate fields
| Hire2Hero field | Required | Notes |
|---|---|---|
| Name | Yes | Mapped from a single ATS field |
| Yes | Used as the candidate's login; must be unique | |
| Hire Date | No | Optional employment date |
| Payroll Employee ID | No | External payroll system reference |
| ATS ID | Auto | Set automatically to the ATS record ID — do not edit manually |
| VMS ID | No | Optional VMS reference |
Placement fields
| Hire2Hero field | Required | Notes |
|---|---|---|
| Title | Yes | Display name of the placement |
| Candidate | Yes | Links to a synced candidate record |
| Start Date | Yes | Placement effective date |
| End Date | Yes | Placement end date |
| Pay Rate | Yes | Candidate pay rate |
| OT Pay Rate | Yes | Overtime pay rate |
| Bill Rate | Yes | Client bill rate |
| OT Bill Rate | Yes | Overtime bill rate |
| Billing Contact | Yes | Billing client contact for invoicing |
| Approving Contact | Yes | Client contact who approves timecards |
New placements arrive with a status of Pending until an administrator reviews and activates them.
Handling sync errors
When a record fails to sync, Hire2Hero logs the error and continues — a single failed record doesn't block the rest of the sync cycle.
Viewing errors
Sync errors surface as an error banner at the top of the ATS integration page (Settings → ATS Integration). The banner shows the most recent error message for the integration.
The Audit Trail (Step 13) is not a sync error log — it records configuration changes to your ATS setup (field mappings, filters, etc.) and lets you download them as a file. Sync errors appear only in the error banner.
Common errors and fixes
| Error | Cause | Fix |
|---|---|---|
| Required field missing | A required field in your ATS record is empty | Fill in the missing field in your ATS; it will sync on the next poll |
| Configuration not set up | A field mapping is missing for this entity type | Return to the entity configuration step and complete the mapping |
| Invalid credentials | Hire2Hero can no longer authenticate with your ATS | Return to Step 2 and re-enter your ATS credentials |
| Nested entity error | A related record (candidate, contact) failed to sync first | Fix the related record error first; the placement will retry on the next poll |
Most sync errors resolve on their own once the underlying data issue is fixed in your ATS — Hire2Hero will pick up the corrected record on the next 5-minute poll.
Connection health
If Hire2Hero loses connectivity to your ATS, an error banner appears at the top of the ATS integration page showing the last known error. Common causes:
- Password changed — re-enter credentials in Step 2 of the setup flow
- ATS API access revoked — contact your ATS account administrator to restore API access
- Network issue — transient; the connection will recover automatically once resolved
Disabling sync
To pause the integration without losing your configuration:
Navigate to Settings → ATS Integration → Step 14 (Disable).
Click Disable.
The 5-minute polling stops immediately. Your existing Hire2Hero records are not affected — no data is deleted. To re-enable, click Go Live again (Step 12).