Guide to the Reports API

The Reports API generates Everee reports on demand and gives you a link to download each one as a file. Reports can take a while to build, so the API works asynchronously: you ask for a report, Everee builds it, and you're notified when it's ready.

How it works

1. Request a report. Make a POST to /integration/v1/reports/{report-type} with the report's criteria in the request body. Each report has its own endpoint, listed below. The response is a report run, with an id and a status of SUBMITTED.
2. Wait for the webhook. When the report is finished, Everee sends a report.completed webhook event. If it fails, you receive report.errored. See Report events below.
3. Retrieve the report run. Call Retrieve a report run with the id. When status is COMPLETED, the response includes a downloadUrl for the report file.
4. Download the file. Reports are Microsoft Excel (.xlsx) files. The downloadUrl is an expiring signed link and needs no further authentication. It stops working at downloadUrlExpiresAt, so download promptly. If it expires, retrieve the report run again to get a new link.

You can also poll Retrieve a report run instead of using webhooks, but webhooks are recommended.

Report run status

Reports and scopes

Each report is gated by its own scope, so you only need (and can only be granted) access to the reports you use. Retrieving a report run needs the scope of that run's report type.

Criteria

Each endpoint documents its own criteria. Most reports take a date range (startDate and endDate, as yyyy-MM-dd), a year, or a year and quarter. Some take none, and report current data; for those, still send an empty JSON object ({}) as the request body.

A request with missing or invalid criteria returns 400, with an errorMessage naming the offending field.

Data safety

Reports are only as reliable as the data behind them. Reports built from finalized payments, such as the Payments by Pay Period report, are stable: payments don't change once finalized.

Payment data that has not been finalized is different. It can change at any moment, especially while payments are being calculated. The Payroll Review report reports on exactly that data, so it will never report on payments that are waiting for calculation or being calculated:

• If such payments exist when you make the request, you get 412 and a Retry-After header telling you how many seconds to wait. No report run is created.
• If payments start calculating after your request is accepted, the report run ends as ERRORED.

Either way, wait and request the report again. See the endpoint's page for details.

Report events

When a report run finishes, Everee sends one of these webhook events. Their data.object has this structure:

{
  "reportId": "8841",
  "reportType": "PAYMENTS_BY_PAY_PERIOD",
  "status": "COMPLETED"
}

If the report couldn't be generated, the event has type report.errored, and data.object includes the reason in errorMessage:

{
  "reportId": "8842",
  "reportType": "FUNDING",
  "status": "ERRORED",
  "errorMessage": "No funding transactions found."
}

reportId is the report run's id, which you pass to Retrieve a report run.