Approval Groups

An approval group is a set of workers that are managed together. Every worker belongs to at most one group. Groups are small to set up, but they decide a lot downstream, so it pays to assign each worker to the right group when you create them rather than fixing it later.

Typical groups are a branch office, a client site, a department, or a staffing customer.

Why approval groups matter

1. They organize your workforce in the admin portal

Admins filter and review workers, timesheets, payments, and reports by group. A payroll admin who runs payroll for the Denver branch can look at only the Denver branch. Without groups, every worker is in one undifferentiated list.

2. They control who can see, manage, and approve workers

An approval group is also a permission boundary. You can name delegated approvers for each group: people who aren't company-wide admins, such as a branch manager or a client contact. An approver's access is limited to the groups they're assigned to, and to the kinds of work you grant:

A worker who isn't in a group can't be reached by any delegated approver. Only company-wide admins, and your API token, see every worker.

So the group you assign decides which people can see a worker's data and approve their pay. Assign it correctly, and treat a change of group as a change of access.

Approvers are set up in the Everee admin portal. The public API doesn't manage approvers.

3. They drive GL coding for finance reporting

Wages are coded to the approval group of the worker's earnings, so a group is how you split payroll cost by branch, client, or department:

• If your company scopes GL mappings by approval group, each group can post to its own GL codes.
• The Payroll Journal report and the journal exported to your accounting system can be split by approval group.
• Reports can be filtered by group, so each branch or client can reconcile its own payroll.

Employer taxes and benefit costs on a payment follow the wages, so they land in the same group. See Reconciling payroll and your general ledger.

4. Other places groups show up

• Leave and scheduling. Leave requests and shifts are handled by the approvers of the worker's group.
• Worker data. A worker's group is returned on the worker record as approvalGroup, and changing it sends a worker-updated webhook. See Webhook events.
• Deleting a group. When a group is deleted in the admin portal, its approvers are removed and its workers are left with no group. If you didn't expect that, re-assign the workers.

The workflow

You set groups up once, then assign them as you create or update workers.

Step 1: If your groups are managed outside Everee, create and update them in Everee

If your system is the source of truth for groups (a staffing platform's clients, an HR system's departments), mirror them into Everee. Create each group once and store the Everee id against your own record, so you never need to look it up again:

POST https://api.everee.com/integration/v1/approval-groups

{ "name": "Denver Branch" }

{ "id": "1000", "name": "Denver Branch", "deleted": false }

The public API creates and lists groups. It doesn't rename or delete them, and it doesn't manage approvers. Make those changes in the admin portal, or ask the customer to. Before creating a group, list the existing groups and match on name so you don't create duplicates.

Step 2: If your groups are managed in Everee, retrieve the list to get their IDs

If the customer sets up groups in Everee, don't ask them to type IDs. Read the groups and let them map each of their own records to one:

GET https://api.everee.com/integration/v1/approval-groups

Results are paged, so follow the page links until you have them all. Refresh the list when you need it, for instance before showing a picker or at the start of each sync, since groups can be added or deleted in the portal. Deleted groups aren't returned.

Step 3: Pass the ID when you create or update a worker

Send approvalGroupId with the worker. It's optional, so you can create the worker without it, but then the worker has no group and no delegated approver can see them.

POST https://api.everee.com/integration/v1/workers/employee

{
  "firstName": "Jordan",
  "lastName": "Example",
  "approvalGroupId": "1000"
}

(The example shows only the group field. See the create endpoint for everything it requires.)

To move a worker later, or to take them out of a group, call Update approval group. Send the new ID, or null to remove their group.

Recommended practice

• Assign the group when you create the worker. Don't create workers first and sort them out afterward: until they're in a group, their approvers can't see them, and hours and payments they generate aren't coded to it.
• Treat the group as part of the worker's identity. If a worker moves branches or clients, update the group in the same sync that updates their position and pay.
• Store the ID, not the name. Names can be changed in the portal. IDs don't change.
• Create groups before the workers that need them, as part of setting up your organization.

Related

• Setting up your organization
• Create an approval group, List approval groups, Update approval group
• Scoping GL mappings by approval group