Collecting Company Information
Create a draft company and send Everee the information it needs, step by step.
This guide walks through creating a company and filling in its draft, one screen at a time, in the order Everee's own self-signup uses. Each step names the readiness codes it satisfies: see The readiness check for how the codes drive your screens. All requests go to https://api.everee.com/integration/v1/partner/companies and use your partner API key (see Authentication). In the examples, $KEY is your partner API key and $ID is the company's ID.
You can make these calls in any order, as often as you like, until the agreements are signed. Get onboarding status at any point to see what is still missing.
1. Create the company
Creating a company needs only the legal name, the EIN, and a primary contact: the person Everee creates the company's first user from.
curl -X POST https://api.everee.com/integration/v1/partner/companies \
-u "$KEY:" \
-H "Content-Type: application/json" \
-d '{
"legalBusinessName": "Summit Ridge Plumbing LLC",
"ein": "87-1234567",
"primaryContact": {
"firstName": "Dana",
"lastName": "Whitfield",
"email": "[email protected]",
"phone": "8015550142"
},
"webhookUrl": "https://hooks.yourplatform.example/everee"
}'taxContactis optional and defaults to the primary contact.webhookUrlis optional. It must be anhttpsURL on a public host. When you give one, Everee creates a webhook endpoint for the company and returns itswebhookSigningKey, which you use to verify events. You can change it, add more endpoints and rotate the signing key later with the Webhook Endpoints API, using the company's API key.
The response contains the company, including:
| Field | Meaning |
|---|---|
id | The company's ID, used in every other path. |
onboardingStatus | DRAFT. |
environment | SANDBOX when you create the company with your test key, PRODUCTION when you use your production key (which Everee issues after it approves your integration). It is also in the response when you retrieve the company. |
apiKey | The company's own API key. It begins with tsk_test_ for a Sandbox company and tsk_prod_ for a Production company. It is returned only in this response. Store it with the company's record in your system. |
webhookSigningKey | Present only when you supplied a webhookUrl. Returned only in this response. |
No readiness code is satisfied by this call, and the status starts as DRAFT.
2. Business details
Readiness codes: LEGAL_ENTITY_TYPE, FORMATION_STATE, BUSINESS_ADDRESS
Ask for the company's legal entity type, the state it was formed in, and its business address. Optional: trade name, business phone and website.
curl -X PATCH https://api.everee.com/integration/v1/partner/companies/$ID \
-u "$KEY:" -H "Content-Type: application/json" \
-d '{
"legalEntityType": "LLC_SINGLE_MEMBER",
"formationState": "UT",
"tradeName": "Summit Ridge Plumbing",
"address": { "line1": "4420 S 900 E", "city": "Salt Lake City", "state": "UT", "postalCode": "84124" }
}'legalEntityType is one of C_CORPORATION, S_CORPORATION, LLC_MULTI_MEMBER, LLC_SINGLE_MEMBER, PARTNERSHIP, SOLE_PROPRIETORSHIP, NONPROFIT or OTHER. formationState and the address state are two-letter state codes. It is a partial update, so send only what changed. See Update company.
3. Supporting documents
Readiness codes: IRS_EIN_LETTER, BUSINESS_FORMATION
Ask the user for the company's IRS EIN letter and its business formation documents (for example the articles of organization).
curl -X POST https://api.everee.com/integration/v1/partner/companies/$ID/documents/IRS_EIN_LETTER \
-u "$KEY:" -F "[email protected];type=application/pdf"
curl -X POST https://api.everee.com/integration/v1/partner/companies/$ID/documents/BUSINESS_FORMATION \
-u "$KEY:" -F "[email protected];type=application/pdf"- Files are PDF, PNG or JPEG, up to 25 MB. A new EIN letter replaces the last one; you can add several formation documents.
- Whether each is required is decided by Everee and can change. List documents returns
requirements.documents, one entry per kind withrequiredandprovided. Show a step for a kind only whenrequiredistrue, and treat it as done whenprovidedistrue. A code is only inreadiness.missingwhile it is required. - If Everee rejects a document, its
reviewStatusbecomesREJECTEDwith areviewNote, it stops counting, and Everee opens a document request for a replacement.
4. Payroll profile
Readiness codes: WORKER_TYPES, EMPLOYEE_COUNT, CONTRACTOR_COUNT, PAY_FREQUENCY, PAY_PERIOD_START_DAY, ANNUAL_REVENUE, NATURE_OF_BUSINESS, NAICS_CODE
Ask what kind of payroll the company runs.
curl -X PATCH https://api.everee.com/integration/v1/partner/companies/$ID/payroll-profile \
-u "$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"
}'| Code | Satisfied by | Notes |
|---|---|---|
WORKER_TYPES | paysW2Employees and/or paysContractors set to true | It also stays missing if the company's plan does not price the worker type you chose (Everee sets the plan). Ask your Everee representative. |
EMPLOYEE_COUNT | employeeCount | Only asked when the company pays W-2 employees. |
CONTRACTOR_COUNT | contractorCount | Only asked when the company pays contractors. |
PAY_FREQUENCY | payFrequency: DAILY, WEEKLY, BI_WEEKLY, SEMI_MONTHLY or MONTHLY | |
PAY_PERIOD_START_DAY | payPeriodStartDay (a weekday) | Only asked for WEEKLY and BI_WEEKLY. |
ANNUAL_REVENUE | annualRevenue | An amount and currency. |
NATURE_OF_BUSINESS | natureOfBusiness | A short description. |
NAICS_CODE | naicsCode, six digits | Let the user search with List NAICS codes (?search=plumbing) rather than typing a code. |
It is a partial update. See Update payroll profile.
You can also send targetGoLiveDate, the date you want the company to go live. It must be the first day of a pay period for the frequency you send. See Set a target go-live date.
5. The people
Readiness codes: CONTROL_PERSON, OWNERSHIP_DECLARATION, OWNERSHIP_TOTAL, SIGNER, SIGNER_IDENTITY, SIGNER_RELATIONSHIP
Everee must know who controls the company, who owns 25% or more of it, and who signs for it. One person can hold more than one role. Collect them in this order, because the signer is matched against the other two.
a. The control person (CONTROL_PERSON). The individual with significant responsibility to control, manage or direct the company, such as the CEO. Exactly one is needed, with their ownership percentage and identity details (date of birth, address, and either an SSN or a passport number and country).
curl -X PUT https://api.everee.com/integration/v1/partner/companies/$ID/control-person \
-u "$KEY:" -H "Content-Type: application/json" \
-d '{
"firstName": "Dana", "lastName": "Whitfield", "title": "Managing Member",
"email": "[email protected]", "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" }
}
}'b. Other owners (OWNERSHIP_DECLARATION, OWNERSHIP_TOTAL). Everee only asks about owners of 25% or more, and they do not have to add up to 100%. If the control person owns more than 75%, nobody else can qualify, and neither code is asked. Otherwise, ask "does anyone else own 25% or more?" and then either add each owner or declare that nobody does:
curl -X POST https://api.everee.com/integration/v1/partner/companies/$ID/beneficial-owners \
-u "$KEY:" -H "Content-Type: application/json" \
-d '{
"firstName": "Pat", "lastName": "Lee", "email": "[email protected]", "phone": "8015550143",
"ownershipPercentage": 40,
"identity": { "dateOfBirth": "1979-02-03", "ssn": "987-65-4321",
"address": { "line1": "12 Elm St", "city": "Provo", "state": "UT", "postalCode": "84601" } }
}'
curl -X PUT https://api.everee.com/integration/v1/partner/companies/$ID/ownership-declaration \
-u "$KEY:" -H "Content-Type: application/json" -d '{ "hasAdditionalOwners": false }'OWNERSHIP_DECLARATIONstays until you either add an owner or declarehasAdditionalOwnersasfalse.OWNERSHIP_TOTALappears when the percentages you gave are inconsistent with the declaration or exceed 100% in total. Fix the owners you entered (update or delete one).- An owner can be an individual (
ownerTypePERSON, the default) or an entity (ENTITY, withentityName,entityEinand the representing individual's details). - An owner under 25% is never entered, so the API refuses one.
c. The signer (SIGNER, SIGNER_RELATIONSHIP, SIGNER_IDENTITY). The person who signs the agreements in step 8. Their relationship decides what else is needed:
curl -X PUT https://api.everee.com/integration/v1/partner/companies/$ID/signer \
-u "$KEY:" -H "Content-Type: application/json" \
-d '{
"firstName": "Dana", "lastName": "Whitfield", "title": "Managing Member",
"email": "[email protected]", "phone": "8015550142",
"relationship": "CONTROL_PERSON"
}'relationship | Rule |
|---|---|
CONTROL_PERSON | The signer is the control person. Their name must match the control person's, ignoring case, or SIGNER_RELATIONSHIP appears. No identity details are needed. |
BENEFICIAL_OWNER | The signer is an owner of 25% or more (or a control person who owns 25% or more). Their name must match someone on file, or SIGNER_RELATIONSHIP appears. No identity details are needed. |
NEITHER | Send identity as well (or SIGNER_IDENTITY stays). The signer is verified separately, and a certificate of authority is needed (step 9). |
If SIGNER_RELATIONSHIP appears, either correct the signer's name or relationship, or add the person they say they are. The signer's name must match what they type when they sign.
6. The customer's agreement
Readiness codes: AGREEMENT_CONSENT
Only for partners whose customers agree to pricing and service terms under the partner's own subscription agreement (agreement.mode is UMBRELLA in the status). When the customer consents, call Report agreement consent with when and how they consented and "attestation": true. The consent is recorded for the signer, so a different signer needs a fresh one. See Agreeing to terms. For every other partner this code never appears.
7. Taxes
Readiness codes: TAX_STATES
Only asked when the company pays W-2 employees. Ask which states it withholds taxes in, and optionally its federal return type.
curl -X PATCH https://api.everee.com/integration/v1/partner/companies/$ID/tax-setup \
-u "$KEY:" -H "Content-Type: application/json" \
-d '{ "returnType": "FORM_941", "states": ["UT", "ID"] }'returnType is FORM_941 or FORM_944. See Update tax setup.
State tax information
Details to comeCollecting the company's state tax information is a required step of company onboarding, and it gates going live. It is not one of the readiness codes, so
readiness.completedoesn't cover it. Details of how to collect it are coming.
Contract terms and the signature request
Everee sets the pricing and billing items for each company, so you do not provide them. When everything in steps 2 to 7 is in and Everee has loaded the company's terms, Everee requests the signature: you receive a company-onboarding.signature-requested webhook, and the status shows contract.status of AWAITING_SIGNATURE. Then continue with step 8.
8. Signing and the bank account
Readiness codes: SIGNED_CONTRACT, BANK_ACCOUNT
You make no data call for these two codes. Both are completed by the signer inside Everee's embedded signing experience, which you show in your product.
- Wait until Everee has requested the signature: a
company-onboarding.signature-requestedwebhook arrives, and the status showscontract.statusofAWAITING_SIGNATURE. Until then, creating a session returns409. If the signature is never requested, check that nothing else is inreadiness.missing(apart from the four codes that wait for signing) and that Everee has loaded the company's contract terms. - Call Create a signing session and show the returned URL in an iframe. Sessions are single-use and expire in minutes, so create one when the user arrives.
- The signer opens the experience, connects the company's funding bank account through their bank (a business account), reviews the agreements, and signs once.
- You receive
company-onboarding.contract-signed, and both codes leavereadiness.missing.
Signing locks everything that appears on the documents. See Signing the agreements.
9. After signing
Readiness codes: CERTIFICATE_OF_AUTHORITY, PICTURE_ID
These two are still collected after signing, while the onboarding is a draft.
-
CERTIFICATE_OF_AUTHORITYappears only when the signer is neither the control person nor an owner (relationshipofNEITHER). Upload a PDF showing the signer may sign for the company with Upload a certificate of authority. -
PICTURE_IDappears only when you capture pictures of IDs, which is part of how Everee has set up your account (journey.documentCapturein the status isPARTNER). Upload the front, and the back if the ID has one, of each person who must be verified: the control person, every owner of 25% or more, and a signer who is neither. List documents shows who is still missing a side.curl -X POST "https://api.everee.com/integration/v1/partner/companies/$ID/documents/PICTURE_ID?personRef=control-person&side=FRONT" \ -u "$KEY:" -F "[email protected];type=image/jpeg"personRefiscontrol-person,owner-<id>orsigner. Otherwise (journey.documentCaptureisALLOY, the default), Everee's identity provider captures each ID when the person verifies,PICTURE_IDnever appears, and an upload returns409.
10. Review and submit
When readiness.complete is true, show a review screen and then call Submit for review. The status becomes UNDER_REVIEW and data is locked. Submitting before the check is complete returns 422 and lists the missing codes. Submitting twice is harmless.
After you submit
- Identity verification. Everee sends each person (the control person, owners of 25% or more, and a signer who is neither) a link to verify.
identityVerificationin the status shows each person's coarse status, andcompany-onboarding.identity-verification-changedfires when it changes. If someone did not get their link, fix their details with Correct a person's contact details and then resend it. - Requests. Everee may ask for more: a document (including a replacement for one it rejected), an answer, another person, a new identity link or a new signature. Show them from
requestsand answer each as described in Submitting for review. - The outcome.
status-changedarrives withAPPROVEDorDECLINED. After approval, use the company API key for the rest of the Everee API.
Checking your work
Get onboarding status returns the readiness check, the contract state, identity verification, and open requests in one call. Get company returns everything you have sent, including the payroll profile.
Updated 6 days ago