🧾 Guide to the Payment Data API

The Payment Data API lets you retrieve the payment-level detail of payroll runs: every payment made on a pay date, with its wages, employer taxes, additional costs, employee withholdings and deductions, and net payouts, itemized line by line.

It's built for post-payroll reconciliation and reporting. You can use it to tie payroll out to your general ledger, check individual payments against your own records, produce your own payroll reports, or feed an audit.

It sits alongside two related APIs:

The Cost Center API rolls payroll up into cost segments by cost center. Use it when you want totals to invoice or report by client, job, or project.
The Worker Payment History API returns the payments of one worker. Use it to show a worker's own history.
The Payment Data API returns every payment in a payroll run, one at a time. Use it when you need the detail behind the totals. It's equivalent to the "Payroll Register" file you'd find in legacy payroll systems.

The concepts are the same across these APIs, so a pay code, a cost center, or a tax label means the same thing in each.

How do I retrieve payment data?

You retrieve the payments for one pay date:

GET https://api.everee.com/integration/v1/payment-data?pay-date=2026-10-16

Typically, you'll retrieve the payment data once per pay date, after payroll for that date has been processed. It contains only payments that have been paid, so it's a record of what happened, not a preview of what's coming.

📘
Retrieve a pay date after it has finished processing
Payments appear in the payment data as they're paid. Retrieve a pay date after its payroll has finished processing, and page through it in one pass, so you get a complete and consistent picture. A payment that is paid while you're paging through a pay date might not be included in that pass.

How does paging work?

A pay date can include thousands of payments, so this endpoint is paginated with a cursor rather than the page and size parameters used by many other endpoints. See Pagination for how the two styles compare.

limit sets the page size. It defaults to 200 and can be up to 1000.
Each response includes hasNextPage, and, when there's more data, a nextCursor.
To get the next page, send the same request with after set to that nextCursor. Treat the cursor as an opaque value: pass it back exactly as you received it.
Keep going until hasNextPage is false. Pages are in a stable order, so you won't see a payment twice.

{
  "items": [ /* payments */ ],
  "pageSize": 200,
  "hasNextPage": true,
  "hasPreviousPage": false,
  "nextCursor": "MjgyMzAzMTE"
}

GET https://api.everee.com/integration/v1/payment-data?pay-date=2026-10-16&after=MjgyMzAzMTE

Paging only moves forward, and responses don't include a total count. If you need the number of payments, count them as you page.

What does a payment look like?

Each item in items is one payment to one worker. Here's an example:

{
  "id": "28230311",
  "workerId": "94cae9c4-a52c-4731-969f-83540f45c2e2",
  "externalWorkerId": "emp-1042",
  "payPeriodStartDate": "2026-10-05",
  "payPeriodEndDate": "2026-10-11",
  "payDate": "2026-10-16",
  "status": "PAID",
  "totalTaxableWages": { "amount": "1200.00", "currency": "USD" },
  "totalNonTaxablePay": { "amount": "0.00", "currency": "USD" },
  "totalEmployerTax": { "amount": "99.00", "currency": "USD" },
  "totalEmployerAdditionalCosts": { "amount": "25.00", "currency": "USD" },
  "totalNetPay": { "amount": "835.00", "currency": "USD" },
  "taxableWages": [
    {
      "payCode": "REGULAR_HOURLY",
      "amount": { "amount": "1050.00", "currency": "USD" },
      "costCenters": [
        { "type": "glCode", "value": "80029" },
        { "type": "clientId", "value": "290" }
      ]
    },
    {
      "payCode": "BONUS",
      "amount": { "amount": "150.00", "currency": "USD" },
      "costCenters": [{ "type": "glCode", "value": "80029" }]
    }
  ],
  "nonTaxablePay": [],
  "employerTaxes": [
    { "name": "Social Security (ER)", "amount": { "amount": "74.40", "currency": "USD" }, "subjectWages": { "amount": "1200.00", "currency": "USD" }, "state": null },
    { "name": "Medicare (ER)", "amount": { "amount": "17.40", "currency": "USD" }, "subjectWages": { "amount": "1200.00", "currency": "USD" }, "state": null },
    { "name": "FUTA (ER)", "amount": { "amount": "7.20", "currency": "USD" }, "subjectWages": { "amount": "1200.00", "currency": "USD" }, "state": null }
  ],
  "employerAdditionalCosts": [
    {
      "name": "Workers' Compensation",
      "amount": { "amount": "25.00", "currency": "USD" },
      "workersCompState": "UT",
      "workersCompClassCode": "64229",
      "workersCompEmployerRate": { "amount": "1.0294", "currency": "USD" }
    }
  ],
  "employeeTaxWithholdings": [
    { "name": "Federal Income Tax", "amountWithheld": { "amount": "132.00", "currency": "USD" }, "resident": null, "subjectWages": { "amount": "1200.00", "currency": "USD" }, "state": null },
    { "name": "Social Security", "amountWithheld": { "amount": "74.40", "currency": "USD" }, "resident": null, "subjectWages": { "amount": "1200.00", "currency": "USD" }, "state": null },
    { "name": "Medicare", "amountWithheld": { "amount": "17.40", "currency": "USD" }, "resident": null, "subjectWages": { "amount": "1200.00", "currency": "USD" }, "state": null },
    { "name": "Utah State Tax", "amountWithheld": { "amount": "54.00", "currency": "USD" }, "resident": true, "subjectWages": { "amount": "1200.00", "currency": "USD" }, "state": "UT" }
  ],
  "employeeDeductions": [
    { "name": "401(k)", "amountDeducted": { "amount": "43.60", "currency": "USD" } },
    {
      "name": "Child Support & Alimony",
      "amountDeducted": { "amount": "43.60", "currency": "USD" },
      "garnishmentOrderCaseId": "2024-DR-004512",
      "garnishmentAgencyName": "Utah Office of Recovery Services",
      "garnishmentAgencyFullAddress": "515 E 100 S, Salt Lake City, UT 84102",
      "garnishmentRemittanceId": "123"
    }
  ],
  "netPayouts": [
    {
      "id": "48213377",
      "type": "DIRECT_DEPOSIT",
      "date": "2026-10-16",
      "netAmount": { "amount": "600.00", "currency": "USD" },
      "status": "PAID",
      "directDepositInfo": { "nickname": "Checking", "routingNumber": "121140399", "accountLast4": "4431", "traceNumber": "12345" }
    },
    {
      "id": "48213378",
      "type": "DIRECT_DEPOSIT",
      "date": "2026-10-16",
      "netAmount": { "amount": "235.00", "currency": "USD" },
      "status": "PAID",
      "directDepositInfo": { "nickname": "Savings", "routingNumber": "121140399", "accountLast4": "7782", "traceNumber": "12346" }
    }
  ]
}

A few things to know about the payment itself:

id is the payment's identifier. It's also what you'd use to retrieve the payment from the Worker Payment History API.
workerId is Everee's identifier for the worker. externalWorkerId is the worker ID you set yourself, or null if you haven't.
payPeriodStartDate and payPeriodEndDate are the dates of the pay period the payment was calculated for, and payDate is when it was paid.
All monetary amounts use the money format, as a decimal string with a currency.

Totals always equal their lines. Each total… property is the sum of the list next to it: totalTaxableWages is the sum of taxableWages, totalNonTaxablePay is the sum of nonTaxablePay, totalEmployerTax is the sum of employerTaxes, totalEmployerAdditionalCosts is the sum of employerAdditionalCosts, and totalNetPay is the sum of netPayouts. You can rely on this when you tie payment data out to your own records.

How are wages broken down?

taxableWages lists the payment's gross taxable wages, and nonTaxablePay lists amounts that aren't taxable, like reimbursements. Each line is the total for one pay code: the pay code's API key if the wages are mapped to one of your custom pay codes, or the standard earning type, like REGULAR_HOURLY, if not.

Each line also lists the cost centers the wages are allocated to, in the costCenters property. These are the same cost centers you send with shifts, payable items, and other wage items, and they work the way they do in the Cost Center API: type is a cost center type's key, and value is the value you used with it. See the Guide to cost centers for how cost centers are set up.

Wages are grouped by pay code and by their full set of cost centers. If a worker earned regular wages on two different clients in the same pay period, the payment has two REGULAR_HOURLY lines, one for each client. Wages with no cost centers have an empty costCenters list. They're the same wages that appear in the unallocated cost segment of the Cost Center API.

How are taxes, additional costs, and deductions reported?

employerTaxes lists the employer payroll taxes for the payment, by tax jurisdiction. Each has the tax amount, the subjectWages it was calculated on, and the state it applies to, or null for federal taxes.
employerAdditionalCosts lists the employer's non-tax costs: benefit plan contributions, Workers' Comp insurance premiums, and similar. For Workers' Comp, you also get the workersCompState, the workersCompClassCode, and the employer's workersCompEmployerRate. The rate is in dollars per $100 of gross payroll wages, except in Washington, where it's dollars per hour worked. The calculation already accounts for this difference. Rates keep their full decimal precision, like 1.0294.
employeeTaxWithholdings lists taxes withheld from the worker's wages. Where it applies, resident tells you whether the worker was a resident of the jurisdiction on the pay date.
employeeDeductions lists everything else taken from the worker's wages, including benefit contributions and garnishments. A garnishment line includes the order's case ID, the agency's name and address, and the garnishmentRemittanceId.

Unlike the Cost Center API, which allocates employer taxes, additional costs, and similar amounts across cost centers in proportion to wages, this API reports each of these for the whole payment. Only the wage lines carry cost centers.

How do net payouts work?

netPayouts lists the payouts that carried the worker's take-home pay out of the payment. A payment can have more than one payout, for example when a worker splits their pay across two bank accounts.

Each payout has:

id, a unique identifier for the payout.
type, which is DIRECT_DEPOSIT for a deposit to a bank account. New payout types may be added over time, so your integration should handle values it doesn't recognize.
date, the date the payout is made.
netAmount, the amount of the payout.
status, which is one of PENDING (not yet completed), PAID (completed), or FAILED. New statuses may be added over time too.
directDepositInfo, for direct deposits: the account's nickname, the routingNumber, the last four digits of the account number as accountLast4, and the ACH traceNumber.

totalNetPay is the sum of the netAmount of the payment's payouts.

Which payments are included?

The Payment Data API includes payments that have been paid and that have wages. Payments that are still being calculated, approved, or funded aren't included, because it's a record of completed payroll.