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"
  }'
  • taxContact is optional and defaults to the primary contact.
  • webhookUrl is optional. It must be an https URL on a public host. When you give one, Everee creates a webhook endpoint for the company and returns its webhookSigningKey, 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:

FieldMeaning
idThe company's ID, used in every other path.
onboardingStatusDRAFT.
environmentSANDBOX 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.
apiKeyThe 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.
webhookSigningKeyPresent 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 with required and provided. Show a step for a kind only when required is true, and treat it as done when provided is true. A code is only in readiness.missing while it is required.
  • If Everee rejects a document, its reviewStatus becomes REJECTED with a reviewNote, 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"
  }'
CodeSatisfied byNotes
WORKER_TYPESpaysW2Employees and/or paysContractors set to trueIt 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_COUNTemployeeCountOnly asked when the company pays W-2 employees.
CONTRACTOR_COUNTcontractorCountOnly asked when the company pays contractors.
PAY_FREQUENCYpayFrequency: DAILY, WEEKLY, BI_WEEKLY, SEMI_MONTHLY or MONTHLY
PAY_PERIOD_START_DAYpayPeriodStartDay (a weekday)Only asked for WEEKLY and BI_WEEKLY.
ANNUAL_REVENUEannualRevenueAn amount and currency.
NATURE_OF_BUSINESSnatureOfBusinessA short description.
NAICS_CODEnaicsCode, six digitsLet 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_DECLARATION stays until you either add an owner or declare hasAdditionalOwners as false.
  • OWNERSHIP_TOTAL appears 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 (ownerType PERSON, the default) or an entity (ENTITY, with entityName, entityEin and 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"
  }'
relationshipRule
CONTROL_PERSONThe 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_OWNERThe 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.
NEITHERSend 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 come

Collecting 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.complete doesn'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.

  1. Wait until Everee has requested the signature: a company-onboarding.signature-requested webhook arrives, and the status shows contract.status of AWAITING_SIGNATURE. Until then, creating a session returns 409. If the signature is never requested, check that nothing else is in readiness.missing (apart from the four codes that wait for signing) and that Everee has loaded the company's contract terms.
  2. 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.
  3. The signer opens the experience, connects the company's funding bank account through their bank (a business account), reviews the agreements, and signs once.
  4. You receive company-onboarding.contract-signed, and both codes leave readiness.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_AUTHORITY appears only when the signer is neither the control person nor an owner (relationship of NEITHER). Upload a PDF showing the signer may sign for the company with Upload a certificate of authority.

  • PICTURE_ID appears only when you capture pictures of IDs, which is part of how Everee has set up your account (journey.documentCapture in the status is PARTNER). 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"

    personRef is control-person, owner-<id> or signer. Otherwise (journey.documentCapture is ALLOY, the default), Everee's identity provider captures each ID when the person verifies, PICTURE_ID never appears, and an upload returns 409.

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. identityVerification in the status shows each person's coarse status, and company-onboarding.identity-verification-changed fires 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 requests and answer each as described in Submitting for review.
  • The outcome. status-changed arrives with APPROVED or DECLINED. 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.


Did this page help you?