Company Setup & KYB

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

curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/companies \
     --header 'Authorization: Bearer <partner_secret>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
         "name": "Bouchard Burger Inc."
     }'

Response

{
  "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

curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/business_entities \
     --header 'Authorization: Bearer <access_token>' \
     --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

{
  "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,
    "onboarding_status": "incomplete",
    "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

curl --request GET \
     --url https://sandbox.nmbr.co/services/payroll/business_entities/<business_entity_id>/verification \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json'

Response

{
  "id": "01hj1djve5zcjv1mrbvp3ps6aq",
  "object": "business_entity_verification",
  "data": {
    "status": "requested",
    "link_status": "not_started",
    "link": "https://verify.nmbr.co/kyb?token=<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/<business_entity_id>/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.

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.

Getting Started

Payroll Fundamentals

Canadian Payroll

Advanced Concepts

Usage & Billing

Company Setup & KYB

1. Create a company

2. Create a business entity

3. Send the customer to business verification

4. Check verification status

Business verification warnings

If verification needs review

​1. Create a company

​2. Create a business entity

​3. Send the customer to business verification

​4. Check verification status

​Business verification warnings

​If verification needs review

1. Create a company

2. Create a business entity

3. Send the customer to business verification

4. Check verification status

Business verification warnings

If verification needs review