Gusto

Connect Gusto to Oleria to use your payroll system as the authoritative worker record. Oleria reads your Gusto company’s employees, contractors, company admins, departments, work locations, and reporting lines, so a leaver who still holds access in another application is visible. You connect by approving Oleria’s Gusto app as a Gusto company admin. Oleria can also terminate and reinstate employees, move people between departments, and create employees.

​

What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your Gusto company:

• Employees - every employee Gusto lists, with name (using the preferred first name when set), work email, personal email, employee code, department, and job title. Each employee appears as an account and as an employee record, with employment type, start date, manager, company name, and the work location of their primary job.
  • An employee whose termination is in effect, or dated today or earlier, shows as disabled, with the termination date as the account’s expiration date and the employee’s end date. Gusto puts a termination into effect only after its date, so Oleria disables the account from the date itself.
  • An employee with a termination scheduled for a later date stays enabled until that date, with the scheduled termination date as the expiration date.
  • A rehired employee shows as enabled.
• Contractors - every contractor, shown as an external user and as an employee record with employment type Contractor. A contractor is enabled when Gusto reports them as active, and their dismissal date is the account’s expiration date and end date. Individual contractors also appear as people. Business contractors appear under the business name, with an employee record but no person.
• People - the person behind each employee and individual contractor, with their name and personal email, linked to their employee record.
• Company admins - every Gusto company admin, as an administrator account with the Company Admin role. Gusto has no admin status, so admins always show as enabled.
• Roles - two Gusto roles:
  • Company Admin, held by every company admin;
  • Primary Payroll Admin, held by the admin whose email matches the company’s primary payroll admin.
• Departments - each Gusto department appears both as a department and as a group. Employees and contractors in the department are its members.
• Work locations - each work location appears as a group named after its street, city, and state. Employees are members of the location of their primary job.
• Reporting lines - which employee manages which, used to build your organization hierarchy.
• Activity - events from the Gusto company event feed:
  • employees and contractors created, updated, or deleted;
  • terminations, termination cancellations, and rehires;
  • contractor deactivations and reactivations;
  • company suspensions and other company changes.
  Oleria keeps every other event too, under its Gusto event name. Events about an employee or contractor are linked to their account, events about a work location to its group, and company events to the Gusto integration. Other events have no affected object.

Oleria refreshes this data on its regular sync schedule.

​

Prerequisites

• A Gusto user who is a company admin of the Gusto company you want to connect.
• Admin access on the Oleria platform to add a new integration.

Each integration connects one Gusto company. If you have more than one company, add an integration for each. See Multi-instance support.

​

Gusto scopes

You don’t create an API key or an app in Gusto. Oleria connects through its own Gusto app, and you approve that app for your company. The integration uses these Gusto scopes:

​

Connect Gusto to Oleria

​

Reconnect the integration

If Gusto stops accepting Oleria’s access, for example because the Oleria app was disconnected from your Gusto company, the sync fails with an error that says to reconnect the integration. To reconnect, edit the Gusto integration in Oleria, select Update, and approve the Oleria app in Gusto again. Sign in as a company admin of the same Gusto company. If you approve the app for a different Gusto company, Oleria refuses the update and keeps the existing connection. To connect another company, create a new Gusto integration. If Oleria can’t confirm which company the integration is connected to, it also refuses the update. Try again. Oleria also checks at the start of each sync that its access is still bound to the company it connected to. If it isn’t, the sync fails with an error that names both company IDs and says to reconnect.

​

Verify the integration

Confirm the Gusto company appears on the Connected tab of your Oleria Integrations page with a status of Healthy. After the first sync completes, review the discovered employees, contractors, admins, departments, work locations, and activity in your Oleria workspace. In the integration’s Capabilities and operation readiness section, Read users, Read groups, and Read roles show Available. They need these scopes: Oleria reads the scopes your approval holds from Gusto. If one of them is missing, the row shows Needs permission.

​

Remediation actions

Oleria can take these actions in Gusto: Before it offers an action, Oleria checks that your approval holds the action’s scopes: Keep these limits in mind when you use these actions:

• Oleria reads the employee or department before it makes a change. If it’s already in the requested state, Oleria makes no change, and reverting the action makes no change either.
• Oleria sends each change to Gusto once and doesn’t resend it. If Gusto doesn’t answer, the action fails. Run it again: because Oleria reads first, a change that Gusto already made is reported as no change. That run records nothing to revert, so undo the change in Gusto if you need to.
• Reverting an action changes only what the action changed. If someone changed the employee or department since, the revert makes no change and says why.

Disable user accounts and Enable user accounts

• These actions apply to employees only. Oleria refuses contractors and company admin accounts when it checks the action, before it runs. To end a contractor’s engagement, deactivate them in Gusto.
• Oleria refuses to terminate or reinstate the Gusto user who approved the connection. When a company admin approved it, Oleria compares the admin’s email address with the employee’s personal and work email addresses. If Oleria can’t confirm the employee isn’t that user, it refuses. This includes when it can’t read the company admins, when the admin has no email address, and when the employee has neither a personal nor a work email address.
• Terminations are dated with today’s date in US Pacific time, because Gusto doesn’t report a company time zone. Oleria doesn’t run a termination payroll. Gusto puts the termination into effect after that date, but Oleria shows the account as disabled from the next sync.
• Gusto allows one termination per employee. If the employee already has a termination in effect, or one dated today or earlier that hasn’t taken effect yet, Disable user accounts makes no change. If a termination is scheduled for a later date, the action fails and names that date. Move the date in Gusto to disable the account sooner. If the termination is in effect but a rehire is scheduled, the action fails and names the rehire date, because the account would come back on that date. Cancel the rehire in Gusto first.
• Reverting Disable user accounts usually rehires the employee. Gusto cancels only a termination dated in the future, and this action dates the termination today, so a revert on the same day may fail until the termination takes effect. If the revert fails, rehire the employee in Gusto. If the termination was removed, a later termination exists, or the employee was reinstated since, the revert makes no change.
• Enable user accounts makes no change for an employee whose termination is scheduled for a later date. The account is still enabled until then, and the departure is HR’s decision. To cancel it, change it in Gusto.
• Enable user accounts cancels a termination dated today or earlier that hasn’t taken effect yet. Gusto may refuse to cancel a termination on or after its date. If it does, run the action again once the termination takes effect, and Oleria rehires the employee instead. It can’t cancel a termination that has a termination payroll. Change it in Gusto.
• When Oleria rehires an employee, the rehire takes effect the day after the termination, or today if that’s later. Oleria rehires the employee at their active work location, or else their most recent one, or else the location of their primary job, and doesn’t file a new-hire report. If the employee has no work location, the action fails. Reinstate them in Gusto. If a rehire is already scheduled after the termination, the action makes no change. If the employee still has a rehire from an earlier employment that has taken effect, Oleria moves that rehire to the new date instead of creating another. Any other existing rehire makes the action fail.
• Reverting a rehire deletes it while it hasn’t taken effect. Gusto doesn’t let Oleria delete a rehire that has taken effect, so Oleria terminates the employee again, dated today.
• Reverting a cancelled termination re-creates the termination with its termination payroll setting, unless the employee has a termination again. It keeps the original date if that date hasn’t passed. Otherwise it dates the termination today, so the last day of work is never backdated.

Add user to group and Remove user from group

• These actions apply to department groups only. Work location groups follow each employee’s job, so Oleria refuses them when it checks the action, before it runs. Change the employee’s job location in Gusto.
• These actions apply to employee and contractor accounts. Oleria refuses company admin accounts. Target the person’s employee or contractor account instead.
• A person belongs to one Gusto department, so adding someone to a department moves them out of their current department. After each change, Oleria reads the department again to confirm it. If the change isn’t there, the action fails.
• Reverting Add user to group removes the person from the department, then adds them back to their previous department. If they’ve left the department since, the revert makes no change and doesn’t restore their previous department. If restoring the previous department fails, the revert fails and names that department.
• Reverting Remove user from group makes no change if the person has joined another department since, because adding them back would move them.

Create user

• The new employee starts onboarding in Gusto. Oleria sends only the first name, last name, and email address. Oleria still requires a username, but doesn’t send it, a password, or groups to Gusto.
• Before it creates the employee, Oleria looks for an existing employee with the same personal or work email address, ignoring case. If that employee is active or has a termination that hasn’t taken effect, the action makes no change and returns the existing employee. If that employee’s termination is in effect, the action fails. Use Enable user accounts to reinstate them instead.
• Reverting Create user deletes the employee only while they’re still onboarding. Once they’ve finished onboarding, the revert makes no change. Use Disable user accounts instead.

Oleria can’t grant or remove the Company Admin or Primary Payroll Admin role, delete employees outside of reverting Create user, or change contractors’ status.

​

Known limitations

• No sign-in data. Gusto doesn’t expose how users sign in to Gusto, so MFA and SSO show as unavailable. Gusto also doesn’t report last sign-in or password changes, so Oleria doesn’t detect or disable dormant Gusto accounts.
• 30 days of activity. Gusto keeps its event feed for 30 days. When you connect, Oleria reads the events from the last 30 days. If Oleria can’t sync for longer than 30 days, events older than that are lost, and Oleria continues from the oldest event Gusto still has.
• No actor on events. Gusto events don’t say who made the change, so activity isn’t attributed to any account. Events don’t include an IP address.
• Activity may be skipped. If Oleria’s Gusto app can’t read the event feed, Oleria skips activity and syncs everything else.
• Admins are separate accounts. A company admin who’s also an employee appears as two Gusto accounts: an admin account and an employee account.
• Primary Payroll Admin by email. If the company’s primary payroll admin isn’t also listed as a company admin with the same email address, no one is shown with the Primary Payroll Admin role.
• Flat departments. Gusto departments have no parent department, so department hierarchy isn’t discovered.
• Location membership. Only employees are members of work location groups, through the location of their primary job. Contractors aren’t.
• US Pacific dates. Termination and rehire dates use today’s date in US Pacific time. For a company on Eastern time, an action between midnight and 3:00 a.m. is dated the previous day. For a company in Alaska or Hawaii, an action late in the evening is dated the next day.
• No non-human identities or AI agents. Gusto’s API doesn’t expose API tokens, connected apps, service accounts, or AI agents, so none appear.

​

Contact us

For questions about this integration, contact us at support@oleria.com.