To integrate an EOR API, you connect your HR, payroll or internal tooling to an Employer of Record’s platform so hires, contract changes, payroll inputs and payslips move between systems without manual re-entry. The work follows five steps: confirm the provider’s legal and data model, authenticate in a sandbox, map your employee data, subscribe to events, and test before you go live. This guide walks through each step, with attention to a single-country setup such as South Africa.
TL;DR
- An EOR API automates the paperwork side of employing someone through a third party: hires, job and pay changes, payroll results and documents.
- Expect OAuth 2.0 or API-key access, scoped permissions, a sandbox, and webhooks for status changes. Check which of these the provider documents publicly before you commit.
- The legal employer stays the EOR. Your integration should never blur who owns contracts, statutory filings and payroll liability.
- Build in stages: sandbox, field mapping, event handling, reconciliation against a real payroll cycle, then production.
- Our own REST API has public docs and sandbox keys, so your developers can test before anyone signs anything.
Table of Contents
- What an EOR API is, and what it can do
- What to check before you write any code
- The stages of an EOR API integration
- Authentication: how to connect safely
- Mapping your data to an EOR’s schema
- Webhooks and events
- Automating onboarding and the employment lifecycle
- Testing, security and troubleshooting
- Why a single-country EOR API can be simpler
- What we do
- Our perspective
- FAQ
- Sources
What an EOR API is, and what it can do
EOR stands for Employer of Record. A third-party company legally employs a worker on your behalf and manages contracts, payroll and benefits, while you direct the daily work (Workday). That split matters for any integration. The EOR is responsible for local contracts, payroll, taxes and statutory compliance; you keep control of the work itself, compensation strategy and performance.
An EOR API exposes that relationship as software. Typical uses:
- Creating an employee record from your applicant tracking system once an offer is accepted.
- Pushing changes such as salary reviews, role changes, leave balances or termination requests.
- Pulling results, such as payslips, cost reports, statutory deductions and employer cost totals, into your finance system.
- Receiving events, such as “contract signed” or “payroll finalized,” so your internal workflows advance without anyone checking a dashboard.
In an integration between an EOR and a core HR system, the data exchanged is standardized: hires, job and compensation changes, time and payroll results, with controls and audit trails kept in the core system (Workday). Employee portals sit on the same data. If you are deciding what employees should see in a self-service layer, this overview of employee portal benefits for HR teams helps frame which payroll and profile fields belong there.
What to check before you write any code
Most failed integrations fail in the contract and data design, not in the HTTP calls. Settle these points first.
1. Who is the legal employer
Your API calls create records, but the legal employment contract sits with a local entity. Ask which entity that is, how it is licensed, and what happens to your employees if the arrangement ends. We cover this in six checks to confirm the legal employer. Disclosure of the legal employer should appear in the data you receive, not only in a sales deck.
2. What the API covers, and what stays manual
Make a list of the lifecycle steps you want automated, then mark each as fully API, partly API or dashboard only. Common gaps: offboarding, because dismissal in many countries needs human legal judgment, and document signing, which often runs through the provider’s own interface.
3. Documentation and sandbox access
Public documentation and sandbox keys let engineers prove the integration works before procurement finishes. If a provider asks you to sign a contract before you can see a single endpoint, you are estimating effort blind.
4. Data residency and privacy
Employee records are personal data. For South African employees the governing law is POPIA, and for EU-based companies GDPR applies to what you send and store. We handle data under POPIA and GDPR with EU data residency. Whatever provider you pick, ask where data is stored and which sub-processors touch it.
5. Currency and reporting
Payroll in a single-country setup runs in local currency. For South Africa that is ZAR, with employer costs reported to you in your own currency. Decide up front which currency your finance system expects in each payload, and whether FX is applied by the provider. We charge no FX loading, which simplifies reconciliation.
6. Security review
Your security team will want to see access scopes, audit logging and incident procedures. A framework such as ISO 27001 gives the questions to ask; this guide to data security controls is a useful checklist for what auditable data exchange should look like.
The stages of an EOR API integration
The table below is the sequence we recommend. It works for any provider, though timing varies with how many systems you connect.
| Stage | What you do | What “done” looks like |
|---|---|---|
| 1. Scope | List the workflows to automate and the systems involved | A one-page spec naming each data flow and its owner |
| 2. Authenticate | Create an app, set scopes, obtain credentials, use sandbox | A successful authenticated call in the sandbox |
| 3. Map data | Match your HR fields to the provider’s schema | A field-mapping table, with gaps and defaults agreed |
| 4. Build flows | Create employees, push changes, pull payroll results | End-to-end test hire in sandbox |
| 5. Subscribe to events | Register webhooks, handle retries and duplicates | Events processed idempotently |
| 6. Reconcile | Compare API output with the first real payroll cycle | Totals match finance’s expectations |
| 7. Go live | Swap credentials, enable monitoring and alerts | Production hires flow without manual steps |
Authentication: how to connect safely
The common pattern for partner-style integrations is OAuth 2.0. You create an application in the provider’s platform, set scopes and HTTPS redirect URIs, obtain a client ID and secret, then run the flow: the customer authorizes access, you exchange the authorization code, and you receive scoped access and refresh tokens (Employment Hero Partner Guides). That same guide notes that PKCE became required there from September 30, 2026, which shows the direction of travel in the industry.
PKCE (Proof Key for Code Exchange) prevents authorization code injection and CSRF attacks in the authorization code flow, and is recommended for all OAuth clients, not only public ones (OAuth.net). Build it in from day one even if your provider does not yet demand it.
Some EOR APIs, including smaller single-country platforms, use simpler bearer API keys issued per environment. Both models are fine if you follow a few rules:
- Keep separate keys for sandbox and production, and never commit them to source control.
- Request the narrowest scope that does the job. A payslip reader does not need permission to create employees.
- Store secrets in a vault, rotate them on a schedule, and rotate immediately when a developer leaves.
- Call only over HTTPS and reject redirect URIs that are not on your allowlist.
Mapping your data to an EOR’s schema
Field mapping takes longer than authentication. Start with the objects almost every EOR exposes.
Employee and contract data
Legal name, work email, start date, job title, employment type, salary and pay frequency, and work location. For South Africa, expect additional fields such as an ID or passport number and tax reference, because the employer must register the worker for PAYE, UIF and SDL. Our guide to registering for employer payroll taxes explains why those identifiers matter.
Compensation and cost data
Gross salary, allowances, employer contributions and total employer cost. A good integration separates what the employee earns from what you pay in total, so your finance system can book each correctly. You can model the totals first with our employment cost calculator and use its output as a sanity check for the API figures.
Payroll results
Payslips, deductions and statutory filing confirmations. In South Africa the monthly employer declaration (EMP201) is due by the 7th, which determines when final payroll data should land in your system; see how that works in paying employees in ZAR.
Time off and public holidays
Leave balances and public holidays differ by country. If your project management tool shows capacity, feed it the local calendar rather than your own. Our South Africa public holidays guide lists them for HR and payroll teams.
Webhooks and events
Polling an API every few minutes works, but webhooks are cleaner. Typical events include a contract being signed, an employee being activated, a payroll run being finalized, a document being issued, and a change request being approved or rejected.
Design the receiver with these habits:
- Verify the signature on every request using the shared secret, computed against the raw body, before parsing.
- Respond fast with a 2xx status, then process the event in a queue.
- Be idempotent. Providers retry, so store event IDs and ignore duplicates.
- Expect disorder. Events can arrive out of sequence; use timestamps or version fields.
- Log everything with the payload ID so finance and HR can trace a discrepancy.
If the provider offers no webhooks, schedule a poll for changed records and keep a cursor so you never rescan the full list.
Automating onboarding and the employment lifecycle
The best-value automation is onboarding. A typical flow:
- Your ATS marks a candidate as “offer accepted.”
- Your integration creates the employee through the API with role, salary and start date.
- The EOR generates the contract from a compliant template. In South Africa that means a contract aligned with the Basic Conditions of Employment Act; see the essential contract clauses.
- A webhook tells your system the contract is signed, which triggers laptop orders, accounts and welcome emails.
- The first payroll cycle picks up the record automatically.
Other lifecycle events worth automating: salary changes approved in your HR tool, expense and allowance updates, monthly cost exports to accounting, and reminders when probation periods end.
One area to keep human: termination. In South Africa, dismissals must be procedurally and substantively fair, and disputes go to the CCMA. An API call can open a request, but a person should review the reasoning. Our risk overview for U.S. companies explains where companies run into trouble.
Testing, security and troubleshooting
Test in layers
- Unit tests on your mapping code, including awkward names, missing optional fields and unusual characters.
- Sandbox integration tests for the full create, update and terminate cycle.
- Contract tests that fail if the provider changes a response shape.
- Parallel payroll run: compare API-reported totals against a manual calculation for the first real month.
Harden the integration
- Apply least-privilege scopes and per-environment credentials.
- Encrypt personal data at rest and in transit, and avoid copying it into logs or analytics tools.
- Set retention rules so you do not hold employee records longer than needed.
- Alert on repeated authentication failures and on unexpected spikes in write calls.
Common problems and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| 401 after hours of working | Expired access token | Refresh with the refresh token, or request a new key |
| 403 on a specific call | Scope too narrow | Add the needed scope, then reauthorize |
| Duplicate employees | Retried create call | Send an idempotency key or check by email first |
| Payroll totals off by cents | Rounding or currency conversion | Compare in the local currency before converting |
| Webhooks stop arriving | Endpoint slow or failing | Respond fast, check the retry log, re-register if needed |
Why a single-country EOR API can be simpler
Global platforms cover many countries, so their schemas are generalized, and country-specific details end up in free-text or custom fields. A single-country provider can expose fields that match one jurisdiction. For South Africa that means PAYE, UIF, SDL and COIDA elements represented as they appear on the filings, rather than as generic “tax” and “benefits” lines. For a developer, that means fewer transformation rules and fewer surprises at reconciliation.
The time zone helps as well. South Africa is within about one hour of Central European Time, so your engineers and payroll contacts can resolve an integration issue in a shared working day.
What we do
We provide Employer of Record services for South Africa only. Employment runs through a licensed local partner that handles contracts, ZAR payroll and statutory filings, and our REST API comes with public docs and sandbox keys. Pricing is flat at $399 per employee per month, with no setup fees. Details are on the pricing page, and the complete EOR guide for South Africa covers the legal side.

If you are replacing an existing provider, we handle transfers at no charge, so your integration work can start in the sandbox while the move is planned.
Our perspective

We have seen integrations go wrong for a predictable reason: teams treat the API as a technical project and the employment relationship as someone else’s problem. The API is only as good as the legal and payroll engine behind it. That is why we run one country and not 150. Every field we expose maps to something a South African employer must actually file or pay, and we say plainly which entity employs your people.
Our advice to engineering leads is simple. Ask for the sandbox before the sales call. Build the create-employee flow and a webhook receiver in a day. If the provider’s documentation lets you do that without a conversation, the rest of the relationship tends to be just as clear. If it does not, you have learned something important for free.
— Roel
FAQ
What does an EOR API usually let you automate?
Most cover employee creation, contract and compensation changes, payroll outputs such as payslips, and status events. Offboarding is often partly automated, since a person should review any dismissal. Check the provider’s documentation for the exact list.
Do I need OAuth 2.0 for an EOR integration?
Not always. Partner-style platforms commonly use OAuth 2.0 with scoped tokens, while simpler APIs issue bearer keys per environment. Either is acceptable if you scope access narrowly, use HTTPS and store secrets in a vault. If OAuth is offered, use PKCE.
How long does an integration take?
A basic create-and-read integration can be running in a sandbox within days. Reaching production confidence takes longer, because you should reconcile the API’s payroll output against at least one real payroll cycle before trusting it.
Can the API replace my HR system?
No. The EOR remains the legal employer and holds the statutory records, while your HR system remains where you manage work, performance and compensation strategy. The API keeps the two in sync.
Sources
- What Is An Employer Of Record? Workday
- Employment Hero Partner Guides
- PKCE, OAuth 2.0
- Benefits of employee portals for HR professionals
- Data Security Controls for Finance Firms: 2026 Guide
