Employment Hero
Connect Employment Hero to manage people, leave, timesheets and rosters, check certifications and policies, and run payroll.
Employment Hero has two separate APIs. For HR, create an OAuth 2.0 application in the Developer Portal, add PopMCP's redirect URL, enter its Client ID and Client secret, then sign in and pick the organisation. For Payroll, generate an API key under My Account and enter that. Fill in either or both.
Paid plan required before this connector works
The HR API needs an Employment Hero Platinum subscription or above, which is what opens the Developer Portal. There is no review: an application works as soon as you create it.
- Typical wait
- None once you are on Platinum or above.
- Cost
- Employment Hero's API documents name no separate fee. See Employment Hero for what a subscription costs.
- Blocked until approved
- On a lower subscription there is no Developer Portal, so no HR application and no HR tools.
- Works meanwhile
- Connect Payroll with an API key from My Account in Employment Hero Payroll. That needs no application.
Where to apply: Upgrade through Employment Hero's sales team or the live chat in the HR platform.
- Scopes are chosen once when an application is created and cannot be changed, so tick everything you may want.
- The connection can only see what the person who signed in can see, so sign in as an owner or admin.
- If your organisation enforces single sign-on, one sign-in reaches one such organisation.
- Setup time
- 5 min
- Auth
- OAuth authorization
- API base URL
- https://api.employmenthero.com
- Rate limits
- The HR API allows 20 requests a second and 100 a minute. The Payroll API allows 5 requests a second per key and address. Going over answers 429 until the window passes.
Before you begin
- For HR: an Employment Hero account on a Platinum subscription or above, which is what opens the Developer Portal. Sign in as an owner or admin: the connection can only see what that person can see.
- For Payroll: a login to Employment Hero Payroll. The API key can do what you can do in Payroll, so use a login with the right access.
- PopMCP's redirect URL for the HR application, shown on the connect form: https://app.popmcp.com/api/providers/employment-hero/callback
Get your credentials
Decide which parts you need
Use HR for people, leave, timesheets, rosters, certifications, policies and payslips. Use Payroll for pay runs, pay categories and the rest of Employment Hero Payroll. If you only use Payroll, skip to the step on the API key: you need no application and no sign-in.
Open the Developer Portal
Sign in at secure.employmenthero.com as an owner or admin. Open the menu under your name in the top right corner and click Developer Portal. If you do not see it, your subscription is below Platinum.
Create an application with PopMCP's redirect URL
Add a new OAuth 2.0 application. Give it a name such as PopMCP, and under Redirect URI(s) paste https://app.popmcp.com/api/providers/employment-hero/callback. Under Scope, tick everything you may want, because scopes are a one-time choice: they cannot be changed once the application exists. It must include the organisations scope, or PopMCP cannot list your organisations.
Register an application
Copy the Client ID and Client secret
Open the application's details page and copy its Client ID and Client secret.
PopMCP
- Client ID
- u6zcls9nx3b9Lq0sSLg****
- Client secret
- 75bAHTX7oo2ksTgnZO7****
Generate a Payroll API key, if you use Payroll
In Employment Hero Payroll, click your name in the top right corner, then My Account. Click Generate API Key, then copy the key. Clicking Change API Key later replaces it, and anything using the old one stops working.
Enter them in PopMCP and connect
On the Employment Hero form in PopMCP, enter the Client ID and Client secret for HR, the Payroll API key for Payroll, or both. Click Connect Employment Hero. With an application, sign in on Employment Hero's page and grant access, then choose the organisation to connect. With a key alone, choose the Payroll business.
Connect in PopMCP
Open your workspace, choose Employment Hero in the marketplace, and fill in the connect dialog:
| Field | What to enter |
|---|---|
| Client ID (for HR)text | In Employment Hero, open the menu under your name, choose Developer Portal and add an OAuth 2.0 application. Add the Redirect URL shown here, tick the scopes you want, then copy its Client ID. Leave this empty if you only use Payroll. |
| Client secret (for HR)secret | On the same page as the Client ID. Stored encrypted and used only on our server.Encrypted with AES-256-GCM on save and never shown again. |
| Payroll API keysecret | In Employment Hero Payroll, click your name, open My Account and click Generate API Key. Leave this empty if you only use HR. The key can do what you can do in Payroll.Encrypted with AES-256-GCM on save and never shown again. |
https://app.popmcp.com/api/providers/employment-hero/callbackIn the Developer Portal, add this as your app's Redirect URI. It must match exactly, or Employment Hero refuses the sign-in.
PopMCP verifies the credential against Employment Hero immediately. On success the connection flips to Verified and its MCP tools are provisioned.
Verify it worked
PopMCP shows Employment Hero as Connected under your organisation's or business's name. employment_hero_headcount_summary returns your people, or employment_hero_payroll_list_pay_runs returns your pay runs.
Troubleshooting
There is no Developer Portal in the menu
Why: API access is available on a Platinum subscription and above.
Fix: Upgrade through Employment Hero, or connect with a Payroll API key if Payroll is what you need.
Employment Hero shows an error instead of asking for access
Why: PopMCP's redirect URL is not on your application, or differs by a character.
Fix: On your application in the Developer Portal set a Redirect URI to `https://app.popmcp.com/api/providers/employment-hero/callback` and connect again.
"Employment Hero did not accept the app's Client ID and Client secret"
Why: A value was mistyped, or the secret belongs to another application.
Fix: Copy both again from the application's details page in the Developer Portal.
"Employment Hero would not list your organisations"
Why: The application was created without the organisations scope. Scopes cannot be added later.
Fix: Create a new application with `urn:mainapp:organisations:read` ticked and connect with that one.
A tool answers 403
Why: Either the person who signed in lacks that role, or the application lacks that scope.
Fix: Connect again as an owner or admin. If that does not help, create a new application with the missing scope.
"Employment Hero Payroll did not accept that API key"
Why: The key was mistyped, or someone clicked Change API Key, which replaces the old one.
Fix: Copy the current key from My Account in Payroll and connect again.
Payroll tools ask for a businessId
Why: Your key reaches several businesses and none has your HR organisation's exact name, so PopMCP did not guess.
Fix: Ask the AI to run employment_hero_payroll_list_businesses and name the business in each request.
A Payroll tool answers 404
Why: Some Payroll tools exist only for some countries, and the tool's description says which.
Fix: Use the tool for your business's country. Search with employment_hero_search_tools.