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)   |
  1. Create the company. You receive its ID and an API key for the company.
  2. Complete the draft. Everee tells you exactly what is still missing at any point.
  3. Get the agreements signed in the embedded signing experience.
  4. Submit for review and respond to Everee.
  5. 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:

FieldWhat to do with it
statusWhere the onboarding is: DRAFT, UNDER_REVIEW, APPROVED, DECLINED or WITHDRAWN. See Statuses.
readiness.missingThe list of codes still unmet. Your screens are driven by this list. See The readiness check.
readiness.completetrue when nothing is missing. This is when you can submit.
contractWhere signing is. Absent until Everee has requested a signature. contract.status is AWAITING_SIGNATURE, then SIGNED, then EXECUTED.
agreementHow your customers agree to pricing and service terms (DIRECT or UMBRELLA). See Agreeing to terms.
identityVerificationAfter submission, one entry per person being verified, with a coarse status.
requestsWhat Everee has asked you for during review.
goLiveWhether the company is live yet, and what's outstanding. See Payroll history and going live.
payrollHistoryWhere 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:

KeyCreates 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.

LimitApplies toEvaluationSandboxWhat happens
Sandbox companies alive at onceTest key125Creating another returns 429. Retire a Sandbox company you no longer need to free a slot.
Sandbox companies created in any rolling 7 daysTest key250Creating 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 daysProduction keyn/a100Nothing 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 companyEvaluationSandboxWhat happens
Off-cycle payroll runs created in any rolling 7 days10100Creating another returns 429. The error message says when the next one can be created.
Payroll run calculations requested in any rolling 24 hours20100Calculating 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 status25250Adding 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 agreementConsent is 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.missing and in requirements.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-changed event lists what is newly required and what no longer is, and journey in the status shows which version applies.

Statuses

Every company has an onboarding status.

StatusMeaningWhat you can do
DRAFTYou are collecting information.Create and change everything. Submit when the readiness check is complete. Withdraw at any time.
UNDER_REVIEWSubmitted. Everee is verifying identities and reviewing the company.Respond to requests from Everee. Other data is locked.
APPROVEDEveree approved the company and has countersigned the agreements.Use the company API key to call the rest of the Everee API.
DECLINEDEveree declined the company. decision.reasonCode has a generic reason.Nothing. Contact your Everee representative.
WITHDRAWNYou 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

#ScreenCodes it satisfiesCall
1Create the company(none)Create company
2Business detailsLEGAL_ENTITY_TYPE, FORMATION_STATE, BUSINESS_ADDRESSUpdate company
3Supporting documentsIRS_EIN_LETTER, BUSINESS_FORMATIONUpload a document
4Payroll profileWORKER_TYPES, EMPLOYEE_COUNT, CONTRACTOR_COUNT, PAY_FREQUENCY, PAY_PERIOD_START_DAY, ANNUAL_REVENUE, NATURE_OF_BUSINESS, NAICS_CODEUpdate payroll profile
5People: control person, owners, signerCONTROL_PERSON, OWNERSHIP_DECLARATION, OWNERSHIP_TOTAL, SIGNER, SIGNER_IDENTITY, SIGNER_RELATIONSHIPControl person, owners, ownership declaration, signer
6Customer's agreement (only some partners)AGREEMENT_CONSENTReport agreement consent
7TaxesTAX_STATESUpdate tax setup
8Sign and choose the bank accountSIGNED_CONTRACT, BANK_ACCOUNTCreate a signing session
9After signing: authority and IDsCERTIFICATE_OF_AUTHORITY, PICTURE_IDCertificate of authority, Upload a document
10Review 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-data with a file part.
  • PATCH endpoints change only the fields you send. PUT endpoints replace the resource.
  • Validation problems return 400 or 422 with 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) returns 409 or 422 with 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


Did this page help you?