# Everee Payroll Infrastructure: partner guide (Markdown)

Generated 2026-11-01 from the Everee docs (branch v1.0). HTML version: https://files.everee.com/everee-payroll-infrastructure-explainer.html. Start with the start-here prompt (https://files.everee.com/prompts/master.md), then use the per-section prompts at the end of each area. Diagrams and sample screens are in the HTML version only.

Payroll Infrastructure · Partner guide

# Payroll Infrastructure for your platform.

Everee Payroll Infrastructure lets you offer full-stack embedded payroll. It's managed: Everee handles most of the compliance and the payroll support workflows, so you don't have to become a payroll company.

**Your product, Everee's engine**

Customers onboard, pay workers and approve payroll without leaving your app.

**We're the payroll experts**

Everee handles all payroll support duties, so you can keep doing what you do best.

**Compliance & tax: handled**

Everee handles tax rule updates, tax filing and remittance, and new hire and termination reporting. You build no tax ops.

Built for coding agents

## Hand this guide to your coding agent.

This guide prompts your coding agent directly. Copy the starting prompt into your agent, or just point it at this guide. It'll know how to get started.

Overview

## What Payroll Infrastructure is

Payroll Infrastructure is Everee's payroll engine, offered as an API for platforms. Your platform creates companies, loads workers and settings, and sends payroll items each cycle. Everee calculates pay, taxes, and withholdings, pays workers, and files and pays taxes. You read the results back as structured data, a balanced payroll GL journal, and reports.

**Who it's for.** Platforms that already hold the workforce data and the customer relationship, such as workforce management, staffing, scheduling, compensation software, and business services. Your customers keep working in your product, and payroll becomes a sticky, valuable feature set. Everee runs behind your platform powering payroll and compliance.

**Managed, so you build no tax ops.** Everee handles tax compliance. As the reporting agent, it keeps up with tax rule updates, and automatically runs payroll tax filings for each company, quarterly and at year-end. You can list a worker's year-end W-2 or 1099 ([worker files](https://developer.everee.com/reference/list-files)), the [company tax files](https://developer.everee.com/reference/list-company-tax-files) Everee has published, and request the [940 and 941 detail reports](https://developer.everee.com/reference/reports-api-guide).

- Tax rule updates, tax remittance and filing
- Garnishment and retirement remittance
- New hire and termination reporting
- Payroll support workflows, with Everee Customer Success supporting your customers directly

### What it lets you offer

Payroll becomes a product family inside your platform instead of an integration your customers set up elsewhere:

- Payroll for employees and contractors, in every state your customers operate in.
- Worker profiles, onboarding, direct deposit and tax withholding.
- Benefit, retirement and other deductions, and garnishments with limits applied and remittance handled by Everee.
- Paid time off, workers' comp classes and work locations.
- Reporting and financials customers can reconcile and post to their ledger.

Six areas

## How the pieces fit

Every integration is a loop. Each area has its own APIs, and the output of one is the input to the next. Webhooks tell you when something happens along the way.

[Area 1

### Onboard a company

Create the customer, collect what Everee needs, sign in an embedded screen, submit for review.

Open sectionAvailable

][Area 2

### Set up the organization

Work locations, payroll calendars, approval groups, cost centers and pay codes.

Open sectionAvailable

][Area 3

### Add and maintain workers

Complete worker records, kept in sync with your records.

Open sectionAvailable

][Area 4

### Send worker payroll settings

Deductions, leave types and policies, balances and garnishments.

Open sectionAvailable

][Area 5

### Run payroll each cycle

Send hours and pay items today. The Run payroll API is coming early November.

Open sectionComing soon

][Area 6

### Retrieve financial data

Payment data, payroll cost, the journal with GL codes, and reports.

Open sectionAvailable

]

### Who does what

| Area | Your platform does | Everee does | You hear about it |
| --- | --- | --- | --- |
| 1 Onboard a company | Sends company details, people and documents; shows the signing screen | Verifies identities, reviews the company, countersigns | `company-onboarding.*` |
| 2 Set up | Creates locations, calendars, approval groups, cost centers, pay codes | Applies them to tax and pay calculation | — |
| 3 Workers | Creates complete worker records, keeps them current | Verifies taxpayer identifiers and applies tax settings | `worker.created` |
| 4 Settings | Syncs deductions, leave policies and enrollments | Applies them every payroll | — |
| 5 Run payroll | Sends shifts, hours and payables; approves each payroll run through the API (early November) | Calculates, funds and pays | `payment.paid` |
| 6 Reporting | Pulls payment data, the journal and reports | Publishes itemized results | `report.completed` |

Path to live

## From agreement to first filing

Ten steps from the partner agreement to the first filing, and who owns each. Durations differ in every situation, so none are given.

The order of the steps, and who owns each one. Boxes with a heavier border gate the steps after them.

1

**Sign the partner agreement**Day 0. Tell Everee who your technical contacts are.

YouEveree

2

**Claim your partner key**Your Everee contact invites a technical contact, who claims the key with a code from a call.

YouEveree

3

**Build and test in your sandbox instances**Areas 1 to 6, against your own sandbox instances with `tsk_test_…` keys.

You

4

**Everee reviews your integration**Everee verifies company onboarding, company setup, worker creation, worker profile management, payroll processing, and GL and reporting.

Everee

5

**Onboard the first live company**Create the draft, complete it, the signer signs in your product, you submit, and Everee reviews and approves.

YouCustomer's signerEveree

6

**Everee collects state tax information**A required step of company onboarding. The company can't go live without it.

Everee

7

**Set up the organization and add workers**Locations, calendars, approval groups, cost centers, pay codes, then complete worker records and their settings.

You

8

**Send pay and approve the first payroll run**Send hours and payables, then approve the run through the API by the 10:30am PT (1:30pm ET) cutoff. Coming soon

You

9

**Workers are paid; you reconcile**`payment.paid` arrives. Pull payment data, post the journal, run reports.

EvereeYou

10

**Everee files taxes and year-end documents**Quarterly and annual filings, W-2s and 1099s, with no tax operations on your side.

Everee

Area 1

## Onboard a company Available

Create a customer as a draft company, collect what Everee needs, sign inside your product, and submit for review.

The Company Onboarding API creates a client company and takes it through onboarding without sending anyone to Everee's own sign-up. You collect the information in your product, the company's signer signs in an embedded screen, Everee reviews the result, and webhooks tell you the outcome. These steps mirror Everee's own self-signup, so you can build the same experience.

### Prompt for your coding agent

Copy this into your coding agent, or point the agent at this page and it can read the prompt directly. It names the docs to read first, the operations to call, the rules that matter for this area, and the tests to write. [Open as Markdown](https://files.everee.com/prompts/onboard.md)

**Agent prompt: Area 1: Onboard a company**

```
GOAL
Build the screens and server logic that onboard a customer as an Everee company from inside my product: capture details, send documents and people, show Everee's embedded contract signing, submit for review, and track status until APPROVED.

READ FIRST (each page also has a Markdown version at the same URL with .md added; the docs index is https://developer.everee.com/llms.txt)
- https://developer.everee.com/docs/company-onboarding-overview
- https://developer.everee.com/reference/company-onboarding-api-guide
- https://developer.everee.com/docs/creating-and-completing-a-company
- https://developer.everee.com/docs/signing-the-agreements
- https://developer.everee.com/docs/company-onboarding-events
- https://developer.everee.com/docs/how-to-embed-components-guide
- https://developer.everee.com/reference/get-partner-company-status
- https://developer.everee.com/reference/create-partner-company-contract-session

BUILD
- POST https://api.everee.com/integration/v1/partner/companies with the legal name, EIN and primary contact (optional webhookUrl). Save the returned company id, apiKey and webhookSigningKey immediately: they are shown once.
- Wizard screens that fill the draft: company details and payroll profile, documents, control person, owners of 25% or more, signer, agreement consent, tax setup, and the required year-to-date payroll history file. Use GET /partner/companies/{id}/status after every change; its readiness codes say exactly what is missing.
- A signing screen: create a signing session (experience COMPANY_CONTRACT), show the returned URL in an iframe, handle the MESSAGE_PORT_REGISTERED, CONTRACT_SIGNED and DISMISS messages, and create a new session if one expires. The signer chooses the funding bank account inside that embedded screen, so never collect bank details yourself.
- Submit for review, then handle identity verification links and review requests that come back. On company-onboarding.status-changed to APPROVED, switch to using the company key.

OPERATIONS (all paths are under https://api.everee.com/integration/v1; each reference page, with .md added, lists its request and response fields)
- POST /partner/companies | operationId create-partner-company | https://developer.everee.com/reference/create-partner-company.md
- GET /partner/companies/{companyId} | operationId get-partner-company | https://developer.everee.com/reference/get-partner-company.md
- PATCH /partner/companies/{companyId} | operationId update-partner-company | https://developer.everee.com/reference/update-partner-company.md
- PATCH /partner/companies/{companyId}/payroll-profile | operationId update-partner-company-payroll-profile | https://developer.everee.com/reference/update-partner-company-payroll-profile.md
- GET /partner/companies/naics-codes | operationId list-partner-company-naics-codes | https://developer.everee.com/reference/list-partner-company-naics-codes.md
- POST /partner/companies/{companyId}/documents/{kind} | operationId upload-partner-company-document | https://developer.everee.com/reference/upload-partner-company-document.md
- GET /partner/companies/{companyId}/documents | operationId list-partner-company-documents | https://developer.everee.com/reference/list-partner-company-documents.md
- PUT /partner/companies/files/year-to-date | operationId upload-partner-company-year-to-date-file | https://developer.everee.com/reference/upload-partner-company-year-to-date-file.md
- PUT /partner/companies/{companyId}/files/certificate-of-authority | operationId upload-partner-company-certificate-of-authority | https://developer.everee.com/reference/upload-partner-company-certificate-of-authority.md
- PUT /partner/companies/{companyId}/control-person | operationId put-partner-company-control-person | https://developer.everee.com/reference/put-partner-company-control-person.md
- PUT /partner/companies/{companyId}/ownership-declaration | operationId put-partner-company-ownership-declaration | https://developer.everee.com/reference/put-partner-company-ownership-declaration.md
- POST /partner/companies/{companyId}/beneficial-owners | operationId add-partner-company-beneficial-owner | https://developer.everee.com/reference/add-partner-company-beneficial-owner.md
- PUT /partner/companies/{companyId}/signer | operationId put-partner-company-signer | https://developer.everee.com/reference/put-partner-company-signer.md
- PATCH /partner/companies/{companyId}/people/{personRef}/contact | operationId correct-partner-company-person-contact | https://developer.everee.com/reference/correct-partner-company-person-contact.md
- POST /partner/companies/{companyId}/people/{personRef}/identity-verification/resend | operationId resend-partner-company-identity-link | https://developer.everee.com/reference/resend-partner-company-identity-link.md
- PUT /partner/companies/{companyId}/agreement-consent | operationId put-partner-company-agreement-consent | https://developer.everee.com/reference/put-partner-company-agreement-consent.md
- PATCH /partner/companies/{companyId}/tax-setup | operationId update-partner-company-tax-setup | https://developer.everee.com/reference/update-partner-company-tax-setup.md
- GET /partner/companies/{companyId}/bank-account | operationId get-partner-company-bank-account | https://developer.everee.com/reference/get-partner-company-bank-account.md
- POST /partner/companies/{companyId}/contract/embedded-session | operationId create-partner-company-contract-session | https://developer.everee.com/reference/create-partner-company-contract-session.md
- GET /partner/companies/{companyId}/contract/documents/{documentType} | operationId get-partner-company-contract-document | https://developer.everee.com/reference/get-partner-company-contract-document.md
- GET /partner/companies/{companyId}/status | operationId get-partner-company-status | https://developer.everee.com/reference/get-partner-company-status.md
- POST /partner/companies/{companyId}/submit | operationId submit-partner-company | https://developer.everee.com/reference/submit-partner-company.md
- POST /partner/companies/{companyId}/withdraw | operationId withdraw-partner-company | https://developer.everee.com/reference/withdraw-partner-company.md
- GET /partner/companies/{companyId}/requests | operationId list-partner-company-requests | https://developer.everee.com/reference/list-partner-company-requests.md
- PUT /partner/companies/{companyId}/requests/{requestId}/file | operationId fulfill-partner-company-request-with-file | https://developer.everee.com/reference/fulfill-partner-company-request-with-file.md
- PUT /partner/companies/{companyId}/requests/{requestId} | operationId fulfill-partner-company-request-with-text | https://developer.everee.com/reference/fulfill-partner-company-request-with-text.md

RULES
- After signing the documents' data is locked: name, address, signer, owners, tax details and pricing return 409. Don't offer edit controls for them after signing.
- Sessions are single-use and expire in minutes. Create one when the user arrives, never earlier.
- Webhooks are nudges. Re-read /status to decide what to show.
- Base URL https://api.everee.com/integration/v1. The partner key (psk_...) is the HTTP Basic user name for the Company Onboarding API. The company key (tsk_...) is the HTTP Basic user name for everything else, plus an x-everee-tenant-id header holding the company's id.
- Keep every key on the server. Everee rejects browser requests. Read keys from a secrets store, never log them, never hard-code them.
- Rate limit: 100 operations per 5 seconds per key (see the RateLimit-Policy header). Back off on 429.
- Only payables have an idempotency key (externalId). Make other creates safe yourself: look first, keep the Everee ID next to your own record.
- Test against a sandbox instance (tsk_test_... keys) before production. Nothing in a URL selects the environment; the key does.

DONE WHEN
- A sandbox company goes from DRAFT through signing to submitted, and the UI always reflects the readiness codes from /status.
- The company key and company id are stored encrypted, and a status-changed webhook updates the UI.

TESTS TO WRITE
- Every readiness code from /status renders the right prompt or screen.
- An expired signing session is replaced by a new one, and no session is created before the user arrives.
- After signing, the locked fields are read-only in the UI, and a 409 from the API is shown as an explanation.
- A company-onboarding.status-changed event for APPROVED switches the company to its company key, and a replayed event changes nothing.
- The company key and webhook signing key are stored encrypted and are not logged.

If a fact you need isn't in the docs, ask me. Don't guess endpoint paths, field names or business rules.
```

### Before you start: your partner API key

Everee never sees or sends your partner key. A technical contact at your company **claims** it, and Everee creates it at that moment and shows it once. It looks like `psk_prod_…` and is sent as an HTTP Basic credential with the key as the user name:

**Authorization**

```
Authorization: Basic base64(psk_prod_…:)

# curl does the encoding for you
curl -u "$PARTNER_KEY:" ...
```

You can only see and change the companies you created. [Getting your partner API key](https://developer.everee.com/docs/getting-your-partner-api-key)

**Your Everee contact invites a technical contact**They pick a label for the key (for example "Production") and who should claim it. Tell Everee your technical contacts first: a key can only be offered to someone on that list.

**You get an email with a link**It works for 7 days. Opening it doesn't use anything up.

**Your Everee contact gives you a 6-digit code on a call**The code never goes by email, so someone with only the email can't claim the key. Five wrong codes lock the link.

**Enter the code and select Generate my key**The key appears once. It looks like `psk_prod_…`. Copy it to your secrets manager right away.

**Rotate or retire when needed**Ask your Everee contact. A replacement is claimed the same way, and the old key keeps working for a period you agree, from none up to one week.

### The whole flow

Five stages from create to approved. Webhooks (arrows pointing back to you) tell you when to move on.

[Company Onboarding Overview](https://developer.everee.com/docs/company-onboarding-overview) · [Collecting company information](https://developer.everee.com/docs/creating-and-completing-a-company) · [Submitting for review](https://developer.everee.com/docs/submitting-for-review)

### Statuses

#### DRAFT

Create and change everything, submit when ready, withdraw any time.

#### UNDER_REVIEW

Everee verifies identities and reviews. The data is locked. You answer requests.

#### APPROVED

Everee countersigned. Use the company API key for the rest of the API.

#### DECLINED

A generic `reasonCode` is returned. Everee doesn't share review details through the API.

#### WITHDRAWN

Final. A withdrawn company can't be reopened. Create a new one.

### The call you keep making: status

Everything is driven by one read, called after every change, when the user returns, and when a webhook arrives. It never changes anything.

| Field | What to do with it |
| --- | --- |
| `status` | Where the onboarding is: `DRAFT`, `UNDER_REVIEW`, `APPROVED`, `DECLINED` or `WITHDRAWN`. |
| `readiness.missing` | The codes still unmet. Your screens are driven by this list. |
| `readiness.complete` | `true` when nothing is missing. This is when you can submit. |
| `contract` | Absent until Everee requests a signature. Then `AWAITING_SIGNATURE`, `SIGNED`, `EXECUTED`. |
| `agreement` | How customers agree to pricing and service terms: `DIRECT` or `UMBRELLA`. See [Agreeing to terms](https://developer.everee.com/docs/agreeing-to-terms). |
| `identityVerification` | After submission, one entry per person being verified, with a coarse status. |
| `requests` | What Everee has asked you for during review. |

**Drive your screens from `readiness.missing`, not from a fixed sequence.** Everee can change what it requires, and codes appear and disappear as the company's answers change.

### The ten screens

The recommended order is the one Everee's own self-signup uses. The signature is requested once screens 2 to 7 are in and Everee has loaded the contract terms, so codes for steps 8 and 9 are expected to still be missing while the user is on earlier screens. [The readiness check](https://developer.everee.com/docs/company-onboarding-overview#the-readiness-check)

| # | Screen | Codes it satisfies | Call |
| --- | --- | --- | --- |
| 1 | Create the company | none | [Create company](https://developer.everee.com/reference/create-partner-company) |
| 2 | Business details | `LEGAL_ENTITY_TYPE` `FORMATION_STATE` `BUSINESS_ADDRESS` | [Update company](https://developer.everee.com/reference/update-partner-company) |
| 3 | Supporting documents | `IRS_EIN_LETTER` `BUSINESS_FORMATION` | [Upload a document](https://developer.everee.com/reference/upload-partner-company-document) |
| 4 | Payroll profile | `WORKER_TYPES` `EMPLOYEE_COUNT` `CONTRACTOR_COUNT` `PAY_FREQUENCY` `PAY_PERIOD_START_DAY` `ANNUAL_REVENUE` `NATURE_OF_BUSINESS` `NAICS_CODE` | [Update payroll profile](https://developer.everee.com/reference/update-partner-company-payroll-profile) |
| 5 | People: control person, owners, signer | `CONTROL_PERSON` `OWNERSHIP_DECLARATION` `OWNERSHIP_TOTAL` `SIGNER` `SIGNER_IDENTITY` `SIGNER_RELATIONSHIP` | [People and ownership](https://developer.everee.com/reference/people-and-ownership-guide) |
| 6 | Customer's agreement (some partners) | `AGREEMENT_CONSENT` | [Report consent](https://developer.everee.com/reference/put-partner-company-agreement-consent) |
| 7 | Taxes | `TAX_STATES` | [Update tax setup](https://developer.everee.com/reference/update-partner-company-tax-setup) |
| 8 | Sign and choose the bank account | `SIGNED_CONTRACT` `BANK_ACCOUNT` | [Signing session](https://developer.everee.com/reference/create-partner-company-contract-session) |
| 9 | After signing: authority and IDs | `CERTIFICATE_OF_AUTHORITY` `PICTURE_ID` | [Certificate of authority](https://developer.everee.com/reference/upload-partner-company-certificate-of-authority) |
| 10 | Review and submit | completes the check | [Submit](https://developer.everee.com/reference/submit-partner-company) |

### Build each screen

1

### Create the company

Only the legal business name, the EIN and a primary contact are needed. The primary contact is the person Everee creates the company's first user from. Optional: `taxContact`, `webhookUrl`, `documentCapture` and `agreementConsent`.

Keep the returned **company API key** and **webhook signing key**. Both are shown once.

[Create company](https://developer.everee.com/reference/create-partner-company)

**POST /integration/v1/partner/companies**

```
curl -X POST "https://api.everee.com/integration/v1/partner/companies" \
  -u "$PARTNER_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "legalBusinessName": "Summit Ridge Plumbing LLC",
  "ein": "87-1234567",
  "primaryContact": { "firstName": "Dana", "lastName": "Whitfield",
    "email": "dana@summitridge.example", "phone": "8015550142" },
  "webhookUrl": "https://hooks.yourplatform.example/everee"
}'
```

**Response (key fields)**

```
{ "id": 48213, "onboardingStatus": "DRAFT",
  "apiKey": "tsk_prod_…", "webhookSigningKey": "<shown once>" }
```

2

### Collect business details

Ask for the legal entity type, the formation state and the business address. Trade name, phone and website are optional. It is a partial update, so send only what changed.

`legalEntityType` is one of `C_CORPORATION`, `S_CORPORATION`, `LLC_MULTI_MEMBER`, `LLC_SINGLE_MEMBER`, `PARTNERSHIP`, `SOLE_PROPRIETORSHIP`, `NONPROFIT` or `OTHER`.

[Update company](https://developer.everee.com/reference/update-partner-company)

**PATCH /integration/v1/partner/companies/$ID**

```
curl -X PATCH "https://api.everee.com/integration/v1/partner/companies/$ID" \
  -u "$PARTNER_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "legalEntityType": "LLC_SINGLE_MEMBER", "formationState": "UT",
  "address": { "line1": "4420 S 900 E", "city": "Salt Lake City",
    "state": "UT", "postalCode": "84124" }
}'
```

3

### Upload supporting documents

Ask for the company's **IRS EIN letter** and its **business formation documents**, such as the articles of organization. Files are PDF, PNG or JPEG, up to 25 MB. A new EIN letter replaces the last one, and you can add several formation documents.

**Whether each is required is decided by Everee and can change.** List documents returns a `required` and `provided` flag per kind, so show a step only when it is required. If Everee rejects a document, it opens a request for a replacement.

**Year-to-date payroll.** Everee requires the company's year-to-date payroll history. Upload it as a file with the year-to-date endpoint. The file format is set for each partner, and it is typically a zip of payroll data from the company's current payroll provider. It is stored for Everee to use, isn't parsed or validated on upload, and isn't checked when you submit, so send it before you submit.

[Upload a document](https://developer.everee.com/reference/upload-partner-company-document)[List documents](https://developer.everee.com/reference/list-partner-company-documents)[Upload year-to-date file](https://developer.everee.com/reference/upload-partner-company-year-to-date-file)

**Upload the EIN letter and formation documents**

```
curl -X POST https://api.everee.com/integration/v1/partner/companies/$ID/documents/IRS_EIN_LETTER \
  -u "$PARTNER_KEY:" -F "file=@ein-letter.pdf;type=application/pdf"

curl -X POST https://api.everee.com/integration/v1/partner/companies/$ID/documents/BUSINESS_FORMATION \
  -u "$PARTNER_KEY:" -F "file=@articles-of-organization.pdf;type=application/pdf"
```

**Upload year-to-date payroll**

```
curl -X PUT "https://api.everee.com/integration/v1/partner/companies/files/year-to-date?companyId=$ID" \
  -u "$PARTNER_KEY:" -F "file=@year-to-date-payroll.zip"
```

4

### Describe the payroll

Ask what kind of payroll the company runs. Some codes appear only when they apply: `CONTRACTOR_COUNT` only after you say the company pays contractors, and `PAY_PERIOD_START_DAY` only for weekly and bi-weekly pay.

`WORKER_TYPES` also stays missing if the company's plan doesn't price the worker type you chose. Everee sets the plan, so ask your Everee representative. Let the user search NAICS codes instead of typing one.

[Update payroll profile](https://developer.everee.com/reference/update-partner-company-payroll-profile)[List NAICS codes](https://developer.everee.com/reference/list-partner-company-naics-codes)

**PATCH /integration/v1/partner/companies/$ID/payroll-profile**

```
curl -X PATCH "https://api.everee.com/integration/v1/partner/companies/$ID/payroll-profile" \
  -u "$PARTNER_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "paysW2Employees": true, "employeeCount": 5,
  "paysContractors": true, "contractorCount": 2,
  "payFrequency": "BI_WEEKLY", "payPeriodStartDay": "MONDAY",
  "annualRevenue": { "amount": 750000.00, "currency": "USD" },
  "natureOfBusiness": "Plumbing installation and repair",
  "naicsCode": "238220"
}'
```

5

### Collect the people

Everee must know who controls the company, who owns 25% or more, and who signs. One person can hold several roles. Collect them in this order, because the signer is matched against the other two.

1. **Control person.** Exactly one, with ownership percentage and identity details (date of birth, address, and an SSN or a passport number and country).
2. **Other owners of 25% or more.** If the control person owns more than 75%, nobody else can qualify and these codes aren't asked. Otherwise add each owner, or declare that nobody else qualifies.
3. **Signer.** The person who signs in step 8. Their relationship decides what else is needed (below).

| Signer relationship | Rule |
| --- | --- |
| `CONTROL_PERSON` | Name must match the control person's. No identity details needed. |
| `BENEFICIAL_OWNER` | Name must match an owner on file. No identity details needed. |
| `NEITHER` | Send identity details too. A certificate of authority is needed (step 9). |

[People and ownership](https://developer.everee.com/reference/people-and-ownership-guide)[Control person](https://developer.everee.com/reference/put-partner-company-control-person)[Add owner](https://developer.everee.com/reference/add-partner-company-beneficial-owner)[Ownership declaration](https://developer.everee.com/reference/put-partner-company-ownership-declaration)[Signer](https://developer.everee.com/reference/put-partner-company-signer)

**Control person**

```
curl -X PUT "https://api.everee.com/integration/v1/partner/companies/$ID/control-person" \
  -u "$PARTNER_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "firstName": "Dana", "lastName": "Whitfield", "title": "Managing Member",
  "email": "dana@summitridge.example", "phone": "8015550142",
  "ownershipPercentage": 60,
  "identity": { "dateOfBirth": "1981-04-17", "ssn": "123-45-6789",
    "address": { "line1": "2875 E Oakview Cir", "city": "Holladay",
      "state": "UT", "postalCode": "84121" } }
}'
```

**An owner of 25% or more**

```
curl -X POST "https://api.everee.com/integration/v1/partner/companies/$ID/beneficial-owners" \
  -u "$PARTNER_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "firstName": "Pat", "lastName": "Lee", "email": "pat@summitridge.example",
  "phone": "8015550143", "ownershipPercentage": 40,
  "identity": { "dateOfBirth": "1979-02-03", "ssn": "987-65-4321",
    "address": { "line1": "12 Elm St", "city": "Provo", "state": "UT", "postalCode": "84601" } }
}'
```

**Signer**

```
curl -X PUT "https://api.everee.com/integration/v1/partner/companies/$ID/signer" \
  -u "$PARTNER_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "firstName": "Dana", "lastName": "Whitfield", "title": "Managing Member",
  "email": "dana@summitridge.example", "phone": "8015550142",
  "relationship": "CONTROL_PERSON"
}'
```

6

### Record the customer's agreement (only some partners)

Every company agrees to pricing and service terms one of two ways, set for your partner account. With `DIRECT` the customer signs Everee's Subscription Agreement in the signing experience. With `UMBRELLA` the customer agrees under **your** subscription agreement and you report each consent. Until you do, `AGREEMENT_CONSENT` stays missing and Everee won't request the signature.

The consent is recorded for the signer, so a different signer needs a fresh one. You must be able to produce the proof, because Everee reviews a sample of consents. [Agreeing to terms](https://developer.everee.com/docs/agreeing-to-terms)

[Report agreement consent](https://developer.everee.com/reference/put-partner-company-agreement-consent)[Upload evidence](https://developer.everee.com/reference/upload-partner-company-agreement-evidence)

**PUT /integration/v1/partner/companies/$ID/agreement-consent**

```
curl -X PUT "https://api.everee.com/integration/v1/partner/companies/$ID/agreement-consent" \
  -u "$PARTNER_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "consentedAt": "2026-10-01T15:30:00Z", "method": "CLICKWRAP",
  "evidenceReference": "order-8841", "attestation": true
}'
```

7

### Choose the tax setup

Only asked when the company pays W-2 employees. Ask which states it withholds taxes in, and optionally its federal return type, `FORM_941` or `FORM_944`.

[Update tax setup](https://developer.everee.com/reference/update-partner-company-tax-setup)

**PATCH /integration/v1/partner/companies/$ID/tax-setup**

```
curl -X PATCH "https://api.everee.com/integration/v1/partner/companies/$ID/tax-setup" \
  -u "$PARTNER_KEY:" \
  -H "Content-Type: application/json" \
  -d '{ "returnType": "FORM_941", "states": ["UT", "ID"] }'
```

8

### Sign and choose the bank account

You make no data call for `SIGNED_CONTRACT` and `BANK_ACCOUNT`. The signer completes both inside Everee's embedded signing experience.

1. Wait for `company-onboarding.signature-requested`. Until then, creating a session returns `409`.
2. Create a session and show its URL in an iframe. Sessions are single-use and expire in minutes, so create one when the user arrives.
3. The signer connects the company's **business** funding bank account through their bank, reviews the agreements and signs once.
4. You receive `company-onboarding.contract-signed`.

The signer signs three documents with one signature: the **Subscription Agreement** (not part of the signature under an umbrella agreement), the **ACH Debit Authorization** and **IRS Form 8655**. In a sandbox instance the bank step uses Plaid's sandbox: choose the test institution and sign in with `user_good` and `pass_good`.

[Signing the agreements](https://developer.everee.com/docs/signing-the-agreements)[Create a signing session](https://developer.everee.com/reference/create-partner-company-contract-session)

**POST /integration/v1/partner/companies/$ID/contract/embedded-session**

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

**Events your page receives**

```
MESSAGE_PORT_REGISTERED  component is ready
CONTRACT_SIGNED          the signer signed (webhook is the source of truth)
DISMISS                  close the view. error + EMB-301 means create a new session
```

9

### Finish what follows signing

Two items are still collected after signing, while the company is a draft.

- **`CERTIFICATE_OF_AUTHORITY`** appears only when the signer is neither the control person nor an owner. Upload a PDF showing the signer may sign for the company.
- **`PICTURE_ID`** appears only when **you** capture pictures of IDs (you created the company with `documentCapture` of `PARTNER`). Upload the front, and the back if the ID has one, for the control person, every owner of 25% or more, and a signer who is neither. With the default `ALLOY`, Everee's identity provider captures each ID when the person verifies, and an upload returns `409`.

[Certificate of authority](https://developer.everee.com/reference/upload-partner-company-certificate-of-authority)[Supporting documents](https://developer.everee.com/reference/supporting-documents-guide)

**Upload a picture ID**

```
curl -X POST "https://api.everee.com/integration/v1/partner/companies/$ID/documents/PICTURE_ID?personRef=control-person&side=FRONT" \
  -u "$PARTNER_KEY:" -F "file=@id-front.jpg;type=image/jpeg"
```

10

### Review and submit

When `readiness.complete` is `true`, show a review screen and submit. The status becomes `UNDER_REVIEW` and the data is locked. Submitting early returns `422` with the missing codes and changes nothing. Submitting twice is harmless.

[Submit for review](https://developer.everee.com/reference/submit-partner-company)[Withdraw](https://developer.everee.com/reference/withdraw-partner-company)

**POST /integration/v1/partner/companies/$ID/submit**

```
curl -X POST "https://api.everee.com/integration/v1/partner/companies/$ID/submit" \
  -u "$PARTNER_KEY:"
```

**Signing locks the documents' data.** Name, address, signer, owners, tax details and pricing can't change after signing, and such calls return `409`. If something must change, Everee voids the signature (`contract-voided`) and requests a new one. Correcting a person's phone or email does the same. Only Everee can replace the signer after signing.

### After you submit

#### Identity verification

Everee sends the control person, each owner of 25% or more and a signer who is neither a secure link. Progress is in `identityVerification`.

| Identity status | Meaning |
| --- | --- |
| `GETTING_READY` | Everee is preparing the check. |
| `LINK_SENT` | The person has the link and hasn't finished. |
| `IN_REVIEW` | The person finished. Everee is reviewing the result. |
| `EXPIRED_CONTACT_US` | The link expired. Contact your Everee representative. |
| `VERIFIED` | The person is verified. |

#### Requests from Everee

Each need is a request in the status response and as a webhook. Documents are PDF, PNG or JPEG up to 25 MB.

| Request type | What Everee needs | How to answer |
| --- | --- | --- |
| `DOCUMENT_NEEDED` | A document, named by `documentType`. This includes a replacement for one Everee rejected. | Fulfill with a file. |
| `INFORMATION_NEEDED` | An answer to a question in `message`. | Fulfill with text, or a file. |
| `ADDITIONAL_PERSON_DETAILS` | Another person must be listed, such as an owner. | Add the person and pass the request's `requestId`. |
| `IDENTITY_VERIFICATION_NEEDED` | A person's link expired. | Resend the link. |
| `CONTRACT_CORRECTION` | A new signature on updated documents. | Show the signing experience again. |

### Onboarding webhooks

Sent to the company's webhook endpoints. Set the first with `webhookUrl` at creation, and add more with the [Webhook Endpoints API](https://developer.everee.com/reference/webhook-endpoints-api-guide). Verify each one, make handlers idempotent, and read the status for the truth. [Company onboarding events](https://developer.everee.com/docs/company-onboarding-events)

| Event | What to do |
| --- | --- |
| `company-onboarding.signature-requested` | Create a signing session. `signatureReason` is `FIRST_REQUEST`, or `RE_SIGN_REQUIRED` after a void. |
| `company-onboarding.contract-signed` | Update your screens, then submit when the readiness check is complete. |
| `company-onboarding.contract-voided` | A signature was voided because documented data changed. A new signature request follows. |
| `company-onboarding.identity-verification-changed` | Show the person's status. Resend a link if it was lost. |
| `company-onboarding.request-created` and `request-resolved` | Show or clear the request. |
| `company-onboarding.contract-executed` | Everee countersigned. Download the executed documents. |
| `company-onboarding.status-changed` | Submitted, approved, declined or withdrawn. On `APPROVED`, use the company API key. |

### State tax information

### Everee collects it

Everee obtains state tax information and rates from the customer directly, through its own systems and partners that work with the company's administrators. You don't collect state tax account numbers.

### It gates going live

Collecting state tax information is a required step of company onboarding, and the company can't go live without it. More details are coming. Everee processes new-hire reporting once payroll service begins.

### After approval: your checklist

**Confirm `company-onboarding.status-changed` is `APPROVED`**Read the onboarding status if you want to double-check. `contract-executed` means Everee countersigned.

**Store the company key and the company ID**The key (`tsk_prod_…`) was returned once at creation. The company's `id` is the value you send as `x-everee-tenant-id` with every company-key request.

**Add your webhook endpoints**Each company can have up to three, managed with the company key through the Webhook Endpoints API. The company key works as soon as the company is created, so you can set up an endpoint before onboarding finishes. Verify the signature on every delivery.

**Set up the organization**Locations, payroll calendars, approval groups, cost centers and pay codes. See area 2.

**Add workers and send their settings**Areas 3 and 4. Look up hiring status before every create.

**Send pay, then approve the payroll run**Area 5. The company can't go live until Everee has collected its state tax information, and runs are approved through the Run payroll API (early November).

**Before you go live, Everee reviews your integration.** Build and test in your sandbox instances first. Everee verifies the complete workflow: company onboarding, company setup, worker creation, worker profile management, payroll processing, and GL and reporting.

Endpoint map: Company Onboarding API

| Method | Endpoint | What it does | Docs |
| --- | --- | --- | --- |
| POST | `/integration/v1/partner/companies` | Create a draft company | [Reference](https://developer.everee.com/reference/create-partner-company) |
| GET | `/integration/v1/partner/companies/{companyId}` | Retrieve the company | [Reference](https://developer.everee.com/reference/get-partner-company) |
| PATCH | `/integration/v1/partner/companies/{companyId}` | Update company details | [Reference](https://developer.everee.com/reference/update-partner-company) |
| PATCH | `/integration/v1/partner/companies/{companyId}/payroll-profile` | Update the payroll profile | [Reference](https://developer.everee.com/reference/update-partner-company-payroll-profile) |
| GET | `/integration/v1/partner/companies/naics-codes` | Search NAICS codes | [Reference](https://developer.everee.com/reference/list-partner-company-naics-codes) |
| POST | `/integration/v1/partner/companies/{companyId}/documents/{kind}` | Upload a document | [Reference](https://developer.everee.com/reference/upload-partner-company-document) |
| GET | `/integration/v1/partner/companies/{companyId}/documents` | List documents and requirements | [Reference](https://developer.everee.com/reference/list-partner-company-documents) |
| PUT | `/integration/v1/partner/companies/files/year-to-date` | Upload year-to-date payroll | [Reference](https://developer.everee.com/reference/upload-partner-company-year-to-date-file) |
| PUT | `/integration/v1/partner/companies/{companyId}/files/certificate-of-authority` | Upload the certificate of authority | [Reference](https://developer.everee.com/reference/upload-partner-company-certificate-of-authority) |
| PUT | `/integration/v1/partner/companies/{companyId}/control-person` | Set the control person | [Reference](https://developer.everee.com/reference/put-partner-company-control-person) |
| PUT | `/integration/v1/partner/companies/{companyId}/ownership-declaration` | Declare additional owners | [Reference](https://developer.everee.com/reference/put-partner-company-ownership-declaration) |
| POST | `/integration/v1/partner/companies/{companyId}/beneficial-owners` | Add an owner (also list, update, delete) | [Reference](https://developer.everee.com/reference/add-partner-company-beneficial-owner) |
| PUT | `/integration/v1/partner/companies/{companyId}/signer` | Set the signer | [Reference](https://developer.everee.com/reference/put-partner-company-signer) |
| PATCH | `/integration/v1/partner/companies/{companyId}/people/{personRef}/contact` | Correct a person's phone or email | [Reference](https://developer.everee.com/reference/correct-partner-company-person-contact) |
| POST | `/integration/v1/partner/companies/{companyId}/people/{personRef}/identity-verification/resend` | Resend an identity link | [Reference](https://developer.everee.com/reference/resend-partner-company-identity-link) |
| PUT | `/integration/v1/partner/companies/{companyId}/agreement-consent` | Report agreement consent | [Reference](https://developer.everee.com/reference/put-partner-company-agreement-consent) |
| PATCH | `/integration/v1/partner/companies/{companyId}/tax-setup` | Set tax setup | [Reference](https://developer.everee.com/reference/update-partner-company-tax-setup) |
| GET | `/integration/v1/partner/companies/{companyId}/bank-account` | Read the funding bank account | [Reference](https://developer.everee.com/reference/get-partner-company-bank-account) |
| POST | `/integration/v1/partner/companies/{companyId}/contract/embedded-session` | Create the signing session | [Reference](https://developer.everee.com/reference/create-partner-company-contract-session) |
| GET | `/integration/v1/partner/companies/{companyId}/contract/documents/{documentType}` | Download a signed document | [Reference](https://developer.everee.com/reference/get-partner-company-contract-document) |
| GET | `/integration/v1/partner/companies/{companyId}/status` | Status, readiness, contract, requests | [Reference](https://developer.everee.com/reference/get-partner-company-status) |
| POST | `/integration/v1/partner/companies/{companyId}/submit` | Submit for review | [Reference](https://developer.everee.com/reference/submit-partner-company) |
| POST | `/integration/v1/partner/companies/{companyId}/withdraw` | Withdraw | [Reference](https://developer.everee.com/reference/withdraw-partner-company) |
| GET | `/integration/v1/partner/companies/{companyId}/requests` | List review requests | [Reference](https://developer.everee.com/reference/list-partner-company-requests) |
| PUT | `/integration/v1/partner/companies/{companyId}/requests/{requestId}/file` | Answer a request with a file | [Reference](https://developer.everee.com/reference/fulfill-partner-company-request-with-file) |
| PUT | `/integration/v1/partner/companies/{companyId}/requests/{requestId}` | Answer a request with text | [Reference](https://developer.everee.com/reference/fulfill-partner-company-request-with-text) |

Area 2

## Set up the organization Available

Work locations, payroll calendars, approval groups, cost centers and pay codes that workers and wages refer to.

Before you create your first worker or send your first hour, Everee needs the shape of the organization. Workers and wages refer to these records by ID or key, so they have to exist first. Create them with the API, using the company's own API key.

### Prompt for your coding agent

Copy this into your coding agent, or point the agent at this page and it can read the prompt directly. It names the docs to read first, the operations to call, the rules that matter for this area, and the tests to write. [Open as Markdown](https://files.everee.com/prompts/setup.md)

**Agent prompt: Area 2: Set up the organization**

```
GOAL
Build the setup screens and sync that create a company's work locations, payroll calendar, approval groups, cost centers and pay codes, and keep the Everee IDs next to my own records.

READ FIRST (each page also has a Markdown version at the same URL with .md added; the docs index is https://developer.everee.com/llms.txt)
- https://developer.everee.com/docs/setting-up-your-organization
- https://developer.everee.com/reference/add-work-location
- https://developer.everee.com/reference/create-payroll-calendar
- https://developer.everee.com/reference/add-approval-group
- https://developer.everee.com/reference/add-cost-center
- https://developer.everee.com/reference/pay-codes-api-guide
- https://developer.everee.com/reference/create-a-pay-code
- https://developer.everee.com/reference/list-workers-comp-classes

BUILD
- Screens to create and archive work locations (POST/GET/DELETE /work-locations), create payroll calendars (POST/GET /payroll-calendar), approval groups, cost centers, and custom pay codes (POST/GET /pay-codes).
- Create these in dependency order before the first worker or hour: work locations and payroll calendar, then approval groups and cost centers, then pay codes. Store each returned Everee ID or key.
- List workers' comp classes (read only) so the user can attach the right class code to hours. Everee enters them during onboarding.

OPERATIONS (all paths are under https://api.everee.com/integration/v1; each reference page, with .md added, lists its request and response fields)
- POST /work-locations | operationId add-work-location | https://developer.everee.com/reference/add-work-location.md
- GET /work-locations | operationId list-work-locations | https://developer.everee.com/reference/list-work-locations.md
- DELETE /work-locations/{workLocationId} | operationId archive-work-location | https://developer.everee.com/reference/archive-work-location.md
- POST /payroll-calendar | operationId create-payroll-calendar | https://developer.everee.com/reference/create-payroll-calendar.md
- GET /payroll-calendar | operationId list-payroll-calendars | https://developer.everee.com/reference/list-payroll-calendars.md
- POST /approval-groups | operationId add-approval-group | https://developer.everee.com/reference/add-approval-group.md
- GET /approval-groups | operationId list-approval-groups | https://developer.everee.com/reference/list-approval-groups.md
- POST /cost-centers | operationId add-cost-center | https://developer.everee.com/reference/add-cost-center.md
- POST /pay-codes | operationId list-pay-codes-1 | https://developer.everee.com/reference/create-a-pay-code.md
- GET /pay-codes | operationId list-pay-codes | https://developer.everee.com/reference/list-pay-codes.md
- GET /workers-comp | operationId list-workers-comp-class-codes | https://developer.everee.com/reference/list-workers-comp-classes.md

RULES
- Pay code keys use only uppercase letters, numbers and underscores. The type decides tax treatment, so make the user pick deliberately, and don't change a type once it is used.
- Archive rather than delete a work location that has history.
- Base URL https://api.everee.com/integration/v1. The partner key (psk_...) is the HTTP Basic user name for the Company Onboarding API. The company key (tsk_...) is the HTTP Basic user name for everything else, plus an x-everee-tenant-id header holding the company's id.
- Keep every key on the server. Everee rejects browser requests. Read keys from a secrets store, never log them, never hard-code them.
- Rate limit: 100 operations per 5 seconds per key (see the RateLimit-Policy header). Back off on 429.
- Only payables have an idempotency key (externalId). Make other creates safe yourself: look first, keep the Everee ID next to your own record.
- Test against a sandbox instance (tsk_test_... keys) before production. Nothing in a URL selects the environment; the key does.

DONE WHEN
- Every record I create appears in the matching list call, and my database holds the Everee ID for each.
- Creating a worker or an hour that refers to a missing record is blocked in my UI before it reaches the API.

TESTS TO WRITE
- Records are created in dependency order, and running the setup twice creates no duplicates.
- A pay code key with a lowercase letter or space is rejected by your form before the API call.
- Archiving a work location with history uses the archive call, not a delete.
- Every Everee ID is persisted next to the matching record of yours.

If a fact you need isn't in the docs, ask me. Don't guess endpoint paths, field names or business rules.
```

### What to set up, in order

| Order | Record | Why it matters | API |
| --- | --- | --- | --- |
| 1 | **Work locations** | A wage is taxed where it was earned. The address decides the tax jurisdictions and which leave rules apply. | [Create a work location](https://developer.everee.com/reference/add-work-location) |
| 2 | **Payroll calendars** | Sets how often workers are paid and when pay periods start. | [Create a payroll calendar](https://developer.everee.com/reference/create-payroll-calendar) |
| 3 | **Approval groups** | A set of workers managed together: who can see and approve them, and how their pay is coded in your books. | [Create an approval group](https://developer.everee.com/reference/add-approval-group) |
| 4 | **Cost centers** | Up to three categories, like client, job or department, to tag wages for cost allocation. | [Create a cost center](https://developer.everee.com/reference/add-cost-center) |
| 5 | **Pay codes** | The categories wages, reimbursements and one-time deductions go into. Everee provides defaults such as `REGULAR_HOURLY` and `BONUS`. | [Create a pay code](https://developer.everee.com/reference/create-a-pay-code) |
| 6 | **Leave types and policies** | Only if you administer paid time off. See area 4. | [Leave Accrual API](https://developer.everee.com/reference/leave-accrual-api-guide) |

### A work location

**POST /integration/v1/work-locations**

```
curl -X POST "https://api.everee.com/integration/v1/work-locations" \
  -u "$COMPANY_KEY:" -H "x-everee-tenant-id: $COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Salt Lake Office", "line1": "100 S Main St",
  "city": "Salt Lake City", "state": "UT", "postalCode": "84101",
  "effectiveDate": "2026-01-01", "externalId": "site-0042"
}'
```

### A payroll calendar

**POST /integration/v1/payroll-calendar**

```
curl -X POST "https://api.everee.com/integration/v1/payroll-calendar" \
  -u "$COMPANY_KEY:" -H "x-everee-tenant-id: $COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "displayName": "Clinic staff", "payPeriodType": "BI_WEEKLY",
  "weeklyStartDay": "MONDAY", "effectiveDate": "2026-11-02"
}'
```

### Work locations

Every wage is assigned to a location, explicitly on the shift or payable or by default from the worker's profile. Staffing and multi-site employers should assign one every time: a wage at the wrong location is taxed in the wrong jurisdiction.

- Send an `externalId` to match your own sites.
- Everee works out coordinates from the address.
- An address change applies only to upcoming payroll.

[Guide: setting up your organization](https://developer.everee.com/docs/setting-up-your-organization)

### Payroll calendars

A calendar's `effectiveDate` must be tomorrow or later. Workers you don't assign go on the company's default calendar. Contractors aren't paid on a calendar. Renaming is the only change you can make, and deleting archives a calendar that workers use.

[Guide to the Payroll Calendar API](https://developer.everee.com/reference/payroll-calendar-api-guide)

### Cost centers

Up to three active types, one per slot. A type has a case-sensitive `key`, like `clientId`, that can't change. Values are created the first time you use them. Create the types before you send wages that use them, because an unknown or archived key rejects the whole request.

[Working with cost centers](https://developer.everee.com/reference/cost-centers-guide)

#### Calendar start-day rules

| payPeriodType | Send | Not allowed |
| --- | --- | --- |
| `WEEKLY`, `BI_WEEKLY` | `weeklyStartDay` (`MONDAY` to `SUNDAY`) | `monthlyStartDay` |
| `SEMI_MONTHLY` | `monthlyStartDay`, 1 to 13 | `weeklyStartDay` |
| `MONTHLY` | `monthlyStartDay`, 1 to 28 | `weeklyStartDay` |

#### Pay code types

| payCodeType | Use it for |
| --- | --- |
| `TAXABLE_PAY` | Wages and contractor pay |
| `NON_TAXABLE_PAY` | Reimbursements and other non-wage amounts |
| `DEDUCTION` | One-time post-tax deductions. It doesn't create a recurring deduction. |

Pick carefully: the type decides tax treatment. Keys use only uppercase letters, numbers and underscores. [Guide to the Pay Codes API](https://developer.everee.com/reference/pay-codes-api-guide)

### Approval groups: why they matter

Every worker belongs to at most one group. Groups are quick to set up but decide a lot downstream, so assign the right one when you create the worker.

### 1. Organize the workforce

Group workers by branch, client site or department, and filter payments and reports by group.

### 2. Drive GL coding

Wages are coded to the group of the worker's earnings. If you scope GL mappings by approval group, each group posts to its own codes, and reports can be filtered by group. Employer taxes and benefit costs follow the wages into the same group.

- The API creates and lists groups. It doesn't rename or delete them.
- List existing groups and match on name before you create one.
- Store the group's `id`, not its name.
- Send `approvalGroupId` when you create a worker, or later with Update approval group (send `null` to remove it).

[Guide: approval groups](https://developer.everee.com/docs/approval-groups)

### Keep your IDs

Store the Everee ID of every record next to your own, so later requests need no lookup.

| Everee record | Where you'll use its ID |
| --- | --- |
| Work location | `workLocationId` on workers, shifts, classified hours and payables |
| Payroll calendar | `payrollCalendarId` when creating or updating a worker |
| Approval group | `approvalGroupId` when creating or updating a worker |
| Cost center | the `type` key in `costCenters` on workers, shifts and payables |
| Pay code | the `apiKey` as `payCode` on payables and deductions |

**Set by Everee.Workers' comp classes** are entered by Everee during company onboarding and updated at each renewal. You can list them to find the codes you attach to hours.

Endpoint map: organization

| Method | Endpoint | What it does | Docs |
| --- | --- | --- | --- |
| POST | `/integration/v1/work-locations` | Create a work location | [Reference](https://developer.everee.com/reference/add-work-location) |
| GET | `/integration/v1/work-locations` | List work locations | [Reference](https://developer.everee.com/reference/list-work-locations) |
| DELETE | `/integration/v1/work-locations/{workLocationId}` | Archive a work location | [Reference](https://developer.everee.com/reference/archive-work-location) |
| POST | `/integration/v1/payroll-calendar` | Create a payroll calendar | [Reference](https://developer.everee.com/reference/create-payroll-calendar) |
| GET | `/integration/v1/payroll-calendar` | List payroll calendars | [Reference](https://developer.everee.com/reference/list-payroll-calendars) |
| POST | `/integration/v1/approval-groups` | Create an approval group | [Reference](https://developer.everee.com/reference/add-approval-group) |
| GET | `/integration/v1/approval-groups` | List approval groups | [Reference](https://developer.everee.com/reference/list-approval-groups) |
| POST | `/integration/v1/cost-centers` | Create a cost center | [Reference](https://developer.everee.com/reference/add-cost-center) |
| POST | `/integration/v1/pay-codes` | Create a pay code | [Reference](https://developer.everee.com/reference/create-a-pay-code) |
| GET | `/integration/v1/pay-codes` | List pay codes | [Reference](https://developer.everee.com/reference/list-pay-codes) |
| GET | `/integration/v1/workers-comp` | List workers' comp classes | [Reference](https://developer.everee.com/reference/list-workers-comp-classes) |

Area 3

## Add and maintain workers Available

Create complete worker records, and keep them in sync with your records.

A worker must finish onboarding before Everee can pay them. In Payroll Infrastructure you collect the worker's information in your own product and send Everee a complete record: taxpayer identifier, date of birth, addresses, bank account and tax settings. Marking the record complete lets the worker be paid once their hire date arrives.

### Prompt for your coding agent

Copy this into your coding agent, or point the agent at this page and it can read the prompt directly. It names the docs to read first, the operations to call, the rules that matter for this area, and the tests to write. [Open as Markdown](https://files.everee.com/prompts/workers.md)

**Agent prompt: Area 3: Add and maintain workers**

```
GOAL
Build worker management: add employees and contractors as complete records, show and edit their profiles, and handle separation, rehire and deletion.

READ FIRST (each page also has a Markdown version at the same URL with .md added; the docs index is https://developer.everee.com/llms.txt)
- https://developer.everee.com/docs/worker-data-and-onboarding
- https://developer.everee.com/reference/look-up-hiring-status-for-a-worker
- https://developer.everee.com/reference/add-a-complete-employee-record
- https://developer.everee.com/reference/add-a-complete-contractor-record
- https://developer.everee.com/reference/retrieve-a-worker
- https://developer.everee.com/reference/update-payment-preferences
- https://developer.everee.com/reference/separate-an-employee
- https://developer.everee.com/reference/rehire-a-worker

BUILD
- Before every create, POST /worker-hiring-status/search to learn whether the person already exists, was hired before or is a rehire, and follow the answer.
- A profile form that collects the full record (legal name, date of birth, contact, home address, tax identifiers, position, pay rate, hire date, work location, approval group, payroll calendar) and sends it to POST /workers/employee or /workers/contractor.
- A worker list and detail screen from GET /workers and /workers/{id}, edits through the update calls, a 'Process termination' action (PUT /workers/{id}/separate-employee), rehire, and delete only while still in onboarding.
- Handle worker.onboarding-completed, worker.profile-updated, worker.created and tin-verification-status-changed events by re-reading the worker.

OPERATIONS (all paths are under https://api.everee.com/integration/v1; each reference page, with .md added, lists its request and response fields)
- POST /worker-hiring-status/search | operationId post_integrationv1worker-hiring-statussearch | https://developer.everee.com/reference/look-up-hiring-status-for-a-worker.md
- POST /workers/employee | operationId add-a-complete-employee-record | https://developer.everee.com/reference/add-a-complete-employee-record.md
- POST /workers/contractor | operationId add-a-complete-contractor-record | https://developer.everee.com/reference/add-a-complete-contractor-record.md
- GET /workers | operationId list-workers | https://developer.everee.com/reference/list-workers.md
- GET /workers/{id} | operationId retrieve-a-worker | https://developer.everee.com/reference/retrieve-a-worker.md
- PUT /workers/{id}/payment-info | operationId update-payment-preferences | https://developer.everee.com/reference/update-payment-preferences.md
- PUT /workers/{id}/separate-employee | operationId separate-an-employee | https://developer.everee.com/reference/separate-an-employee.md
- POST /workers/{id}/rehire | operationId rehire-a-worker | https://developer.everee.com/reference/rehire-a-worker.md
- DELETE /workers/{id} | operationId delete-a-worker-in-onboarding | https://developer.everee.com/reference/delete-a-worker-in-onboarding.md

RULES
- Payroll Infra uses the full-record flow only. Supply a stable externalWorkerId from my system and store Everee's worker id next to it.
- Effective dates matter: a hire date in the future or a change effective later must be respected, not applied now.
- A worker with any transacted payment can't be deleted, only separated.
- Base URL https://api.everee.com/integration/v1. The partner key (psk_...) is the HTTP Basic user name for the Company Onboarding API. The company key (tsk_...) is the HTTP Basic user name for everything else, plus an x-everee-tenant-id header holding the company's id.
- Keep every key on the server. Everee rejects browser requests. Read keys from a secrets store, never log them, never hard-code them.
- Rate limit: 100 operations per 5 seconds per key (see the RateLimit-Policy header). Back off on 429.
- Only payables have an idempotency key (externalId). Make other creates safe yourself: look first, keep the Everee ID next to your own record.
- Test against a sandbox instance (tsk_test_... keys) before production. Nothing in a URL selects the environment; the key does.

DONE WHEN
- A sandbox employee is created, edited, separated and rehired from my UI, with no duplicate created by retries.
- A failed TIN verification event surfaces a clear fix-it prompt to the user.

TESTS TO WRITE
- The hiring-status lookup always runs before a create, and a status of ACTIVE links the existing worker instead of creating one.
- Retrying a create with the same externalWorkerId creates no second worker.
- A future hire date is kept as a future date.
- A worker with a transacted payment can't be deleted in your UI, only separated.
- A tin-verification-status-changed event with VERIFICATION_FAILED shows the user what to fix.

If a fact you need isn't in the docs, ask me. Don't guess endpoint paths, field names or business rules.
```

**You handle sensitive data.** Social Security numbers and bank account numbers pass through your systems, and you take on the responsibility for protecting them. Never log them, and never put them in a client-side request.

### Employees and contractors

|  | Employee (W-2) | Contractor (1099) |
| --- | --- | --- |
| Taxes | Withheld and remitted for you, with the employer's share | The contractor handles their own taxes |
| Tax form collected | W-4 and state forms, plus a Form I-9 if the company's setup calls for one | W-9 |
| Year-end form | W-2 | 1099 |
| Paid | On a payroll calendar, or as soon as possible | As soon as possible |
| Hours | Timesheets API | Not tracked by Everee. Send payable items. |

Everee's tax operations team calculates and remits taxes, files quarterly and annual forms and issues W-2 and 1099 forms, so none of it is built into your integration. [Guide: onboarding and managing workers](https://developer.everee.com/docs/worker-data-and-onboarding)

### Step 1: look up hiring status before every create

A duplicate profile causes payroll and tax filing problems. Send as much as you have; the SSN is the most reliable. If you send an `externalWorkerId` the lookup also checks it against the matched worker.

| hiringScenario | What to do |
| --- | --- |
| `NEW_HIRE` | Create a profile. |
| `ACTIVE` | Don't create one. Link the existing worker to your record using the `workerId` returned. |
| `ELIGIBLE_FOR_REHIRE` | Rehire the worker instead of creating a profile. The rehire date can't be earlier than `earliestValidHireDate`. |
| `NOT_ELIGIBLE_FOR_REHIRE` | Don't create a profile. The company marked this person not eligible. |

### Step 2: create the complete record

Send everything Everee needs in one request, with your own ID as `externalWorkerId`, and set `onboardingComplete` to `true`. Leave it `false` only if the worker still has data to provide.

| Data area | What Everee needs | What you send in the complete record |
| --- | --- | --- |
| Identity | Name, date of birth, phone, email | All four. `dateOfBirth` is required. |
| Taxpayer identifier | SSN or other; checked against IRS and SSA records | Employee: `taxpayerIdentifier`. Contractor: `socialSecurityNumber` or `employerIdentificationNumber` in `w9FormResponse`. |
| Home address | Residence, for tax and forms | `homeAddress` |
| Work location | Default legal work address | `legalWorkAddress` |
| Position and pay | Pay type, rate, weekly hours, hire date (contractors: start date) | On the same request |
| Payment method | A bank account, unless the worker is paid outside Everee | `bankAccount` |
| Tax forms | W-4 and state forms, or a W-9 | Employee: `withholdingSettings`. Contractor: `w9FormResponse`. |
| Onboarding | Marked complete so the worker can be paid | `onboardingComplete: true` |

### The worker lifecycle

Wages and payables sent before the worker becomes payable are held and released when they do. Store the Everee `workerId` from `worker.created` against your own record.

### Contractor W-9

Send `w9FormResponse` with the taxpayer identifier, and Everee treats the W-9 as complete. **Everee captures no signature** for it, so if you need a signed W-9 on file, capturing and storing it is up to you.

### Workers you pay outside Everee

Mark them with `externallyPaid: true` in payment preferences. No bank account is needed, no money moves, and the setting can't be combined with direct deposit or pay card. To switch back, send `externallyPaid: false` with a payment method.

### Keep profiles in sync

Your product is the source of truth. Store your own ID as `externalWorkerId`, push each change with its endpoint, and subscribe to `worker.profile-updated`, a catch-all with only IDs, to learn when something changed in Everee. Then retrieve the worker and update your copy.

| Change | Endpoint |
| --- | --- |
| Name, email, phone, date of birth | [Update personal information](https://developer.everee.com/reference/update-personal-information) |
| Home address | [Update home address](https://developer.everee.com/reference/update-a-workers-home-address) |
| Title, pay rate, pay type, weekly hours, default cost centers | [Update position and compensation](https://developer.everee.com/reference/update-position-compensation) |
| Default work location | [Update work location](https://developer.everee.com/reference/update-worker-work-location2) |
| Approval group | [Update approval group](https://developer.everee.com/reference/update-approval-group) |
| Payroll calendar | [Update payroll calendar](https://developer.everee.com/reference/update-worker-payroll-calendar) |
| Payment preferences | [Update payment preferences](https://developer.everee.com/reference/update-payment-preferences) |
| Bank accounts and splits | [Worker Direct Deposit API](https://developer.everee.com/reference/worker-direct-deposit-api-guide) |
| Taxpayer identifier | [Update taxpayer identifier](https://developer.everee.com/reference/update-a-workers-taxpayer-identifier) |
| Hire date | [Update start date](https://developer.everee.com/reference/update-worker-start-date) |

### Separate and rehire

Separate an employee with a date, rehire eligibility, severance, benefits end date and leave payout. `eligibleForRehire` is what a later hiring status search returns. Rehire when the status is `ELIGIBLE_FOR_REHIRE`. If the worker type changes, create a new profile instead.

### Correcting mistakes

Update a wrong hire date. Delete a worker only while nothing beyond onboarding data exists under it. A duplicate that already has payroll data needs support. If a call fails, see [Diagnosing a failed request](https://developer.everee.com/docs/diagnosing-failed-requests).

Endpoint map: workers

| Method | Endpoint | What it does | Docs |
| --- | --- | --- | --- |
| POST | `/integration/v1/worker-hiring-status/search` | Look up hiring status | [Reference](https://developer.everee.com/reference/look-up-hiring-status-for-a-worker) |
| POST | `/integration/v1/workers/employee` | Create a complete employee record | [Reference](https://developer.everee.com/reference/add-a-complete-employee-record) |
| POST | `/integration/v1/workers/contractor` | Create a complete contractor record | [Reference](https://developer.everee.com/reference/add-a-complete-contractor-record) |
| GET | `/integration/v1/workers` | List workers | [Reference](https://developer.everee.com/reference/list-workers) |
| GET | `/integration/v1/workers/{id}` | Retrieve a worker | [Reference](https://developer.everee.com/reference/retrieve-a-worker) |
| PUT | `/integration/v1/workers/{id}/payment-info` | Update payment preferences | [Reference](https://developer.everee.com/reference/update-payment-preferences) |
| PUT | `/integration/v1/workers/{id}/separate-employee` | Separate an employee | [Reference](https://developer.everee.com/reference/separate-an-employee) |
| POST | `/integration/v1/workers/{id}/rehire` | Rehire a worker | [Reference](https://developer.everee.com/reference/rehire-a-worker) |
| DELETE | `/integration/v1/workers/{id}` | Delete a worker still in onboarding | [Reference](https://developer.everee.com/reference/delete-a-worker-in-onboarding) |

Area 4

## Send worker payroll settings Available

Recurring deductions, paid leave policies and garnishments, each applied with an effective date.

Settings change what a worker takes home: recurring deductions, garnishments, and paid leave. Each is sent with an effective date, so Everee applies it to the right payroll without rewriting past ones.

### Prompt for your coding agent

Copy this into your coding agent, or point the agent at this page and it can read the prompt directly. It names the docs to read first, the operations to call, the rules that matter for this area, and the tests to write. [Open as Markdown](https://files.everee.com/prompts/settings.md)

**Agent prompt: Area 4: Worker payroll settings**

```
GOAL
Build the screens and sync for each worker's payroll settings: benefit, retirement and other deductions, garnishments and child-support orders, and paid leave (types, policies, enrollment, balances).

READ FIRST (each page also has a Markdown version at the same URL with .md added; the docs index is https://developer.everee.com/llms.txt)
- https://developer.everee.com/reference/deductions-api-guide
- https://developer.everee.com/reference/apply-benefit-deduction
- https://developer.everee.com/reference/apply-retirement-deduction
- https://developer.everee.com/reference/apply-other-deduction
- https://developer.everee.com/reference/get-deduction-reconciliation
- https://developer.everee.com/reference/list-leave-types
- https://developer.everee.com/reference/create-leave-policy
- https://developer.everee.com/reference/enroll-workers-in-leave-policy

BUILD
- An elections table per worker like a benefits screen: each row posts to POST /deductions/benefits, /retirement or /other to start, change or end it, with an effective date and employee and employer amounts or percentages (including 401(k) match tiers).
- A reconciliation view from GET /deductions/reconciliation showing what payroll actually deducted for a pay period, to compare with the elections.
- Leave: manage types, policies, enrollment and balances (GET/POST /leave/types, /leave/policies, enrollments, worker balances, award rules).
- Garnishments and income-withholding orders are multipart POSTs (/garnishments, /income-withholding-orders): upload the order document with the terms.

OPERATIONS (all paths are under https://api.everee.com/integration/v1; each reference page, with .md added, lists its request and response fields)
- POST /deductions/benefits | operationId apply-benefit-deduction | https://developer.everee.com/reference/apply-benefit-deduction.md
- POST /deductions/retirement | operationId apply-retirement-deduction | https://developer.everee.com/reference/apply-retirement-deduction.md
- POST /deductions/other | operationId apply-other-deduction | https://developer.everee.com/reference/apply-other-deduction.md
- GET /deductions/reconciliation | operationId get_deduction_reconciliation | https://developer.everee.com/reference/get-deduction-reconciliation.md
- GET /leave/types | operationId list-leave-types | https://developer.everee.com/reference/list-leave-types.md
- POST /leave/types | operationId create-leave-type | https://developer.everee.com/reference/create-leave-type.md
- DELETE /leave/types/{leaveTypeName} | operationId delete-leave-type | https://developer.everee.com/reference/delete-leave-type.md
- GET /leave/policies | operationId list-leave-policies | https://developer.everee.com/reference/list-leave-policies.md
- POST /leave/policies | operationId create-leave-policy | https://developer.everee.com/reference/create-leave-policy.md
- PUT /leave/policies/{policyId} | operationId update-leave-policy | https://developer.everee.com/reference/update-leave-policy.md
- DELETE /leave/policies/{policyId} | operationId delete-leave-policy | https://developer.everee.com/reference/delete-leave-policy.md
- GET /leave/policies/unenrolled | operationId list-unenrolled-workers | https://developer.everee.com/reference/list-unenrolled-workers.md
- POST /leave/policies/{policyId}/enrollments | operationId enroll-workers-in-leave-policy | https://developer.everee.com/reference/enroll-workers-in-leave-policy.md
- POST /leave/policies/{policyId}/unenroll | operationId unenroll-workers-from-leave-policy | https://developer.everee.com/reference/unenroll-workers-from-leave-policy.md
- GET /workers/{workerId}/leave/balances | operationId get-worker-leave-balances | https://developer.everee.com/reference/get-worker-leave-balances.md
- PUT /workers/{workerId}/leave/balances/{leaveTypePayCode} | operationId update-worker-leave-balance | https://developer.everee.com/reference/update-worker-leave-balance.md
- PUT /workers/{workerId}/leave/award-rules | operationId update-worker-leave-award-rules | https://developer.everee.com/reference/update-worker-leave-award-rules.md
- POST /garnishments | operationId (see page)
- POST /income-withholding-orders | operationId (see page)

RULES
- Changes apply from an effective date and never change past payrolls. Show the effective date and don't offer back-dating that Everee would reject.
- Everee calculates garnishment limits and handles remittance. Send the order, never calculate or remit it yourself.
- Base URL https://api.everee.com/integration/v1. The partner key (psk_...) is the HTTP Basic user name for the Company Onboarding API. The company key (tsk_...) is the HTTP Basic user name for everything else, plus an x-everee-tenant-id header holding the company's id.
- Keep every key on the server. Everee rejects browser requests. Read keys from a secrets store, never log them, never hard-code them.
- Rate limit: 100 operations per 5 seconds per key (see the RateLimit-Policy header). Back off on 429.
- Only payables have an idempotency key (externalId). Make other creates safe yourself: look first, keep the Everee ID next to your own record.
- Test against a sandbox instance (tsk_test_... keys) before production. Nothing in a URL selects the environment; the key does.

DONE WHEN
- A deduction can be started, changed and ended in sandbox, and reconciliation matches the election after a sandbox payroll.
- Leave balances shown to users come from the API, not a local calculation.

TESTS TO WRITE
- Start, change and end a deduction each send the right effective date, and a past end date is blocked in your UI.
- After a sandbox payroll, the reconciliation endpoint totals match the elections, or the screen shows the difference.
- A garnishment or income-withholding order is sent as multipart with its document.
- Leave balances on screen come from the API, never from a local calculation.

If a fact you need isn't in the docs, ask me. Don't guess endpoint paths, field names or business rules.
```

### Deductions: keep elections in sync

If you administer benefits or retirement plans, you hold what each participant elected. Everee holds the payroll that deducts it.

| Endpoint | Use it for |
| --- | --- |
| [Apply benefit deduction](https://developer.everee.com/reference/apply-benefit-deduction) | Medical, dental, vision, HSA, FSA, life, disability and similar |
| [Apply retirement deduction](https://developer.everee.com/reference/apply-retirement-deduction) | 401(k), Roth 401(k), 403(b), IRAs and state retirement plans, with employer match tiers |
| [Apply other deduction](https://developer.everee.com/reference/apply-other-deduction) | Dues, savings and loan repayments |

A deduction is identified by the worker and the pay code, so you never store an Everee deduction ID. Other deductions also take your own `externalId`.

| You send | What happens |
| --- | --- |
| `effectiveDate` | The deduction is created, or updated if it exists |
| `effectiveDate` and `effectiveEndDate` | The same, with an end date |
| Only `effectiveEndDate` | The existing deduction is ended |
| Neither | Rejected with `422` |

**A 401(k) at 5% of pay with a tiered match**

```
curl -X POST "https://api.everee.com/integration/v1/deductions/retirement" \
  -u "$COMPANY_KEY:" -H "x-everee-tenant-id: $COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "workerId": "emp-1042", "payCode": "ERISA_401K",
  "deductionPercentage": { "employeePercentage": 0.05 },
  "employerMatchTiers": [
    { "matchRate": 1.0, "percentOfWages": 0.03 },
    { "matchRate": 0.5, "percentOfWages": 0.02 } ],
  "effectiveDate": "2027-01-01"
}'
```

- **Percentages are decimal fractions.** Send `0.05` for 5%.
- **Send exactly one** of `deductionAmount` or `deductionPercentage`. Fixed amounts need a `periodType`.
- **Changes never rewrite past payrolls.** A used deduction is ended the day before your date and a new one starts on it. The response shows the dates actually used, so store those.
- For an HSA send `hsaLimitType`. State retirement Roth 401(k) pay codes need a state prefix such as `CA_STATE_RETIREMENT_PLAN_ROTH_401K`. Custom pay codes work too.

[Guide to the Deductions API](https://developer.everee.com/reference/deductions-api-guide) · [Guide: syncing deductions](https://developer.everee.com/docs/syncing-deductions) · [Get deduction reconciliation](https://developer.everee.com/reference/get-deduction-reconciliation)

### Leave and paid time off

**Set up leave types**List first: Everee provides system defaults you can't recreate. Create the rest by name. Each gets its own pay code, like `TIME_OFF_TYPE_JURYDUTY`. Pass `state` for sick leave that accrues only on wages in one state (not available to every company yet; best-match accrual applies).

**Create a leave policy**Choose how each type is earned, plus eligibility waiting periods, an award rule with optional limits, and optional tenure tiers. Only the name and description can be edited afterward. To adjust one worker, change that worker's award rules.

**Enroll workers**Up to 200 at a time, starting tomorrow. A move to another policy ends the current enrollment today. Requests are all-or-nothing. You can also pass `timeOffPolicyId` when you create an employee.

**Read and set balances**Balances are in hours per leave type, identified by pay code. Set a balance to load starting values. The difference is recorded as an adjustment so history is kept.

| List in a policy | How it's earned | Pays out |
| --- | --- | --- |
| `accruedLeaveTypes` | A little at a time as workers work, such as 1 hour per 30 worked | Yes |
| `frontLoadedLeaveTypes` | A lump of hours at the start of each year, quarter or month | Yes |
| `unpaidFrontLoadedLeaveTypes` | The same, for unpaid leave | No |

| A leave payout is a payable |  |
| --- | --- |
| `payCode` | The leave type's pay code, always starting `TIME_OFF_TYPE_` |
| `unitCount` | Required. The hours paid out. The request is rejected without it. |
| `amount` | You calculate it, as with any payable. |
| Balance check | If the worker is enrolled, the hours can't exceed the available balance. Check balances first. |
| Cost centers | Use the `costCenters` on the payable. Leave Everee generates uses the worker's default cost centers. |

Deleting a leave type or policy removes it if unused and archives it otherwise. A policy with active enrollments can't be removed. Contractors can't be enrolled. [Guide to the Leave Accrual API](https://developer.everee.com/reference/leave-accrual-api-guide) · [Guide: managing leave and PTO](https://developer.everee.com/docs/leave-and-pto)

### Garnishments Docs coming

Everee automatically calculates each garnishment against the applicable limits and handles remittance, so you send the order, not the math. Garnishment and child support income withholding order endpoints exist, but their reference pages are still to come. Ask your Everee contact before building against them.

Endpoint map: deductions, leave and garnishments

| Method | Endpoint | What it does | Docs |
| --- | --- | --- | --- |
| POST | `/integration/v1/deductions/benefits` | Start, change or end a benefit deduction | [Reference](https://developer.everee.com/reference/apply-benefit-deduction) |
| POST | `/integration/v1/deductions/retirement` | Start, change or end a retirement deduction | [Reference](https://developer.everee.com/reference/apply-retirement-deduction) |
| POST | `/integration/v1/deductions/other` | Start, change or end another deduction | [Reference](https://developer.everee.com/reference/apply-other-deduction) |
| GET | `/integration/v1/deductions/reconciliation` | What payroll deducted for a pay period | [Reference](https://developer.everee.com/reference/get-deduction-reconciliation) |
| GET | `/integration/v1/leave/types` | List leave types | [Reference](https://developer.everee.com/reference/list-leave-types) |
| POST | `/integration/v1/leave/types` | Create a leave type | [Reference](https://developer.everee.com/reference/create-leave-type) |
| DELETE | `/integration/v1/leave/types/{leaveTypeName}` | Delete or archive a leave type | [Reference](https://developer.everee.com/reference/delete-leave-type) |
| GET | `/integration/v1/leave/policies` | List leave policies | [Reference](https://developer.everee.com/reference/list-leave-policies) |
| POST | `/integration/v1/leave/policies` | Create a leave policy | [Reference](https://developer.everee.com/reference/create-leave-policy) |
| PUT | `/integration/v1/leave/policies/{policyId}` | Update name and description | [Reference](https://developer.everee.com/reference/update-leave-policy) |
| DELETE | `/integration/v1/leave/policies/{policyId}` | Delete or archive a policy | [Reference](https://developer.everee.com/reference/delete-leave-policy) |
| GET | `/integration/v1/leave/policies/unenrolled` | Workers with no policy | [Reference](https://developer.everee.com/reference/list-unenrolled-workers) |
| POST | `/integration/v1/leave/policies/{policyId}/enrollments` | Enroll workers | [Reference](https://developer.everee.com/reference/enroll-workers-in-leave-policy) |
| POST | `/integration/v1/leave/policies/{policyId}/unenroll` | Unenroll workers | [Reference](https://developer.everee.com/reference/unenroll-workers-from-leave-policy) |
| GET | `/integration/v1/workers/{workerId}/leave/balances` | A worker's balances | [Reference](https://developer.everee.com/reference/get-worker-leave-balances) |
| PUT | `/integration/v1/workers/{workerId}/leave/balances/{leaveTypePayCode}` | Set a balance | [Reference](https://developer.everee.com/reference/update-worker-leave-balance) |
| PUT | `/integration/v1/workers/{workerId}/leave/award-rules` | Change one worker's award rules | [Reference](https://developer.everee.com/reference/update-worker-leave-award-rules) |
| POST | `/integration/v1/garnishments` | Apply or end a garnishment (multipart) | Docs coming |
| POST | `/integration/v1/income-withholding-orders` | Apply or end a child support order (multipart) | Docs coming |

Area 5

## Run payroll each cycle Coming soon

Send hours and pay items each cycle. The Run payroll API arrives in early November.

Everee turns the hours and payable items you send into payments, calculates taxes and net pay, and pays workers. Your product supplies the inputs on a schedule and drives each payroll run through the API. Submitting wages is always safe to do early and often, because no money moves until the payroll run is approved.

### Prompt for your coding agent

Copy this into your coding agent, or point the agent at this page and it can read the prompt directly. It names the docs to read first, the operations to call, the rules that matter for this area, and the tests to write. [Open as Markdown](https://files.everee.com/prompts/pay.md)

**Agent prompt: Area 5: Run payroll**

```
GOAL
Build the inputs and approval experience for running payroll: send hours and pay items each cycle, request payouts, and plan the screens for the payroll-run step that is coming in early November.

READ FIRST (each page also has a Markdown version at the same URL with .md added; the docs index is https://developer.everee.com/llms.txt)
- https://developer.everee.com/docs/running-payroll
- https://developer.everee.com/reference/payables-api-guide
- https://developer.everee.com/reference/createpayable
- https://developer.everee.com/reference/add-a-shift-to-an-employees-time-card
- https://developer.everee.com/reference/update-classified-hours-for-pay-period-bulk
- https://developer.everee.com/reference/createpayablepaymentrequest
- https://developer.everee.com/reference/get-earnings-on-demand-status

BUILD
- Send time: POST /labor/timesheet/worked-shifts for shifts, and /labor/classified-hours/bulk for a pay period's classified hours.
- Send pay items: POST /payables (or /payables/bulk) using your own externalId for each, then POST /payables/payment-request to request a payout when a worker should be paid right away.
- Early Pay (/earnings-on-demand/status and /custom-amount) and Real Time Payroll enrollment (/real-time-payroll/enrollment) screens, both subject to credit approval by Everee.
- Design, but do not wire, the payroll-run step: a summary of the run, an approval action before the daily cutoff of 10:30am PT (1:30pm ET), and the funding and payment states.

OPERATIONS (all paths are under https://api.everee.com/integration/v1; each reference page, with .md added, lists its request and response fields)
- POST /labor/timesheet/worked-shifts | operationId add-a-shift-to-an-employees-time-card | https://developer.everee.com/reference/add-a-shift-to-an-employees-time-card.md
- POST /labor/classified-hours/bulk | operationId update-classified-hours-for-pay-period-bulk | https://developer.everee.com/reference/update-classified-hours-for-pay-period-bulk.md
- POST /payables | operationId createPayable | https://developer.everee.com/reference/createpayable.md
- POST /payables/bulk | operationId createPayablesBulk | https://developer.everee.com/reference/createpayablesbulk.md
- POST /payables/payment-request | operationId createPayablePaymentRequest | https://developer.everee.com/reference/createpayablepaymentrequest.md
- GET /payables/{externalId} | operationId getPayable | https://developer.everee.com/reference/getpayable.md
- GET /earnings-on-demand/status | operationId get-earnings-on-demand-status | https://developer.everee.com/reference/get-earnings-on-demand-status.md
- POST /earnings-on-demand/custom-amount | operationId request-earnings-on-demand | https://developer.everee.com/reference/request-earnings-on-demand.md
- PUT /real-time-payroll/enrollment | operationId put_integrationv1real-time-payrollworker-enrollment | https://developer.everee.com/reference/update-real-time-payroll-enrollment.md

RULES
- The externalId on a payable is the only idempotency key in the API. Reuse the same id on a retry and never invent a new one.
- The Run payroll API isn't published yet. Don't invent endpoints or fields for it. Leave a clearly marked interface for it.
- The company's bank account is debited the day needed to reach the pay date. Funding statuses are PENDING, SUBMITTED, FUNDED and FAILED (read them in the payroll journal). Failed or NSF funding handling is coming with the Run payroll API: show FAILED clearly and tell the user to contact Everee Customer Success.
- The company connects its funding bank account with the FUNDING_BANK_ACCOUNT component (coming soon). Never collect bank credentials yourself.
- Base URL https://api.everee.com/integration/v1. The partner key (psk_...) is the HTTP Basic user name for the Company Onboarding API. The company key (tsk_...) is the HTTP Basic user name for everything else, plus an x-everee-tenant-id header holding the company's id.
- Keep every key on the server. Everee rejects browser requests. Read keys from a secrets store, never log them, never hard-code them.
- Rate limit: 100 operations per 5 seconds per key (see the RateLimit-Policy header). Back off on 429.
- Only payables have an idempotency key (externalId). Make other creates safe yourself: look first, keep the Everee ID next to your own record.
- Test against a sandbox instance (tsk_test_... keys) before production. Nothing in a URL selects the environment; the key does.

DONE WHEN
- Sandbox hours and payables created from my UI appear in the worker's payment data, and a retried submission creates no duplicate.
- The run-payroll screens exist behind a feature flag with a single interface to fill in when the API ships.

TESTS TO WRITE
- Sending the same payable twice with the same externalId results in one payable (check with GET /payables/{externalId}).
- The externalId is built from stable data: the same inputs always give the same id (a unit test).
- A shift in the future is rejected by your form, and a classified-hours call sent twice gives the same total, because it replaces.
- The payout request runs after the contractor's payables and before the run is approved.
- The run-payroll screens sit behind a feature flag with one interface to fill in when the API ships.

If a fact you need isn't in the docs, ask me. Don't guess endpoint paths, field names or business rules.
```

**The Run payroll API is coming in early November and isn't published yet.** Approving a payroll run will be an API call from your product, and nobody needs an Everee sign-in. The daily approval cutoff is **10:30am PT (1:30pm ET)**. This section will list its endpoints, funding timing and failure handling when it ships.

### How pay flows through Everee

| Run payroll topic | Status |
| --- | --- |
| Approval cutoff | 10:30am PT (1:30pm ET), daily |
| Company bank account debit | The day needed to reach the pay date of the payroll run |
| Funding statuses (read today in the payroll journal) | `PENDING`, `SUBMITTED`, `FUNDED`, `FAILED`. A failed funding, for example insufficient funds (NSF), shows as `FAILED`. Transfer questions about it to Everee Customer Success. |
| Approval endpoints and failed or NSF funding handling and retries | Coming soon Details arrive with the Run payroll API in early November. See [Running payroll](https://developer.everee.com/docs/running-payroll) |

### Which API for which earning

Hourly wages always go through the Timesheets API, even when you've already classified the hours, because overtime and other hourly rules shape the calculation and the pay stub. Payables are for everything else.

| You're paying | You have | Use | Paid |
| --- | --- | --- | --- |
| An hourly employee | Punch times, with breaks if you track them | [Create a shift](https://developer.everee.com/reference/add-a-shift-to-an-employees-time-card) | On the employee's regular cycle |
| An hourly employee | Hours already classified as regular, overtime and double time | [Update classified hours](https://developer.everee.com/reference/update-classified-hours-for-pay-period-bulk) | On the employee's regular cycle |
| An employee | A flat amount: bonus, commission, stipend, reimbursement, leave payout | [Create a payable](https://developer.everee.com/reference/createpayable) | On the regular cycle, or as soon as possible |
| A contractor | Any amount for services or reimbursement | [Create a payable](https://developer.everee.com/reference/createpayable) then [request payout](https://developer.everee.com/reference/createpayablepaymentrequest) | As soon as possible |

### Shifts or classified hours

|  | Shifts | Classified hours |
| --- | --- | --- |
| You send | Each shift's start and end, with breaks | Period totals already split into regular, overtime and double time |
| Everee classifies overtime | Yes, by federal and state rules | No. You classify first. |
| Pay stub detail | Shift detail shown | None |
| When to send | As each shift completes | Once per pay period |
| Prefer | Shifts, when you can. Some places require shift detail on pay stubs. | Only if you have pre-classified totals |

### Send pay, step by step

1

### Send shifts with breaks

Record a lunch as a **break inside one shift**, not as two shifts. Send `workLocationId`, `effectiveHourlyPayRate` and `workersCompClassCode` with every shift. Times are Unix epoch seconds, and a shift can't be in the future.

Everee classifies overtime and double time under the FLSA and each state's rules, from the worker's legal work location.

[Guide to the Timesheets API](https://developer.everee.com/reference/using-the-timesheets-api)[Time and attendance](https://developer.everee.com/docs/time-and-attendance)

**POST /integration/v1/labor/timesheet/worked-shifts**

```
curl -X POST "https://api.everee.com/integration/v1/labor/timesheet/worked-shifts" \
  -u "$COMPANY_KEY:" -H "x-everee-tenant-id: $COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "externalWorkerId": "emp-1042",
  "shiftStartEpochSeconds": 1792051200, "shiftEndEpochSeconds": 1792080000,
  "createBreaks": [ { "segmentConfigCode": "DEFAULT_UNPAID", "breakDuration": "PT30M" } ],
  "effectiveHourlyPayRate": { "amount": "22.50", "currency": "USD" },
  "workLocationId": 1234, "workersCompClassCode": "8810",
  "costCenters": [ { "type": "clientId", "value": "290" } ]
}'
```

2

### Or send classified hours for a period

**Each call replaces hours; it never adds to them.** It replaces everything Everee holds for that worker, pay period and work location, so send a worker's complete hours for a location in one call. Send FLSA and non-FLSA overtime in separate fields.

[Update classified hours](https://developer.everee.com/reference/update-classified-hours-for-pay-period-bulk)

**POST /integration/v1/labor/classified-hours/bulk**

```
curl -X POST "https://api.everee.com/integration/v1/labor/classified-hours/bulk" \
  -u "$COMPANY_KEY:" -H "x-everee-tenant-id: $COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "earningDate": "2026-10-07",
  "classifiedHoursPerWorker": [ { "externalWorkerId": "emp-1042",
    "classifiedHours": [ { "payRate": { "amount": "22.50", "currency": "USD" },
      "workLocationId": "1234", "regularHoursWorked": "40.00",
      "flsaQualifiedOvertimeHoursWorked": "6.50" } ] } ]
}'
```

3

### Send everything else as payables

A payable is one amount for one worker under a pay code. You provide the amount. **`externalId` is an idempotency key**: build it from stable data, never a timestamp or random value, or a retry pays twice. Use `earningTimestamp` (Unix seconds) and set `workLocationId` so employee wages are taxed in the right place.

[Guide to the Payables API](https://developer.everee.com/reference/payables-api-guide)[Sending pay to Everee](https://developer.everee.com/docs/paying-workers)

**POST /integration/v1/payables**

```
curl -X POST "https://api.everee.com/integration/v1/payables" \
  -u "$COMPANY_KEY:" -H "x-everee-tenant-id: $COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "externalId": "client_123::emp-1042::on_time_bonus_20261016",
  "externalWorkerId": "emp-1042", "label": "On-time bonus, October",
  "payableModel": "PRE_CALCULATED", "payCode": "BONUS", "type": "bonus",
  "amount": { "amount": 150.00, "currency": "USD" },
  "earningTimestamp": 1792000000, "workLocationId": 1234,
  "costCenters": [ { "type": "clientId", "value": "290" } ]
}'
```

4

### Request payout for contractors

Contractors have no regular cycle, so nothing is paid until you request payout. Call it **after** you've sent all of a contractor's payables and **before** you approve the payroll run. With no parameters it processes every unpaid contractor payable and leaves employees' items for regular payroll.

To pay an employee's payable without waiting, add `includeWorkersOnRegularPayCycle: true`, and limit it with `externalIds` or `externalWorkerIds`.

[Request ASAP payout](https://developer.everee.com/reference/createpayablepaymentrequest)

**POST /integration/v1/payables/payment-request**

```
curl -X POST "https://api.everee.com/integration/v1/payables/payment-request" \
  -u "$COMPANY_KEY:" -H "x-everee-tenant-id: $COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get workers paid faster

Two fast-pay features sit alongside regular payroll.

### Early Pay

Employees request part of their wages ahead of regular payroll. You call two endpoints: **Get Early Pay Status** returns the amount available and any fee, and **Request Early Pay** pays it out as soon as possible. By default the available amount is 75% of verified gross hourly earnings minus payroll deductions, and the limit can be changed. The payment is fully taxed and remitted, and Everee reconciles it against the worker's next payroll automatically. You can add a worker fee if you want.

[How Early Pay works](https://developer.everee.com/reference/how-early-pay-works) · [Get status](https://developer.everee.com/reference/get-earnings-on-demand-status) · [Request Early Pay](https://developer.everee.com/reference/request-earnings-on-demand)

### Real Time Payroll

Enroll an employee so their earnings are paid as they accrue instead of on the regular schedule. Enrollment isn't a pay schedule, and a change takes effect at the next pay period boundary. Only employees can be enrolled.

[Real Time Payroll guide](https://developer.everee.com/docs/real-time-payroll) · [Update enrollment](https://developer.everee.com/reference/update-real-time-payroll-enrollment)

**Credit approval.** Early Pay and Real Time Payroll are both subject to credit approval by Everee.

### Follow a payment

Subscribe instead of polling. A returned deposit isn't the end: the payable stays `PAID` and Everee retries under the same payment ID. [Returned deposits and retries](https://developer.everee.com/docs/returned-deposits-and-retries)

| Event | Meaning |
| --- | --- |
| `payment.paid` | A payment was submitted for deposit. It lists shifts and payables included, and gross and net. |
| `payment-payables.status-changed` | Payables in a payment are now `PAID`, or blocked in `ERROR`. |
| `payment.deposit-returned` | The worker's bank returned the deposit. The worker is asked to fix their details. |
| `payment.deposit-retried` | Everee retried the deposit under the same payment ID. |

### Changing or removing pay

You can change or remove an amount until its payment is approved. Requesting payout doesn't lock it.

| To... | Do this |
| --- | --- |
| Change or remove an amount before its payment is approved | Send it again with the same `externalId`, update it, or delete it |
| Change or remove an amount whose payment is approved | Add `correction-authorized=true`. Without it the request is rejected with `400` |
| Change hours that were paid | Use the Timesheets endpoints with `correction-authorized=true` |

| Outcome | What happens |
| --- | --- |
| Overpayment | Everee records a deduction that withholds the overpaid amount from the next payment |
| Underpayment | The worker is paid the difference. `correctionPaymentTimeframe` sets when: `NEXT_PAYROLL_PAYMENT` (default), `IMMEDIATELY` or `EXTERNALLY_PAID` |

The corrected hours appear on the pay stub as a Prior Period Correction. A shift's times can't move more than 48 hours in one update.

**Common mistakes.** Paying hourly employees with payables. A random `externalId`. Forgetting the payout request for contractors. Not setting `workLocationId`. Polling instead of using `payment.paid`. Sending a worker's classified hours in more than one call.

Endpoint map: sending pay and fast pay

| Method | Endpoint | What it does | Docs |
| --- | --- | --- | --- |
| POST | `/integration/v1/labor/timesheet/worked-shifts` | Create a shift | [Reference](https://developer.everee.com/reference/add-a-shift-to-an-employees-time-card) |
| POST | `/integration/v1/labor/classified-hours/bulk` | Send classified hours for a period | [Reference](https://developer.everee.com/reference/update-classified-hours-for-pay-period-bulk) |
| POST | `/integration/v1/payables` | Create or update a payable | [Reference](https://developer.everee.com/reference/createpayable) |
| POST | `/integration/v1/payables/bulk` | Create payables in bulk | [Reference](https://developer.everee.com/reference/createpayablesbulk) |
| POST | `/integration/v1/payables/payment-request` | Request payout | [Reference](https://developer.everee.com/reference/createpayablepaymentrequest) |
| GET | `/integration/v1/payables/{externalId}` | Get a payable | [Reference](https://developer.everee.com/reference/getpayable) |
| GET | `/integration/v1/earnings-on-demand/status` | Early Pay status | [Reference](https://developer.everee.com/reference/get-earnings-on-demand-status) |
| POST | `/integration/v1/earnings-on-demand/custom-amount` | Request Early Pay | [Reference](https://developer.everee.com/reference/request-earnings-on-demand) |
| PUT | `/integration/v1/real-time-payroll/enrollment` | Update Real Time Payroll enrollment | [Reference](https://developer.everee.com/reference/update-real-time-payroll-enrollment) |

Area 6

## Retrieve financial data Available

Payment data, cost segments, the payroll journal with GL codes, and reports.

After payroll runs, Everee gives you three views of the same payments plus on-demand reports. They aren't meant to match one for one: the journal groups by funding date, the segments by earning or pay date, the payment data by pay date. Use the journal for the books and the segments for analysis.

### Prompt for your coding agent

Copy this into your coding agent, or point the agent at this page and it can read the prompt directly. It names the docs to read first, the operations to call, the rules that matter for this area, and the tests to write. [Open as Markdown](https://files.everee.com/prompts/reporting.md)

**Agent prompt: Area 6: Retrieve financial data**

```
GOAL
Build financial reporting for the company's finance users: payments, payroll cost, a balanced payroll journal ready to post to a general ledger, and file-based reports.

READ FIRST (each page also has a Markdown version at the same URL with .md added; the docs index is https://developer.everee.com/llms.txt)
- https://developer.everee.com/reference/get-payment-data
- https://developer.everee.com/reference/list-payroll-journal-fundings
- https://developer.everee.com/reference/get-payroll-journal-for-funding
- https://developer.everee.com/reference/upsert-gl-mappings
- https://developer.everee.com/reference/reports-api-guide
- https://developer.everee.com/reference/retrieve-report-run
- https://developer.everee.com/reference/get-payroll-cost-segments-by-period

BUILD
- A journal screen: list fundings (GET /payroll-costs/journal/fundings), open one (/fundings/{id}) to show balanced debit and credit lines by category, type, GL code and account, and a GL-mapping editor (GET/PUT /payroll-costs/journal/gl-mappings and /options).
- Cost views from /payroll-costs/segments/by-period and /by-cost-centers, payment data from GET /payment-data, a worker pay history, and deduction reconciliation.
- A reports screen: request a report run (POST /reports/{report-type}), wait for the report.completed webhook, then retrieve the run for a download link. Also list worker files and company tax files.

OPERATIONS (all paths are under https://api.everee.com/integration/v1; each reference page, with .md added, lists its request and response fields)
- GET /payment-data | operationId get_payment_data | https://developer.everee.com/reference/get-payment-data.md
- GET /payroll-costs/segments/by-period | operationId get_payroll_cost_segments_by_period | https://developer.everee.com/reference/get-payroll-cost-segments-by-period.md
- GET /payroll-costs/segments/by-cost-centers | operationId get_payroll_cost_segments_by_cost_centers | https://developer.everee.com/reference/get-payroll-cost-segments-by-cost-centers.md
- GET /payroll-costs/journal/fundings | operationId list_payroll_journal_fundings | https://developer.everee.com/reference/list-payroll-journal-fundings.md
- GET /payroll-costs/journal/fundings/{fundingId} | operationId get_payroll_journal_for_funding | https://developer.everee.com/reference/get-payroll-journal-for-funding.md
- PUT /payroll-costs/journal/gl-mappings | operationId upsert_payroll_journal_gl_mappings | https://developer.everee.com/reference/upsert-gl-mappings.md
- GET /payroll-costs/journal/gl-mappings | operationId list_payroll_journal_gl_mappings | https://developer.everee.com/reference/list-gl-mappings.md
- GET /payroll-costs/journal/gl-mappings/options | operationId list_payroll_journal_gl_mapping_options | https://developer.everee.com/reference/list-gl-mapping-options.md
- POST /reports/{report-type} | operationId create-report-run-{report-type} | https://developer.everee.com/reference/reports-api-guide.md
- GET /reports/{id} | operationId retrieve-report-run | https://developer.everee.com/reference/retrieve-report-run.md
- GET /deductions/reconciliation | operationId get_deduction_reconciliation | https://developer.everee.com/reference/get-deduction-reconciliation.md
- GET /workers/{id}/payment-history | operationId retrieve-a-workers-pay-history | https://developer.everee.com/reference/retrieve-a-workers-pay-history.md
- GET /workers/files | operationId list-files | https://developer.everee.com/reference/list-files.md
- GET /company-files/tax/{taxYear} | operationId list-company-tax-files | https://developer.everee.com/reference/list-company-tax-files.md

RULES
- Journal lines must balance. If they don't, show the discrepancy instead of posting it.
- Report download links expire. Retrieve the run again for a fresh link instead of storing the link.
- Don't recompute payroll cost. Show Everee's numbers and let finance users export them.
- Base URL https://api.everee.com/integration/v1. The partner key (psk_...) is the HTTP Basic user name for the Company Onboarding API. The company key (tsk_...) is the HTTP Basic user name for everything else, plus an x-everee-tenant-id header holding the company's id.
- Keep every key on the server. Everee rejects browser requests. Read keys from a secrets store, never log them, never hard-code them.
- Rate limit: 100 operations per 5 seconds per key (see the RateLimit-Policy header). Back off on 429.
- Only payables have an idempotency key (externalId). Make other creates safe yourself: look first, keep the Everee ID next to your own record.
- Test against a sandbox instance (tsk_test_... keys) before production. Nothing in a URL selects the environment; the key does.

DONE WHEN
- A sandbox funding's journal renders balanced and can be exported or posted with my GL mapping.
- A requested report completes via webhook and downloads with a fresh link.

TESTS TO WRITE
- A journal's debits equal its credits, otherwise the screen shows the difference instead of posting it.
- An expired report link is refreshed by retrieving the run again.
- The report.completed webhook triggers the retrieval, and a duplicate event doesn't download twice.
- A GL mapping saved with PUT reads back identically with GET.
- Cost and payment totals on screen equal the API's numbers.

If a fact you need isn't in the docs, ask me. Don't guess endpoint paths, field names or business rules.
```

### Three views of the same payments

| You want to... | Use | Organized by |
| --- | --- | --- |
| Post payroll to your general ledger | [Payroll journal](https://developer.everee.com/reference/payroll-journal-guide) | Funding, as balanced debits and credits with your GL codes |
| Bill clients or report cost by job | [Cost segments](https://developer.everee.com/reference/payroll-cost-api-guide) | Cost center, fully loaded with taxes and benefit costs |
| Check individual payments | [Payment data](https://developer.everee.com/reference/payment-data-api-guide) | Payment, one per worker per pay period, every line itemized |

### Post each funding to your GL

A **funding** is the transfer of money that covers one or more payments. Each funding's journal balances on its own: `totalDebits` equals `totalCredits`. Run the loop daily, or when `payment.paid` arrives.

**List October fundings**

```
curl -X GET "https://api.everee.com/integration/v1/payroll-costs/journal/fundings?start-date=2026-10-01&end-date=2026-10-31" \
  -u "$COMPANY_KEY:" -H "x-everee-tenant-id: $COMPANY_ID"
```

- The date range filters on **funding date**, not pay date. Fundings page with a cursor; treat `fundingId` and cursors as opaque.
- A submitted funding can still fail, so post only `FUNDED` if you want certainty.
- Pass `group-by` to split lines by fewer fields. The journal balances either way.

[Guide to the payroll journal](https://developer.everee.com/reference/payroll-journal-guide) · [Guide: reconciling payroll and the GL](https://developer.everee.com/docs/reconciling-payroll-and-gl)

### Give every line its GL code

A mapping works at three levels of detail: category, type and detail. The most specific match wins. Sending your whole set on every sync is safe.

**A mapping for the exact type and detail**For example `FIELD_HOURS` with the detail "Night Field Hours".

**Otherwise, a mapping for the type**All `FIELD_HOURS` lines, whatever the detail.

**Otherwise, the category's default**Every gross pay line without a more specific mapping. If nothing matches, the GL code is `null`: post it to a suspense account, don't skip it.

**Map wages, field hours and taxes**

```
curl -X PUT "https://api.everee.com/integration/v1/payroll-costs/journal/gl-mappings" \
  -u "$COMPANY_KEY:" -H "x-everee-tenant-id: $COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '[
  { "category": "GrossPay", "glCode": "6000" },
  { "category": "GrossPay", "transactionType": "FIELD_HOURS", "glCode": "6010" },
  { "category": "EmployerTaxes", "glCode": "6200" },
  { "category": "Withholdings", "glCode": "2100" },
  { "category": "Liabilities", "glCode": "2110" },
  { "category": "PayrollFunding", "glCode": "1000" }
]'
```

If approval groups or work locations need different codes, scope your mappings by one of them. A scoped group's own mappings are checked first, even over a more specific master mapping. [Guide to GL mappings](https://developer.everee.com/reference/gl-mappings-guide)

### Reports, asynchronously

Each report has its own endpoint. Most take a date range or a year and quarter. Some take none: send an empty object. Reports are Excel files. Payroll Review refuses to run while payments are calculating (`412` with `Retry-After`).

All 20 reports

**Payroll Review**`POST /reports/payroll-review`[Reference](https://developer.everee.com/reference/create-report-run-payroll-review)

**Payments by Pay Period**`POST /reports/payments-by-pay-period`[Reference](https://developer.everee.com/reference/create-report-run-payments-by-pay-period)

**Payments by Pay Date**`POST /reports/payments-by-pay-date`[Reference](https://developer.everee.com/reference/create-report-run-payments-by-pay-date)

**Funding**`POST /reports/funding`[Reference](https://developer.everee.com/reference/create-report-run-funding)

**Pay Correction by Earning Period**`POST /reports/pay-correction-by-earning-period`[Reference](https://developer.everee.com/reference/create-report-run-pay-correction-by-earning-period)

**Pay Correction by Corrected Period**`POST /reports/pay-correction-by-corrected-period`[Reference](https://developer.everee.com/reference/create-report-run-pay-correction-by-corrected-period)

**Pay Correction Outstanding Repayment**`POST /reports/pay-correction-outstanding-repayment`[Reference](https://developer.everee.com/reference/create-report-run-pay-correction-outstanding-repayment)

**Benefits and Deductions**`POST /reports/benefits-and-deductions`[Reference](https://developer.everee.com/reference/create-report-run-benefits-and-deductions)

**Garnishment Withholding**`POST /reports/garnishment-withholding`[Reference](https://developer.everee.com/reference/create-report-run-garnishment-withholding)

**Negative Balances**`POST /reports/negative-balances`[Reference](https://developer.everee.com/reference/create-report-run-negative-balances)

**Workers' Comp**`POST /reports/workers-comp`[Reference](https://developer.everee.com/reference/create-report-run-workers-comp)

**Outstanding Paid Leave Liability**`POST /reports/outstanding-paid-leave-liability`[Reference](https://developer.everee.com/reference/create-report-run-outstanding-paid-leave-liability)

**W-2 Details**`POST /reports/w2-details`[Reference](https://developer.everee.com/reference/create-report-run-w2-details)

**1099 Details**`POST /reports/1099-details`[Reference](https://developer.everee.com/reference/create-report-run-1099-details)

**940 Details**`POST /reports/940-details`[Reference](https://developer.everee.com/reference/create-report-run-940-details)

**941 Details**`POST /reports/941-details`[Reference](https://developer.everee.com/reference/create-report-run-941-details)

**W-4 Elections**`POST /reports/w4-elections`[Reference](https://developer.everee.com/reference/create-report-run-w4-elections)

**Worker Census**`POST /reports/worker-census`[Reference](https://developer.everee.com/reference/create-report-run-worker-census)

**Employee Navigator Demographic**`POST /reports/employee-navigator-demographic`[Reference](https://developer.everee.com/reference/create-report-run-employee-navigator-demographic)

**Employee Navigator Deduction**`POST /reports/employee-navigator-deduction`[Reference](https://developer.everee.com/reference/create-report-run-employee-navigator-deduction)

[Guide to the Reports API](https://developer.everee.com/reference/reports-api-guide)

### Cost segments and payment data

**Cost for a pay period, by cost center**

```
curl -X GET "https://api.everee.com/integration/v1/payroll-costs/segments/by-period?min-earning-date=2026-10-05&max-earning-date=2026-10-11" \
  -u "$COMPANY_KEY:" -H "x-everee-tenant-id: $COMPANY_ID"
```

**Every payment in a pay period**

```
curl -X GET "https://api.everee.com/integration/v1/payment-data?pay-period-start-date=2026-10-05&pay-period-end-date=2026-10-11" \
  -u "$COMPANY_KEY:" -H "x-everee-tenant-id: $COMPANY_ID"
```

Retrieve once a pay date has finished processing, and page in one pass. Send either `pay-date` or both pay period dates. [Payment Data API](https://developer.everee.com/reference/payment-data-api-guide) · [Payroll Cost API](https://developer.everee.com/reference/payroll-cost-api-guide)

### Documents

| Document | Where |
| --- | --- |
| Worker pay history and pay statements | [Worker Payment History API](https://developer.everee.com/reference/retrieve-a-workers-pay-history) |
| Worker tax files such as W-2 and 1099 | [List worker files](https://developer.everee.com/reference/list-files) |
| Company tax files for a tax year | [List company tax files](https://developer.everee.com/reference/list-company-tax-files) |
| Detail behind Forms 940 and 941 | [Reports API](https://developer.everee.com/reference/reports-api-guide) |

### A month-end routine

**Each pay date, after `payment.paid`**List fundings and post the new `FUNDED` ones to your GL.

**Each pay period**Pull the cost segments and turn each client's segment into an invoice line. Include the unallocated segment or totals won't tie out.

**When a total doesn't match**Open the payment data for that pay date and find the payments behind it.

**After changing a GL mapping**Re-retrieve the journals of affected fundings. Mapping changes apply to past journals too.

Endpoint map: financial data

| Method | Endpoint | What it does | Docs |
| --- | --- | --- | --- |
| GET | `/integration/v1/payment-data` | Payments by pay date or pay period | [Reference](https://developer.everee.com/reference/get-payment-data) |
| GET | `/integration/v1/payroll-costs/segments/by-period` | Cost segments by period | [Reference](https://developer.everee.com/reference/get-payroll-cost-segments-by-period) |
| GET | `/integration/v1/payroll-costs/segments/by-cost-centers` | Cost segments by cost center | [Reference](https://developer.everee.com/reference/get-payroll-cost-segments-by-cost-centers) |
| GET | `/integration/v1/payroll-costs/journal/fundings` | List fundings | [Reference](https://developer.everee.com/reference/list-payroll-journal-fundings) |
| GET | `/integration/v1/payroll-costs/journal/fundings/{fundingId}` | Get a funding's journal | [Reference](https://developer.everee.com/reference/get-payroll-journal-for-funding) |
| PUT | `/integration/v1/payroll-costs/journal/gl-mappings` | Create or update GL mappings | [Reference](https://developer.everee.com/reference/upsert-gl-mappings) |
| GET | `/integration/v1/payroll-costs/journal/gl-mappings` | List GL mappings | [Reference](https://developer.everee.com/reference/list-gl-mappings) |
| GET | `/integration/v1/payroll-costs/journal/gl-mappings/options` | Suggested transaction types | [Reference](https://developer.everee.com/reference/list-gl-mapping-options) |
| POST | `/integration/v1/reports/{report-type}` | Request a report run | [Reference](https://developer.everee.com/reference/reports-api-guide) |
| GET | `/integration/v1/reports/{id}` | Retrieve a report run | [Reference](https://developer.everee.com/reference/retrieve-report-run) |
| GET | `/integration/v1/deductions/reconciliation` | Deduction reconciliation | [Reference](https://developer.everee.com/reference/get-deduction-reconciliation) |
| GET | `/integration/v1/workers/{id}/payment-history` | Worker pay history | [Reference](https://developer.everee.com/reference/retrieve-a-workers-pay-history) |
| GET | `/integration/v1/workers/files` | List worker files | [Reference](https://developer.everee.com/reference/list-files) |
| GET | `/integration/v1/company-files/tax/{taxYear}` | List company tax files | [Reference](https://developer.everee.com/reference/list-company-tax-files) |

Core concepts

## Ideas that apply to every area

Keys, sandbox instances, embedded components, multiple EINs, webhooks, errors and limits, and effective dates.

### Prompt for your coding agent

Copy this into your coding agent, or point the agent at this page and it can read the prompt directly. It names the docs to read first, the operations to call, the rules that matter for this area, and the tests to write. [Open as Markdown](https://files.everee.com/prompts/foundation.md)

**Agent prompt: Foundation: client, keys and webhooks**

```
GOAL
Build the shared foundation every Everee area depends on: a server-side API client, secrets handling, a webhook receiver, and an error and retry policy.

READ FIRST (each page also has a Markdown version at the same URL with .md added; the docs index is https://developer.everee.com/llms.txt)
- https://developer.everee.com/docs/authentication-api-tokens
- https://developer.everee.com/docs/rate-limits
- https://developer.everee.com/docs/requests-responses
- https://developer.everee.com/docs/events-overview
- https://developer.everee.com/docs/authenticating-events
- https://developer.everee.com/docs/securing-your-handler
- https://developer.everee.com/docs/sandbox-and-production
- https://developer.everee.com/docs/multiple-ein-company-instances

BUILD
- One API client with two credentials: partner key (psk_...) for the Company Onboarding API, and a per-company key (tsk_...) with the x-everee-tenant-id header for everything else. Store a key and company id per company (one per EIN).
- A webhook receiver: read the raw body, verify the HMAC-SHA256 signature of timestamp + '.' + raw body against the x-everee-webhook-signature header (it may carry several v1= signatures during a key rotation: accept any), check the timestamp, return 2xx quickly and process asynchronously.
- Store each delivery's id and ignore repeats. Events can arrive more than once and out of order, so treat an event as a nudge and read current state from the API.
- Manage endpoints and keys through the API: Webhook Endpoints API (up to three endpoints per company, rotate signing key, send test event) and Company API keys (rotate, expire; shown once).
- Error handling: surface 4xx messages to the user, retry 5xx and 429 with backoff, and log the X-Request-ID response header with every failure so Everee support can trace it.

OPERATIONS (all paths are under https://api.everee.com/integration/v1; each reference page, with .md added, lists its request and response fields)
- GET /webhook-endpoints | operationId list-webhook-endpoints | https://developer.everee.com/reference/list-webhook-endpoints.md
- POST /webhook-endpoints | operationId create-webhook-endpoint | https://developer.everee.com/reference/create-webhook-endpoint.md
- PUT /webhook-endpoints/{id} | operationId update-webhook-endpoint | https://developer.everee.com/reference/update-webhook-endpoint.md
- DELETE /webhook-endpoints/{id} | operationId delete-webhook-endpoint | https://developer.everee.com/reference/delete-webhook-endpoint.md
- POST /webhook-endpoints/{id}/rotate-signing-key | operationId rotate-webhook-endpoint-signing-key | https://developer.everee.com/reference/rotate-webhook-endpoint-signing-key.md
- POST /webhook-endpoints/{id}/test | operationId send-test-webhook-event | https://developer.everee.com/reference/send-test-webhook-event.md
- GET /partner/companies/{companyId}/api-keys | operationId list-partner-company-api-keys | https://developer.everee.com/reference/list-partner-company-api-keys.md
- POST /partner/companies/{companyId}/api-keys | operationId create-partner-company-api-key | https://developer.everee.com/reference/create-partner-company-api-key.md
- POST /partner/companies/{companyId}/api-keys/{keyId}/rotate | operationId rotate-partner-company-api-key | https://developer.everee.com/reference/rotate-partner-company-api-key.md
- PUT /partner/companies/{companyId}/api-keys/{keyId}/expiration | operationId set-partner-company-api-key-expiration | https://developer.everee.com/reference/set-partner-company-api-key-expiration.md
- DELETE /partner/companies/{companyId}/api-keys/{keyId}/expiration | operationId cancel-partner-company-api-key-expiration | https://developer.everee.com/reference/cancel-partner-company-api-key-expiration.md

RULES
- Base URL https://api.everee.com/integration/v1. The partner key (psk_...) is the HTTP Basic user name for the Company Onboarding API. The company key (tsk_...) is the HTTP Basic user name for everything else, plus an x-everee-tenant-id header holding the company's id.
- Keep every key on the server. Everee rejects browser requests. Read keys from a secrets store, never log them, never hard-code them.
- Rate limit: 100 operations per 5 seconds per key (see the RateLimit-Policy header). Back off on 429.
- Only payables have an idempotency key (externalId). Make other creates safe yourself: look first, keep the Everee ID next to your own record.
- Test against a sandbox instance (tsk_test_... keys) before production. Nothing in a URL selects the environment; the key does.

DONE WHEN
- A signed test event from 'Send a test event' is accepted, and the same body with a tampered byte is rejected.
- A sandbox call with the company key and tenant header succeeds, and a call from a browser is not possible.

TESTS TO WRITE
- A signed test event from 'Send a test event' is accepted, and the same body with one byte changed is rejected.
- A delivery whose header carries two v1 signatures (during a key rotation) is accepted when either matches.
- The same event id delivered twice is processed once.
- A 429 or 5xx is retried with backoff, and a 4xx message reaches the user.
- No log line, error report or response ever contains a key. Assert it with a redaction test.

If a fact you need isn't in the docs, ask me. Don't guess endpoint paths, field names or business rules.
```

### Who does what

Payroll Infrastructure is managed. You build the experience and Everee runs the payroll and the compliance.

| You build | Everee handles |
| --- | --- |
| Onboarding, worker management and payroll approval screens inside your product | Tax rule updates, tax remittance and filing, and the forms (941, 940, W-2, 1099) |
| The hours and pay items you send each cycle | Gross-to-net pay, garnishment and retirement remittance, and paying workers |
| Reporting and ledger posting for your customers | New hire and termination reporting, and payroll support workflows for your customers |

### Keys

Keep every key on your servers. Everee rejects requests made from browsers.

|  | Partner key | Company key | Webhook signing key |
| --- | --- | --- | --- |
| Looks like | `psk_prod_…` or `psk_test_…` | `tsk_prod_…` or `tsk_test_…` | Per endpoint |
| Comes from | Claimed by your technical contact; Everee never sees it | Returned once when you create the company. Your partner key can then list, add, rotate and expire the company's keys, and each new key is shown once. Your sandbox instances have `tsk_test_…` keys. | Shown once when you create an endpoint or rotate its key, masked after that |
| Used for | The Company Onboarding API | Everything inside an approved company | Verifying webhook deliveries |
| How it's sent | HTTP Basic, key as user name | HTTP Basic, plus the `x-everee-tenant-id` header on every request | HMAC-SHA256 of timestamp + body |
| Tenant ID | Not used | The company's `id` from the create response | Not used |

#### A key and its key ID

|  | API key | API key ID |
| --- | --- | --- |
| What it is | The secret credential, such as `tsk_prod_…` | A public identifier for one key. It is the `id` on each key record that Everee returns, and the `keyId` you use to rotate or expire that key. |
| What it's for | Authenticates requests. Send it as an HTTP Basic credential. | Refers to one specific key without exposing it. Filter the Request Log API by `api-key-id` to see everything that key has done, or tell Everee support which key you mean. |
| Is it secret? | Yes. Keep it on your servers and never log it. | No. It is safe to store and log. |
| Can it authenticate? | Yes | Never |
| Shown | Once, when the key is created. It can't be shown again. | Returned with the key, and again when you list the company's keys (redacted). |

#### Managing a company's keys

Your partner key manages the keys of the companies you created. List them (redacted, whoever made them), add another for a separate integration, rotate one, or schedule one to stop. Rotate and expiry take `expireInHours` from 0 to 24, and the old key keeps working during that window so you can switch without an outage. An expired key returns `401`. [Company API keys](https://developer.everee.com/reference/company-api-keys-guide)

[Getting your partner API key](https://developer.everee.com/docs/getting-your-partner-api-key) · [Authentication & API tokens](https://developer.everee.com/docs/authentication-api-tokens)

### Sandbox instances for partners

Partners get sandbox instances as a development and testing tool, and keep them for ongoing testing. Company customers don't get sandbox instances in Payroll Infrastructure. Nothing in a URL selects the environment: the key and tenant ID you send decide which instance a request acts on, so check the tenant ID before you test and the `companyId` on every webhook.

|  | Sandbox instance (for you) | Production company |
| --- | --- | --- |
| Who gets one | You, for development and ongoing testing | Each customer company you onboard |
| Keys | `tsk_test_…` | `tsk_prod_…` |
| API domain | `https://api.everee.com` | `https://api.everee.com` |
| Tenant ID, key, webhooks, signing keys, data | Its own | Its own |
| Money | No real money moves | Real money moves |

In a sandbox instance, the bank step of contract signing uses Plaid's sandbox: choose the test institution and sign in with `user_good` and `pass_good`.

### Embedded components

Every company-level action happens in your product, driving Everee's API. Everee's own screens appear only as embedded experiences, and nobody signs in to Everee.

| Component | When | What it is |
| --- | --- | --- |
| `COMPANY_CONTRACT` | During onboarding | The company's signer reviews the agreements, connects the funding bank account and signs. Create it with the contract signing session. [Signing the agreements](https://developer.everee.com/docs/signing-the-agreements) |
| `FUNDING_BANK_ACCOUNT` | After onboarding | The company connects the bank account Everee debits to fund payroll, so you never handle its bank credentials. Create a session with `experience` set to `FUNDING_BANK_ACCOUNT` and no worker ID. Coming soon [Funding bank account](https://developer.everee.com/docs/embedding-funding-bank-account) |

[Component events](https://developer.everee.com/docs/handling-events) · [How to embed](https://developer.everee.com/docs/how-to-embed-components-guide)

### Multiple EINs

Each legal entity runs in its own company instance, with its own API key and tenant ID. Store a key and an ID per EIN and pick the right pair per request. Link your own worker and wage records to the EIN. [Company instances and multiple EINs](https://developer.everee.com/docs/multiple-ein-company-instances)

### Webhooks

| Event | When it fires |
| --- | --- |
| Company onboarding |  |
| `company-onboarding.status-changed` | The status changed: submitted, approved, declined or withdrawn. |
| `company-onboarding.signature-requested` | The signer can sign. Create a signing session. |
| `company-onboarding.contract-signed` | The signer signed the agreements. |
| `company-onboarding.contract-executed` | Everee countersigned. The executed documents are ready. |
| `company-onboarding.contract-voided` | A signature was voided because documented data changed. A new request follows. |
| `company-onboarding.request-created` | Everee needs something from you during review. |
| `company-onboarding.request-resolved` | A request was answered or no longer needed. |
| `company-onboarding.identity-verification-changed` | A person's identity check changed status. |
| Workers |  |
| `worker.created` | A worker profile exists. Store the Everee `workerId`. |
| `worker.profile-updated` | Something on the profile changed. Retrieve the worker and re-sync. |
| `worker.deleted` | A worker profile was deleted. |
| `worker.onboarding-completed` | The worker finished onboarding and can be paid. |
| `worker.updated-payment-method` | The worker's preferred payment method changed (direct deposit or pay card). |
| `worker.new-tax-forms-available` | The worker was paid in a new tax jurisdiction. New forms use default values. |
| `worker.tin-verification-status-changed` | The taxpayer identifier did or didn't match IRS or SSA records. |
| Payments |  |
| `payment.paid` | A payment was submitted for deposit. |
| `payment-payables.status-changed` | Payables in a payment are now `PAID`, or blocked in `ERROR`. |
| `payment.deposit-returned` | The worker's bank returned the deposit. |
| `payment.deposit-retried` | Everee retried the deposit under the same payment ID. |
| Reports |  |
| `report.completed` | A report you requested is ready to retrieve. |
| `report.errored` | The report couldn't be generated. `errorMessage` says why. |

Each company can have up to three webhook endpoints, managed with the company key through the [Webhook Endpoints API](https://developer.everee.com/reference/webhook-endpoints-api-guide): list, add, change, switch one off, delete, and send a test event. Set the first at company creation with `webhookUrl`. Every event goes to every enabled endpoint. A signing key is shown once, when you create an endpoint or rotate its key. To [rotate it](https://developer.everee.com/reference/rotate-webhook-endpoint-signing-key), make one call: for the next 24 hours each delivery carries two signatures, `v1=<new>,v1=<old>`, so your handler can switch without missing an event. Rotating again inside those 24 hours ends the oldest key at once. [Send a test event](https://developer.everee.com/reference/send-test-webhook-event) to check a handler. Everee retries a failed delivery up to 20 times over about 6.6 days. Reading delivery attempts through the API is coming soon. Make handlers idempotent: events can arrive more than once and out of order.

[Events overview](https://developer.everee.com/docs/events-overview) · [Securing a handler](https://developer.everee.com/docs/securing-your-handler) · [Authenticating events](https://developer.everee.com/docs/authenticating-events)

**verify-webhook.js**

```
import crypto from "node:crypto";

export function verifyEveree(rawBody, headers, signingKey) {
  const timestamp = headers["x-everee-webhook-timestamp"];
  const expected = crypto.createHmac("sha256", signingKey)
    .update(timestamp + "." + rawBody).digest("hex");
  // During a key rotation the header holds two v1 signatures: accept either.
  return headers["x-everee-webhook-signature"]
    .split(",").map((p) => p.split("="))
    .filter(([v]) => v === "v1")
    .some(([, sig]) => sig.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)));
}
```

### Requests, errors and limits

| Status | Meaning |
| --- | --- |
| `400`, `422` | A field or the request's state is invalid. Fix it using `errorMessage`. |
| `401`, `403` | The credentials can't perform the operation. An expired key returns `401`. |
| `404` | Something referenced doesn't exist. |
| `409` | A conflict with the resource's current state. |
| `412` | A report was requested while payments are calculating. Honor `Retry-After`. |
| `429` | Rate limit: 100 operations per 5-second window per token by default (the `RateLimit-Policy` header shows the policy that applied). Back off exponentially with jitter. |
| `5xx` | Everee's side. Retry with backoff and send support the `X-Request-ID`. |

Send `content-type` and `accept` as `application/json`. Errors return `errorCode`, `errorMessage`, `errorCause` and `path`.

**Idempotency.** Only payables take an idempotency key today: their `externalId` makes a retry safe. Other creates, such as shifts, workers and companies, have none, so after a timeout check what exists before you retry. For workers, look up hiring status first.

**Diagnose a failed call.** The Request Log API keeps your recent calls to `/integration/v1` for 30 days, with the request body and error response, and masks sensitive values. Look one up by the request ID.

[Requests and responses](https://developer.everee.com/docs/requests-responses) · [Rate limits](https://developer.everee.com/docs/rate-limits) · [Pagination](https://developer.everee.com/docs/pagination) · [Diagnosing a failed request](https://developer.everee.com/docs/diagnosing-failed-requests)

### Effective dates

Changes that affect pay take effect on a date, so past payrolls are never rewritten: a home address (use the next day in the worker's time zone), a new payroll calendar (tomorrow or later), deductions and leave enrollments (start tomorrow), and scheduled position changes. Corrections to paid pay are explicit and use `correction-authorized=true`.

Agent kit

## Everything an agent needs to build

Machine-readable copies of this guide, the questions to answer before building, the data to store, and a sandbox script that proves the setup.

### Machine-readable copies

Point an agent at the Markdown guide, or at one prompt. Each prompt names the docs to read, the operations to call with their operationIds, the rules, and the tests to write. The OpenAPI specs are `reference/default.json`, `reference/everee-api.json` and `reference/everee-embed.json` in the docs repository.

| Machine-readable copy | URL |
| --- | --- |
| **Whole guide as Markdown** | [https://files.everee.com/everee-payroll-infrastructure-explainer.md](https://files.everee.com/everee-payroll-infrastructure-explainer.md) |
| **Start-here prompt** | [https://files.everee.com/prompts/master.md](https://files.everee.com/prompts/master.md) |
| **Foundation: client, keys and webhooks** | [https://files.everee.com/prompts/foundation.md](https://files.everee.com/prompts/foundation.md) |
| **Area 1: Onboard a company** | [https://files.everee.com/prompts/onboard.md](https://files.everee.com/prompts/onboard.md) |
| **Area 2: Set up the organization** | [https://files.everee.com/prompts/setup.md](https://files.everee.com/prompts/setup.md) |
| **Area 3: Add and maintain workers** | [https://files.everee.com/prompts/workers.md](https://files.everee.com/prompts/workers.md) |
| **Area 4: Worker payroll settings** | [https://files.everee.com/prompts/settings.md](https://files.everee.com/prompts/settings.md) |
| **Area 5: Run payroll** | [https://files.everee.com/prompts/pay.md](https://files.everee.com/prompts/pay.md) |
| **Area 6: Retrieve financial data** | [https://files.everee.com/prompts/reporting.md](https://files.everee.com/prompts/reporting.md) |

### Decisions to make before building

The start-here prompt has the agent ask you these first.

1. Which legal entities (EINs) will run payroll, and do they need separate company instances? Each EIN is its own company with its own key and tenant ID.
2. Who signs the company's agreements, and who is the control person and each owner of 25% or more? (Needed for onboarding and identity verification.)
3. How are workers paid today: employees, contractors, or both? Hourly, salaried, or per-task? Which pay codes do you need beyond the defaults?
4. Which payroll calendar fits each customer (weekly, bi-weekly, semi-monthly, monthly) and when do pay periods start?
5. Which work locations exist, and where does each worker legally work? (The address decides tax jurisdictions.)
6. Which benefits, retirement plans and garnishments do you need to sync, and from which system?
7. Who approves payroll in your product, and what is your internal cutoff before Everee's 10:30am PT cutoff?
8. Where should finance data go: a GL integration, a CSV export, or both? Which GL accounts map to which Everee transaction types?
9. Which framework, job runner, secrets store and webhook ingress do you already have?

### What to store

Keep each Everee ID next to your own record so later requests need no lookup.

| Entity | What Everee gives you | Keep it beside |
| --- | --- | --- |
| **Company** | id (this is also the tenant ID you send in x-everee-tenant-id), company API key (secret, shown once), key IDs, webhook endpoint IDs and signing keys (secret, shown once) | your customer or company record |
| **Partner** | partner API key (secret, one per environment) | your secrets store, not a table |
| **Worker** | workerId (Everee) and externalWorkerId (yours) | your worker or employee record |
| **Work location** | workLocationId, and your own id as externalId | your site or location record |
| **Payroll calendar, approval group** | payrollCalendarId, approvalGroupId | your pay schedule and team records |
| **Cost center, pay code** | cost center key, pay code apiKey | your own client, job or earning type |
| **Payable** | your externalId (the only idempotency key), and the paymentId in payment data | your earning or bonus record |
| **Funding and reports** | fundingId, report run id | your payroll run or ledger batch record |
| **Webhook delivery** | the event id from the envelope | a processed-events table, for de-duplication |

### Sandbox walkthrough

A script that checks a sandbox key, creates a work location and a payroll calendar, lists pay codes, sends an idempotent payable and reads payments and fundings. It refuses to run with a production key.

**sandbox-walkthrough.sh**

```
#!/usr/bin/env bash
# Everee sandbox walkthrough: set up an organization, send pay, read the results.
# Needs a SANDBOX company key (tsk_test_...) and its company id. Never run this with a production key.
set -euo pipefail
: "${COMPANY_KEY:?set COMPANY_KEY to a tsk_test_ key}"
: "${COMPANY_ID:?set COMPANY_ID to the company id}"
case "$COMPANY_KEY" in tsk_test_*) ;; *) echo "Refusing: not a sandbox key" >&2; exit 1;; esac
BASE=https://api.everee.com/integration/v1
call() { # method path [json-body]
  curl -sS -X "$1" "$BASE$2" -u "$COMPANY_KEY:" -H "x-everee-tenant-id: $COMPANY_ID" \
    ${3:+-H "Content-Type: application/json" -d "$3"} -w '\n-- HTTP %{http_code}\n'
}

echo "1. Check the key: list work locations";           call GET /work-locations
echo "2. Create a work location"
call POST /work-locations '{"name":"Salt Lake Office","line1":"100 S Main St","city":"Salt Lake City","state":"UT","postalCode":"84101","effectiveDate":"2026-01-01","externalId":"site-0042"}'
echo "3. Create a payroll calendar"
call POST /payroll-calendar '{"displayName":"Clinic staff","payPeriodType":"BI_WEEKLY","weeklyStartDay":"MONDAY","effectiveDate":"2026-11-02"}'
echo "4. List pay codes (note each apiKey)";            call GET /pay-codes

# Steps 5 to 7 need a worker. Create one with the complete employee record
# (POST /workers/employee, see the add-a-complete-employee-record reference page),
# then set EXTERNAL_WORKER_ID to the externalWorkerId you gave it.
if [ -n "${EXTERNAL_WORKER_ID:-}" ]; then
  echo "5. Send a payable; run this twice to see the externalId make it idempotent"
  call POST /payables "{\"externalId\":\"walkthrough::$EXTERNAL_WORKER_ID::bonus-1\",\"externalWorkerId\":\"$EXTERNAL_WORKER_ID\",\"label\":\"Walkthrough bonus\",\"payableModel\":\"PRE_CALCULATED\",\"payCode\":\"BONUS\",\"type\":\"bonus\",\"amount\":{\"amount\":10.00,\"currency\":\"USD\"},\"earningTimestamp\":$(date -u +%s)}"
  echo "6. Read it back";                               call GET "/payables/walkthrough::$EXTERNAL_WORKER_ID::bonus-1"
fi
echo "7. Read payment data for a pay period";           call GET "/payment-data?pay-period-start-date=2026-10-05&pay-period-end-date=2026-10-11"
echo "8. List fundings (the payroll journal starts here)"; call GET "/payroll-costs/journal/fundings?start-date=2026-10-01&end-date=2026-10-31"
```

FAQ

## Good to know

Quick answers about access, onboarding, taxes, payroll runs and support.

Who builds on Payroll Infrastructure?

Software platforms that want payroll inside their own product. Each customer becomes a company under your partner account.

How do I get access?

Contact Everee. A technical contact on your list claims the partner key, which is created at that moment and shown once. See Getting your partner API key.

Does anyone sign in to Everee?

No. Every company-level action is an API call from your product. Everee's screens appear only as embedded experiences, such as the company contract signing.

What do I need to create a company?

Only the legal business name, the EIN and a primary contact. Everything else is added to the draft, and the status response lists a code for each gap.

Do I send bank details for the company?

No. The company's signer chooses the funding bank account by signing in to their bank during signing.

Does a company need year-to-date payroll?

Yes. Everee requires it. The file format is set for each partner, and it is typically a zip of payroll data from the company's current payroll provider. It isn't parsed on upload and the API doesn't block submission without it, so send it before you submit.

How do I know when a company is approved?

Listen for `company-onboarding.status-changed` and read the onboarding status. Use the company API key once it is `APPROVED`.

What state tax information does Everee need?

Everee collects state tax information and rates from the customer directly, through its own systems and partners that work with the company's administrators. Collecting it is a required step of company onboarding, and the company can't go live without it. Everee processes new-hire reporting once payroll service begins.

Who files payroll taxes?

IRS Form 8655, signed with the agreements, authorizes Everee to act for the company on payroll tax matters. Everee prepares and files the payroll tax filings and year-end documents. Some companies file and remit their own taxes, and the journal accounts for that.

How are garnishments handled?

Everee automatically calculates each garnishment against the applicable limits and handles remittance.

Is Everee SOC 2 compliant?

Yes. Everee is SOC 2 Type II compliant.

Is there a sandbox?

Yes, for you. Partners get sandbox instances for development and ongoing testing, with `tsk_test_…` keys. Company customers don't get sandbox instances in Payroll Infrastructure.

Does Everee review my integration?

Yes. Before a new integration goes live with customers, Everee verifies the complete workflow: company onboarding, company setup, worker creation, worker profile management, payroll processing, and GL and reporting.

When is the Run payroll API available?

Early November. It isn't published yet.

What is the daily approval cutoff?

10:30am PT (1:30pm ET).

When is the company's bank account debited?

On the day needed to reach the pay date of the payroll run. More detail arrives with the Run payroll API in early November.

Are Early Pay and Real Time Payroll available?

Yes. Both are subject to credit approval by Everee.

Who supports my customers?

Everee's Customer Success team provides customer-facing support on your behalf. Transfer all payroll-related issues to Everee Customer Success.

What if I lose a key?

A partner key can't be shown again: ask your Everee contact to rotate it. A company key is shown once, at creation. If it is lost or may have leaked, rotate it or add another with your partner key (Company API keys endpoints). A lost webhook signing key is fixed by rotating it.

What should I send when I contact support?

The `X-Request-ID` from the response, the company ID and the time of the request.

Is there a Markdown version of the docs?

Yes. The index is at [developer.everee.com/llms.txt](https://developer.everee.com/llms.txt), and each page has a Markdown version at the same address with .md added.

**Go deeper.** The full documentation is at developer.everee.com: start with the [Developer Center](https://developer.everee.com/docs/introduction) and [Common Workflows](https://developer.everee.com/docs/workflows-overview), or give your agent the [docs index](https://developer.everee.com/llms.txt). Every section above links to its reference pages. This is a pre-release guide: the Run payroll API will be added when it ships in early November.