Payroll History and Going Live

An approved company isn't live yet. Before it can run payroll on Everee, Everee imports the payroll it has already run this year and finishes setting the company up. This page covers the three things you handle along the way: the date you want the company to go live, its payroll history, and knowing when it's live.

What you see

Get onboarding status includes two objects for this, goLive and payrollHistory. goLive is also on Get a company and Get go-live status.

"goLive": {
  "live": false,
  "targetGoLiveDate": "2026-12-07",
  "targetGoLiveDateValid": true,
  "goLiveDate": "2026-12-07",
  "outstanding": ["PAYROLL_HISTORY", "EVEREE_SETUP"]
}

outstanding can list:

Set a target go-live date

Tell Everee the date you want the company to go live: the first day of the first pay period you want Everee to pay. Everee plans the company's setup around it and sets the real go-live date.

Send it with the payroll profile while the company is a draft:

curl -X PATCH https://api.everee.com/integration/v1/partner/companies/$ID/payroll-profile \
  -u "$KEY:" -H "Content-Type: application/json" \
  -d '{ "payFrequency": "WEEKLY", "payPeriodStartDay": "MONDAY", "targetGoLiveDate": "2026-12-07" }'

Or set, move or clear it at any time before Everee sets the go-live date, with Set the target go-live date:

curl -X PUT https://api.everee.com/integration/v1/partner/companies/$ID/go-live/target \
  -u "$KEY:" -H "Content-Type: application/json" \
  -d '{ "targetGoLiveDate": "2026-12-07" }'

Which dates are accepted

The date must be tomorrow or later, and the first day of a pay period. Everee checks it against the company's payroll calendar configuration:

1. The payroll calendar you name with payrollCalendarId (targetGoLivePayrollCalendarId on the payroll profile).
2. Otherwise, the company's default payroll calendar, or its only active one. A company with several payroll calendars and no default must name one.
3. A company with no payroll calendar is checked against the pay frequency in its payroll profile.

A payroll calendar's date must also be on or after its effectiveDate. A date that doesn't qualify is refused with 422, and the message names the nearest valid dates either side.

When the target can change

• While the company is a draft: with the payroll profile or the target endpoint. A payroll profile change that would leave your target off the first day of a pay period is refused with 409, unless the same request sends a new targetGoLiveDate.
• After that: with the target endpoint only.
• A payroll calendar change isn't refused. If it leaves your target off a pay period start, targetGoLiveDateValid becomes false and outstanding lists TARGET_GO_LIVE_DATE until you set a new one.
• Once Everee sets the go-live date, or the company is live, the target can't change (409). Ask your Everee contact to move the go-live date.

Provide payroll history

Everee needs the payroll the company has already run this year, from its previous payroll provider. Everee's team reviews the files and imports them.

Recommended: the upload component

Embed the payroll history upload in your product, so the company's admin can hand the files to Everee directly. Create a session with Create a payroll history upload session and open its url in a webview or iframe, the same way as other embedded experiences.

curl -X POST https://api.everee.com/integration/v1/partner/companies/$ID/payroll-history/embedded-session \
  -u "$KEY:" -H "Content-Type: application/json" \
  -d '{ "eventHandlerName": "evereeHandler" }'

In the component, the admin:

• drags and drops files, or chooses them, several at a time;
• sees every payroll history file Everee has, with Everee's review of each, and a note on any that needs replacing;
• sees what Everee asked for when it needs more files;
• can remove a file they uploaded there, until Everee reviews it.

Sessions expire quickly, so create one right before you show it. The component sends these events to your page:

Or upload the files yourself

If you collect the files in your own product, send each one with Upload a payroll history file:

curl -X POST https://api.everee.com/integration/v1/partner/companies/$ID/payroll-history/files \
  -u "$KEY:" -F "[email protected]"

Files can be CSV, XLSX, XLS, PDF or ZIP, up to 25 MB each and 50 per company. Delete a payroll history file removes one you uploaded through the API, until Everee reviews it. Upload a year-to-date payroll file still works, and files the same way.

What to send

Agree the files with your Everee contact. Typically they're the company's quarterly payroll registers for this year and year-to-date totals for each worker, exported from its previous provider.

Where it stands

Read it with Get payroll history, or from payrollHistory on the onboarding status.

Each file has a reviewStatus: PENDING until Everee looks at it, then ACCEPTED or REJECTED. A rejected file has a reviewNote saying why; show it to the admin as written.

When Everee needs more, it opens a DOCUMENT_NEEDED request with documentType: PAYROLL_HISTORY and a message, and the status becomes CHANGES_REQUESTED. Answer it by uploading the files, in the component or through the API, or with Fulfill a request with a file. A payroll history request can be answered after the company is approved. The next upload resolves the request and moves the status back to RECEIVED.

An upload after IMPORTED or NOT_NEEDED moves the status back to RECEIVED too, so Everee can look at what changed.

Know when it's live

Subscribe to these company onboarding events:

Once you receive went-live, or goLive.live is true, the company can run payroll: see Running payroll.