Onboarding a Company
Create client companies, collect everything Everee needs to onboard them, and get them signed, all through the API.
The Company Onboarding API lets a platform partner create client companies in Everee and take them through onboarding without sending anyone to Everee's own sign-up flow. You collect the company's information in your own product and send it to Everee through the API. The person who signs for the company reviews and signs Everee's agreements in an embedded experience inside your product. Everee reviews the result and tells you the outcome with webhooks.
These guides are written so that you, or an AI agent working from them, can build the same experience as Everee's own self-signup: a sequence of screens that collects the company's information, hands the signer to an embedded signing step, and finishes with a submission. The most important section is The readiness check: it explains how Everee tells you what is still missing. Collecting company information then says, for every item Everee can ask for, what to ask the user and which call to make.
This API is for partners. To add workers to a company once it's onboarded, see Managing workers.
How it fits together
Your platform Everee
| |
| 1. Create the company ───────────────────▶ | draft company
| ◀── company ID, company API key, |
| webhook signing key |
| |
| 2. Fill in the draft ────────────────────▶ | details, documents, payroll profile,
| (as many calls as you like, in any | control person, owners, signer, taxes
| order; check the status after each) |
| |
| Everee sets the contract terms (pricing) for the company
| |
| ◀── company-onboarding.signature-requested | the draft is complete and
| | the terms are loaded
| 3. Create an embedded signing session ───▶ |
| show it to the company's signer | signer reviews the agreements,
| ◀── company-onboarding.contract-signed | chooses the funding bank account
| | and signs once
| 4. Submit for review ────────────────────▶ | UNDER_REVIEW
| ◀── identity-verification-changed, | identity checks and Everee's review
| request-created |
| 5. Answer any requests ──────────────────▶ |
| ◀── contract-executed | Everee countersigns
| ◀── status-changed (APPROVED / DECLINED) |
- Create the company. You receive its ID and an API key for the company.
- Complete the draft. Everee tells you exactly what is still missing at any point.
- Get the agreements signed in the embedded signing experience.
- Submit for review and respond to Everee.
- Once the company is approved, Everee imports its payroll history and finishes setting it up. Tell Everee the date you want it to go live, and get its payroll history to Everee: see Payroll history and going live. Use its company API key with the rest of the Everee API (for example to add workers and run payroll). You can use it earlier to manage the company's webhook endpoints, and you can add, rotate and retire the company's keys with the Company API keys endpoints.
The call you keep making: the status
Everything in this API is driven by one read: Get onboarding status. Call it after every change you make, when the user returns to your product, and when a webhook arrives. It returns:
| Field | What to do with it |
|---|---|
status | Where the onboarding is: DRAFT, UNDER_REVIEW, APPROVED, DECLINED or WITHDRAWN. See Statuses. |
readiness.missing | The list of codes still unmet. Your screens are driven by this list. See The readiness check. |
readiness.complete | true when nothing is missing. This is when you can submit. |
contract | Where signing is. Absent until Everee has requested a signature. contract.status is AWAITING_SIGNATURE, then SIGNED, then EXECUTED. |
agreement | How your customers agree to pricing and service terms (DIRECT or UMBRELLA). See 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. |
goLive | Whether the company is live yet, and what's outstanding. See Payroll history and going live. |
payrollHistory | Where the company's payroll history stands. |
The status never changes anything. Treat it as the single source of truth for which screen to show next, rather than keeping your own list of steps.
Authentication
Everee gives your platform partner API keys: a test key that begins with zk_test_2 and a production key that begins with zk_prod_2. Each is 57 characters, and is shown once, when your technical contact claims it, so store it like any other secret. Send it the same way you send a company API token to the rest of the Everee API: as an HTTP Basic credential, with the key as the user name and no password.
Authorization: Basic base64(zk_prod_xxxxxxxx…:)The value after Basic is the Base64 encoding of your key. A trailing colon is optional, so base64(zk_prod_…) works too. Do not send the unencoded key after Basic. Most HTTP tools encode it for you: with curl, use -u "$KEY:" (as the examples in these guides do). Treat keys as opaque strings: they are 57 characters today, but don't validate their length or pattern, and leave room to store at least 128 characters.
You can only see and change the companies you created, and each key reaches only its own environment:
| Key | Creates and reaches |
|---|---|
Test key (zk_test_) | Your Sandbox companies (environment is SANDBOX). Their company API keys begin with tsk_test_, no real money moves, and nothing they do is real. |
Production key (zk_prod_) | Your Production companies (environment is PRODUCTION). Everee issues it after it approves your integration. Until then, creating a company with it returns 403. |
A request for a company in the other environment returns 404, as if the company did not exist. You keep your test key after approval, so you can keep creating Sandbox companies to test with. A Sandbox company can't be converted to Production, so create a new company. See Sandbox & Production.
Creating a company also returns a separate company API key (apiKey), which begins with tsk_test_2 for a Sandbox company or tsk_prod_2 for a Production company, and is 58 characters. It is shown only in that response. Keep it with the company's record in your system: after approval it is what you use to call the rest of the Everee API for that company.
Limits on creating companies
Everee limits how many companies you create, so a mistake in your automation can't create thousands.
| Limit | Applies to | Evaluation | Sandbox | What happens |
|---|---|---|---|---|
| Sandbox companies alive at once | Test key | 1 | 25 | Creating another returns 429. Retire a Sandbox company you no longer need to free a slot. |
| Sandbox companies created in any rolling 7 days | Test key | 2 | 50 | Creating another returns 429. Retiring a company does not free this limit, because it counts every company you created, retired or not. The error message says when the next one can be created. |
| Production companies created in any rolling 7 days | Production key | n/a | 100 | Nothing is refused. Everee emails your technical contacts when you reach it. |
When you reach a Sandbox limit, Everee also emails your verified technical contacts once a day, so a script that keeps retrying does not flood them. If you have a reason to create more, contact your Everee contact.
Limits on what a Sandbox company can use
Each Sandbox company is also limited in how much payroll it can run and how many workers it can have. These limits apply to Sandbox companies you create with a test key, and never to Production companies.
| Limit, per Sandbox company | Evaluation | Sandbox | What happens |
|---|---|---|---|
| Off-cycle payroll runs created in any rolling 7 days | 10 | 100 | Creating another returns 429. The error message says when the next one can be created. |
| Payroll run calculations requested in any rolling 24 hours | 20 | 100 | Calculating again returns 429, with the time the next one is allowed. Calculating a run that is already queued doesn't count. While a run is being calculated, the first change that makes it calculate again (adding or removing an item, or excluding a payment) counts as one calculation, and returns 429 if you're at the limit. Further changes before that calculation starts don't count again. |
| Workers, of any kind and status | 25 | 250 | Adding another returns 429. Workers don't expire, so the limit lifts only if the company has fewer workers. |
A request refused by one of these limits changes nothing. If you have a reason to need more, contact your Everee contact.
Evaluation
Before you sign a partnership agreement, Everee can set you up with evaluation access so you can try Payroll Infrastructure against a real Sandbox. Evaluation works like the Sandbox, with the lower limits above, and it ends:
- It lasts 14 days from when Everee sets it up. Your Everee contact can extend it.
- Your test key stops working when it ends. Requests with it are rejected as unauthenticated. Rotating or replacing the key doesn't extend the period.
- Your Sandbox companies are retired shortly after it ends (the data is kept, and their API keys stop working).
- No agreement is needed to create companies. During evaluation your Sandbox companies are created without one, so a company created with an
agreementConsentis refused, and each company is released for onboarding as soon as it is created.
When your agreement is signed, Everee moves you from evaluation to the Sandbox. Your existing test key keeps working and the Sandbox limits apply from then on. See Getting your partner API key.
Requirements can change while a company is in progress
Everee's compliance requirements (which supporting documents are required, and how identity is verified) are versioned, and a company is measured against the version in effect. Treat readiness and the required flag in List documents as the source of truth, not a fixed list.
- Drafts: a requirement that is added or removed shows up in
readiness.missingand inrequirements.documents. - After you submitted: Everee opens a request for a document that is required and missing. Answer it like any other request.
- Approval: Everee approves a company against the requirements in force at the time, so a company under review may need to supply newly required items first.
- You are told: the
company-onboarding.requirements-changedevent lists what is newly required and what no longer is, andjourneyin the status shows which version applies.
Statuses
Every company has an onboarding status.
| Status | Meaning | What you can do |
|---|---|---|
DRAFT | You are collecting information. | Create and change everything. Submit when the readiness check is complete. Withdraw at any time. |
UNDER_REVIEW | Submitted. Everee is verifying identities and reviewing the company. | Respond to requests from Everee. Other data is locked. |
APPROVED | Everee approved the company and has countersigned the agreements. | Use the company API key to call the rest of the Everee API. |
DECLINED | Everee declined the company. decision.reasonCode has a generic reason. | Nothing. Contact your Everee representative. |
WITHDRAWN | You withdrew the onboarding. | Nothing. |
Read the current status, and what is missing, with Get onboarding status. You also receive a company-onboarding.status-changed webhook whenever it changes.
The readiness check
readiness.missing lists a code for each gap. A code leaves the list when you make the call described below. Some codes only appear when they apply: for example CONTRACTOR_COUNT only appears once you say the company pays contractors, and CERTIFICATE_OF_AUTHORITY only when the signer is not an owner. Two rules make this easy to build against:
- Drive your screens from the list, not from a fixed sequence. Everee can change what it requires (for example which documents are required), and codes appear and disappear as the company's answers change.
- Order is up to you, but dependencies exist. The recommended order below is the order Everee's own self-signup uses. Where one answer changes another code (the signer and the control person, say), the step says so.
The recommended screen sequence
| # | Screen | Codes it satisfies | Call |
|---|---|---|---|
| 1 | Create the company | (none) | Create company |
| 2 | Business details | LEGAL_ENTITY_TYPE, FORMATION_STATE, BUSINESS_ADDRESS | Update company |
| 3 | Supporting documents | IRS_EIN_LETTER, BUSINESS_FORMATION | Upload a 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 |
| 5 | People: control person, owners, signer | CONTROL_PERSON, OWNERSHIP_DECLARATION, OWNERSHIP_TOTAL, SIGNER, SIGNER_IDENTITY, SIGNER_RELATIONSHIP | Control person, owners, ownership declaration, signer |
| 6 | Customer's agreement (only some partners) | AGREEMENT_CONSENT | Report agreement consent |
| 7 | Taxes | TAX_STATES | Update tax setup |
| 8 | Sign and choose the bank account | SIGNED_CONTRACT, BANK_ACCOUNT | Create a signing session |
| 9 | After signing: authority and IDs | CERTIFICATE_OF_AUTHORITY, PICTURE_ID | Certificate of authority, Upload a document |
| 10 | Review and submit | (completes the check) | Submit |
Each step has its own section in Collecting company information, with the fields, an example request, and the rules for when a code appears. The signature is requested as soon as everything in steps 2 to 7 is in and Everee has loaded the company's contract terms. Steps 8 and 9 happen afterwards, so SIGNED_CONTRACT, BANK_ACCOUNT, CERTIFICATE_OF_AUTHORITY and PICTURE_ID are expected to still be in readiness.missing while the user is on the earlier screens.
After you submit
Everee verifies each person's identity, may send you requests for more, and tells you the outcome. See Submitting for review.
Conventions
- Requests and responses are JSON, except file uploads, which are
multipart/form-datawith afilepart. PATCHendpoints change only the fields you send.PUTendpoints replace the resource.- Validation problems return
400or422with a message that names the field. A request that is not allowed in the company's current state (for example, changing data that has been signed, or submitting before the draft is complete) returns409or422with an explanation. - Everything in the draft is editable until the agreements are signed. Signing locks the information that appears on the documents; see Changing data after signing.
Where to next
Updated 1 day ago