Connect Employment Hero
Employment Hero is a cloud HR and payroll platform used by organisations in Australia, New Zealand, the United Kingdom, Singapore, Malaysia and Canada. It holds the employee records, leave, documents,…
Written By Christopher Scaminaci
Last updated About 3 hours ago
Employment Hero is a cloud HR and payroll platform used by organisations in Australia, New Zealand, the United Kingdom, Singapore, Malaysia and Canada. It holds the employee records, leave, documents, onboarding and offboarding, timesheets and rosters, the asset register, forms, goals, benefits and pay data. StackJack talks to it through Employment Hero's own API.
Connecting Employment Hero to StackJack gives your AI assistant a family of eh_ MCP tools. MCP (Model Context Protocol) tools are the standardized commands an AI assistant can call through StackJack. With them, your AI can:
- See who is out of office - one request lists leave across the whole organisation for any date range and any approval status, so "who is off next week?" is a single question
- Look people up - employees and contractors, teams (called Groups in the Employment Hero product), employment and job history, emergency contacts, work eligibility and custom fields
- Onboard and offboard - add an employee or contractor, run a full onboarding and follow its progress, and end someone's employment. This is the hand-off point to your other tools: a new hire in Employment Hero becomes an account to create, and a leaver becomes an account to disable
- Manage leave - read balances, categories and requests, raise or change a request, and approve or decline one
- Handle employee documents - list the documents held for an employee and upload a new one, plus the compliance document tags, certifications and policies around them
- Run time and rosters - timesheet entries and their approval, rostered shifts and their cost, roster unavailability, Hero Time Clock access and sales or forecast data
- Read and shape the organisation - work sites, work locations, departments, positions, cost centres and employing entities
- Track the asset register - assets, their categories and custom fields, who holds each one, and the assign, return, reassign and dispose steps that follow a laptop or phone through its life
- Work with forms and goals - form templates, forms, assignments and responses, and goals with their key results and check-ins
- Read pay and benefits - pay details, payslips, pay categories, awards, classifications and the benefits assigned to each person
- Read payroll identity details - bank account, superannuation and tax records, on request only. These are sensitive and are labeled that way
- Read the Careers Page (optional) - the countries, departments and public jobs published on your own careers site
Reading is available on every plan. Anything that changes data, from raising a leave request to uploading a document, is on Pro plans, and anything that cannot easily be undone is labeled as a change that needs approval.
See the generated Employment Hero tool reference for the current inventory, plan assignment, input schemas, and destructive-action labels.
What you need before you start
- An Employment Hero plan that includes API access. That is HR Elite or Employment Unlimited. An organisation on HR Essentials or HR Engage cannot connect. If you are not sure, ask your Employment Hero account manager first.
- An owner or admin account in Employment Hero. You use it twice: to create the API application, and to sign in. The connection carries the permissions of the person who signs in, so an owner or admin sees the most. A narrower account sees less, and most tools then answer with a permission error.
How StackJack connects to Employment Hero
Employment Hero has no API key. Instead, each organisation creates its own API application in Employment Hero, and StackJack signs in to Employment Hero through that application. You create the application once, copy its Client ID and Client Secret into StackJack, and then sign in. The application belongs to your organisation. StackJack does not own one, and no other StackJack customer uses yours.
StackJack keeps the connection current afterwards, so you do not sign in again unless you disconnect it or move to a different application (a different Client ID). Replacing only the Client Secret keeps your sign-in.
Step 1: Create the API application in Employment Hero
Sign in to Employment Hero with an owner or admin account for the organisation you want to connect.
Open the Developer Portal, in the menu under your profile name (some accounts show it under Settings), and add an application. Employment Hero's own page for it is
https://secure.employmenthero.com/app/v2/organisations/<your organisation id>/developer_portal/api/new, with your organisation id in place of the placeholder.Give the application a Name, for example "StackJack".
Set the Redirect URI to the address for your StackJack region. The StackJack connector card shows the right address for your account, with a Copy button.
Copy the address exactly. Employment Hero lets you add several Redirect URIs separated by commas, so an organisation that uses both regions can list both.
Choose the scopes. This is the one step you cannot repeat, so read the next section first.
Save the application. On its details page, copy the Client ID and the Client Secret.
Choose the scopes carefully: you cannot change them later
Employment Hero fixes an application's scopes when the application is created. You can edit everything else about it, but not its scopes. A scope you leave out only makes the tools in that area answer with a permission error, and every other tool keeps working. The only way to add the missing scope later is to create a new application, which has a new Client ID and a new Client Secret, and to connect again with them.
The safest choice is to tick every scope Employment Hero offers, delete scopes included. The application can still only do what the person who signs in is allowed to do, and StackJack labels every change that cannot easily be undone as one that needs approval.
Employment Hero names its scopes itself, and its public documentation does not list them all, so match the areas below to the names its form shows (two of its names are Employee - Delete and Goals - Delete). Work down this list and make sure each area has the access shown:
- Organisations: read. Lists and reads the organisations you can see.
- People: read, write and delete. Employees and contractors, teams (called Groups in Employment Hero), custom fields, emergency contacts, employment and job history, work eligibility, onboarding and offboarding. Delete covers deleting an employee.
- Leave and availability: read, write and delete. Leave balances, categories and requests, and unavailability. Delete covers deleting a leave request.
- Documents and compliance: read, write and delete. Employee documents, certifications, compliance document tags and policies. Delete covers deleting a certification.
- Time and rostering: read, write and delete. Timesheet entries, rostered shifts, Hero Time Clock access, roles and tags, work types and sales data. Delete covers deleting a timesheet entry.
- Organisation structure: read and write. Work sites, work locations, departments, positions, cost centres and employing entities.
- Assets: read, write and delete. Assets, categories, custom fields and assignment history. Delete covers deleting an asset, a category or a custom field.
- Forms: read, write and delete. Form templates, forms, categories, assignments and responses. Delete covers deleting a form, a template or a category.
- Goals: read, write and delete. Goals, key results, comments and check-ins. Delete covers deleting a goal or a key result.
- Pay and benefits: read, write and delete. Pay details, payslips, pay categories, awards and classifications, and the benefits assigned to each person. Delete covers removing an employee benefit.
- Payroll identity: read. Bank account, superannuation and tax records. These are sensitive.
The three Careers Page tools do not use an application scope. They use the separate Careers Page access token described below.
Step 2: Enter the Client ID and Client Secret in StackJack
- Open Connectors in the StackJack portal and choose Employment Hero.
- Click Add connection if you already have one, and name it after the customer.
- Paste the Client ID and the Client Secret from the application's details page.
- Click Connect Employment Hero, sign in to Employment Hero with an owner or admin account, and approve the application.
- Optional: open the connection again and enter a Default organisation id. Every Employment Hero request names an organisation, and a saved default lets your AI leave it out. Ask your assistant to list your organisations if you do not know the id, then click Save.
- Optional: paste a Careers Page API access token if you want the three Careers Page tools. In Employment Hero open General Settings, then Recruitment Settings, and copy the token once the Careers Page is enabled. It is a separate credential from your sign-in and is not checked by Test Connection.
- Use Test Connection. It reads the first organisation your account can see, which confirms the sign-in without touching any employee data.
StackJack stores the Client Secret encrypted and never shows it again. When you open a connected card, the Client ID is filled in and the Client Secret box is empty. Leave the secret blank and click Connect Employment Hero to sign in again with the saved secret, or click Save to keep the connection as it is.
Changing the application, the Client ID or the Client Secret
- You changed only the Client Secret of the same application. Open the connection, paste the new secret, keep the same Client ID and click Save. Your sign-in is kept, so nobody has to sign in again.
- You created a new application. Paste its Client ID and its Client Secret together and click Connect Employment Hero. StackJack never uses a saved secret with a different Client ID, and a different application always needs a fresh sign-in, because a sign-in belongs to the application it was made with. Save stores the default organisation, the Careers Page token and a new Client Secret for the same application, so it refuses a different Client ID and points you to Connect Employment Hero.
One connection per customer organisation
A connection reaches the organisations the signed-in person can see. If you look after several customers, add one connection for each and name it after the customer, for example "Acme Pty Ltd" and not "Employment Hero 2". Each connection keeps its own Client ID and Client Secret. Your AI then knows which organisation you mean when you ask "who is out of office at Acme?". An organisation that enforces single sign-on can only be authorised once per connection, so add a separate connection for each of those.
Good to know
- Dates. Employment Hero uses
YYYY-MM-DDalmost everywhere. Two places differ: the termination date when you offboard someone, and the date filters on the timesheet list, both of which useDD/MM/YYYY. Your AI knows this, but it is the first thing to check if a date is refused. - Leave balances work only for organisations that use Employment Hero's own leave, not for payroll-connected organisations.
- Documents can be listed and uploaded for one employee at a time. Employment Hero offers no way to update or delete a document, or to list documents across the whole organisation, so check the employee and the name before you upload.
- Some requests finish later. Creating or changing a certification, onboarding an employee and creating many rostered shifts at once answer with a reference, and a second request reads the outcome. Your AI follows up on its own.
- Some changes email people or change pay. Changing a salary, work hours or a leave balance alters pay or entitlements, and creating, publishing or assigning a form, granting or removing Hero Time Clock access and assigning many assets at once reach real people. These are labeled as changes that need approval, as are deletes, offboarding, and approving or declining a leave request or a form response. Assigning, reassigning or creating a single asset and updating a certification can email someone too, but only when your AI turns that email option on, and they are not labeled that way, so say in your request whether people should be told.
- Offboarding and deleting are different. Offboarding ends employment and keeps the record. Deleting removes the employee file and cannot be undone.
- Rate limits. Employment Hero allows 20 requests a second and 100 a minute. A very large list is better narrowed with a date range than read page by page.
Troubleshooting
- StackJack says Employment Hero needs an API application. The connection has no complete Client ID and Client Secret. Create the application in the Employment Hero Developer Portal (in the menu under your profile name; some accounts show it under Settings), paste both values into the Employment Hero connector in StackJack and click Connect Employment Hero.
- StackJack says a Client Secret is needed. You entered a different Client ID without its Client Secret. A saved secret belongs to the application it was created for. Enter the Client Secret of the application the new Client ID belongs to.
- "Employment Hero refused the Client ID and Client Secret saved on this connection". The application was deleted, or its Client Secret changed. In the Employment Hero Developer Portal (in the menu under your profile name; some accounts show it under Settings), check the application, then enter its current Client ID and Client Secret and click Connect Employment Hero.
- StackJack says the Employment Hero sign-in could not be completed, after you approved the application. Employment Hero did not accept the Client ID and Client Secret when StackJack finished the sign-in. The Client Secret is only used at that last step, so a mistyped or out-of-date secret shows up here and not earlier. Check that the Client Secret belongs to the application whose Client ID is on the connector card, enter both again and click Connect Employment Hero.
- Employment Hero reports a problem with the redirect while you sign in. The Redirect URI on your application does not match the address on the connector card. Copy the address from the card again, with its Copy button, and save it on the application.
- "Employment Hero no longer accepts this connection's sign-in". The sign-in was revoked or has expired. Open the connector and click Connect Employment Hero again.
- A tool answers with a permission error while others work. Either the account that connected does not have permission for that area, or the scope for that area was not ticked when the application was created. Connect with an owner or admin account first. If the same area still answers with a permission error, the application is missing that scope: create a new application with every scope ticked, then connect again with its Client ID and Client Secret. Also check that the plan includes API access.
- A tool names no organisation. Either pass the organisation id, or save a default organisation on the connection.
Employment Hero tools
eh_ · 167 tools · Free 75 · Pro 92
Organisations
People
Leave and availability
Documents and compliance
Time and rostering
Organisation structure
Assets
Forms
Goals
Pay and benefits
Payroll identity
Careers Page
Was this helpful?
More in Connector guides
Connect 3CXConnect AbleSignConnect Acronis Cyber Protect CloudConnect Action1Still need help? Ask the team