> ## Documentation Index > Fetch the complete documentation index at: https://docs.nmbr.co/llms.txt > Use this file to discover all available pages before exploring further. # Company Setup & KYB > Guide to enrolling a company in Nmbr's payroll services Before Nmbr can process payroll for a company, Nmbr needs information about the company to meet regulatory obligations, determine processing periods, and surface onboarding flows. As a partner, you submit this information through the Nmbr API before the customer's first payroll. This guide walks through the API calls to create the company, create at least one business entity, and send the customer through business verification (KYB). ## 1. Create a company A `Company` is the top-level container for one customer. Create it with your partner secret. The response includes a company-scoped `access_token` for future API calls for that customer. **Request** ```bash theme={null} curl --request POST \ --url https://sandbox.nmbr.co/services/payroll/companies \ --header 'Authorization: Bearer ' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{ "name": "Bouchard Burger Inc." }' ``` **Response** ```json theme={null} { "id": "01hhcy3fc40cp6yyv500re1041", "object": "company", "data": { "name": "Bouchard Burger Inc.", "pay_day_movement_setting": "inherit", "created_at": "2023-12-11T17:16:55.000000Z", "updated_at": "2023-12-11T17:16:55.000000Z", "token": { "access_token": "4nWkuMVylVeJMkOiFaPMzbQwdUklsP08sIqkBifve92a05c2", "expires_in": 59, "expires_at": "2023-12-11T18:16:55.000000Z" } }, "links": { "self": "https://sandbox.nmbr.co/services/payroll/companies/01hhcy3fc40cp6yyv500re1041" } } ``` ## 2. Create a business entity A business entity is the legal employer that runs payroll. Tax agency accounts, such as CRA payroll accounts, are configured separately as remittance accounts. Required information includes: * Business number * Legal business name * Legal registration number * Address on file * Primary business contact A company can have more than one business entity. Use the company-scoped `access_token` returned when you created the company. **Request** ```bash theme={null} curl --request POST \ --url https://sandbox.nmbr.co/services/payroll/business_entities \ --header 'Authorization: Bearer ' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{ "business_number": "36774676RP0001", "name": "Bobs Burgers (#67667)", "legal_name": "8877362 Inc", "legal_registration_number": "047738-9", "address_line_1": "13 Main Street", "address_line_2": null, "city": "Toronto", "province_code": "ON", "country_code": "CA", "postal_code": "M1M1M1", "contact_name": "Bob", "contact_area_code": "416", "contact_phone_number": "3748686", "contact_extension": null }' ``` **Response** ```json theme={null} { "id": "01hhcy3fpqkez7wjqzeaqetwfs", "object": "business_entity", "data": { "business_number": "36774676RP0001", "name": "Bobs Burgers (#67667)", "legal_name": "8877362 Inc", "legal_registration_number": "047738-9", "address_line_1": "13 Main Street", "address_line_2": null, "city": "Toronto", "province_code": "ON", "country_code": "CA", "postal_code": "M1M1M1", "contact_name": "Bob", "contact_area_code": "416", "contact_phone_number": "3748686", "contact_extension": null, "status": "onboarding", "in_preview": false, "created_at": "2023-12-11T17:16:55.000000Z", "updated_at": "2023-12-11T17:16:55.000000Z" }, "links": { "self": "https://sandbox.nmbr.co/services/payroll/business_entities/01hhcy3fpqkez7wjqzeaqetwfs" } } ``` Outcome: Nmbr creates the business entity and starts business verification automatically. You do not need to create a separate verification record. ## 3. Send the customer to business verification KYB stands for "Know Your Business." It is the due diligence process financial companies use to verify a business's identity and assess risk. Nmbr checks the business against corporate registries, sanctions and watchlists, and other AML sources. Nmbr creates a business entity verification when the business entity is created. When verification needs information directly from the business, Nmbr stores a hosted verification link on the business entity verification record. Retrieve the verification record after you create the business entity. Send the customer to the returned `link` so they can complete verification. **Request** ```bash theme={null} curl --request GET \ --url https://sandbox.nmbr.co/services/payroll/business_entities//verification \ --header 'Authorization: Bearer ' \ --header 'accept: application/json' ``` **Response** ```json theme={null} { "id": "01hj1djve5zcjv1mrbvp3ps6aq", "object": "business_entity_verification", "data": { "status": "requested", "link_status": "not_started", "link": "https://verify.nmbr.co/kyb?token=", "external_id": "vs_abc123", "business_entity": { "id": "01hhcy3fpqkez7wjqzeaqetwfs", "object": "business_entity", "links": { "self": "https://sandbox.nmbr.co/services/payroll/business_entities/01hhcy3fpqkez7wjqzeaqetwfs" } }, "created_at": "2023-12-11T17:16:56.000000Z", "updated_at": "2023-12-11T17:16:56.000000Z" }, "links": { "self": "https://sandbox.nmbr.co/services/payroll/business_entities/01hhcy3fpqkez7wjqzeaqetwfs/verification" } } ``` Outcome: the customer completes verification from the hosted link. Nmbr receives the result from the verification provider and updates the verification status. Note: the verification link is provider-hosted and may expire. If a link no longer works, contact Nmbr support for a refreshed link. ## 4. Check verification status Use `GET /business_entities//verification` to check the current status. | Status | What it means | What to do next | | ------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `incomplete` | Nmbr created the verification record, but the hosted verification link has not been requested yet. | Try the request again shortly. If the status does not move to `requested`, contact Nmbr support. | | `requested` | The hosted verification link is available and the business is waiting on verification. | Send the customer to the `link`, or wait for the provider result if they already completed it. | | `approved` | The business passed verification. | Continue onboarding. Related business verification warnings are resolved. | | `failed` | The business did not pass verification. | Contact Nmbr support for next steps. The API does not return a machine-readable failure reason. | The `status` field is the verification decision. The `link_status` field only tracks how far the business has gotten through the hosted link: * `not_started`: the link has been shared, but the business has not completed it. * `in_progress`: the business submitted their information and it is being processed. * `complete`: the information is in and has been picked up for review. `link_status` never carries the decision. Read the outcome from `status`. ## Check whether you can approve a payroll Before you call `POST /payrolls//approve`, retrieve the business entity with `GET /business_entities/` and read its `status` field. `status` is the business entity's lifecycle state: `onboarding`, `approved`, or `suspended`. You can approve a payroll once the business entity's `status` is `approved`. The verification endpoint also returns a `status`, but it is the KYB decision: `incomplete`, `requested`, `approved`, or `failed`. Do not use it to determine whether a payroll can be approved. For example, verification can be `approved` while the business entity remains `onboarding`. This check only determines business entity eligibility. The payroll must still meet the endpoint's other approval requirements, such as being draft and fully calculated. Preview Mode is a separate case. A business entity in [Preview Mode](/guides/advanced/preview-mode) (`in_preview` is `true`) can approve payrolls regardless of its `status`, because preview runs never move real money. It is a testing state, not an approval status. ## Business verification warnings Business verification can block onboarding while the status is `incomplete`, `requested`, or `failed`. When the status is `approved`, Nmbr clears the business verification warning. You can then continue with the rest of the company setup flow. ## If verification needs review Automated KYB can fail when business information cannot be validated against registry data, sanctions lists, or other AML checks. If that happens, Nmbr may ask the customer for an identification document so Nmbr can complete manual KYC/KYB review. Nmbr accepts any of the following documents for a business: * Certificate of incorporation/registration * Memorandum/articles of incorporation/association/registration * Directors registry * Shareholder registry * Trust agreement * Proof of address. For example, a utility bill, rent contract, or electricity bill. * Certificate of incumbency * Statement of information * Certificate of good standing Manual review can often take 24 hours after Nmbr has the required information. Partners should not build a separate document-upload step for this guide. Nmbr does not expose an API for partners to upload these documents for business verification. The verification response also does not include a machine-readable failure reason or manual review payload.