# Employment Hero setup for PopMCP 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. - Auth: OAuth authorization - Setup time: 5 min - API base URL: https://api.employmenthero.com - Credentials screen: https://secure.employmenthero.com/ - Provider docs: https://developer.employmenthero.com/api-references/authentication ## Approval required before this 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. ## 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 ### 1. 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. ### 2. 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. Screen: https://secure.employmenthero.com/ ### 3. 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. Screen: https://secure.employmenthero.com/ ### 4. Copy the Client ID and Client secret Open the application's details page and copy its Client ID and Client secret. Screen: https://secure.employmenthero.com/ ### 5. 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. ### 6. 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. ## Fields PopMCP asks for - Client ID (for HR) (clientId): 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) (clientSecret): On the same page as the Client ID. Stored encrypted and used only on our server. - Payroll API key (payrollApiKey): 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. ## Callback URL to register https://app.popmcp.com/api/providers/employment-hero/callback ## Verify 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 Cause: 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 Cause: 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" Cause: 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" Cause: 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 Cause: 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" Cause: 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 Cause: 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 Cause: 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. --- Source: https://www.docs.popmcp.com/docs/integrations/employment-hero/