Business Onboarding

Use the Business Onboarding endpoints to create and verify sub-businesses under your Tradevu account — for example, if you’re a platform onboarding merchants of your own. Every business you create is scoped to your API key and only visible to you.

Currently, Nigerian businesses (LLC, LLP, and SoleProprietorship) are supported. LLP follows the exact same document requirements as LLC. country is fixed to Nigeria on every business you create through this API.

The flow

Upload supporting documents

Upload each document (certificate of incorporation, bank statement, proof of address, etc.) individually and collect the returned URLs before you create the business.

Create the business

Call POST /api/business with the business’s identity, address, and documents. The required document set depends on businessType — see Required documents below.

Add directors and UBOs

Call POST /api/business/:businessId/director and POST /api/business/:businessId/ubo for each person. Once at least one director and one UBO have been added, the business is automatically submitted for verification.

(Optional) Update or check status

Use PATCH /api/business/:businessId to correct or add fields, and GET /api/business/:businessId to poll verification status.

Uploading a document

curl -X POST https://api.tradevu.co/v1/api/business/upload-file \
  -H "x-api-key: <your-api-key>" \
  -F "file=@/path/to/certificate.pdf"

Response

{
  "link": "https://tradevu-space.nyc3.digitaloceanspaces.com/certificate.pdf"
}

file

required

The document to upload. Accepts JPEG, PNG, or PDF, up to 20MB.

The response only returns a link. When you reference this document elsewhere in the API (e.g. in documents, proofOfAddress, or sourceOfFund), pass that link as url, and any identifier you want to keep for your own records as key — Tradevu doesn’t derive key from the upload, it just stores whatever you send.

Create a business

POST /api/business creates a sub-business and submits its top-level KYB fields. Every field except documents and the optional ones below maps 1:1 to the request body.

string

required

Registered business name.

string

required

LLC, LLP, or SoleProprietorship. LLP requires the same documents as LLC.

string

required

CAC registration number (or BN number for sole proprietorships).

string

required

Business email address.

string

required

Business phone number, in E.164 format (e.g. +2348012345678).

object

required

{ nature: string, code: string } — a free-text description and your own classification code.

object

required

{ houseNumber, street, city, state, zipCode, subdivision? }.

object

Same shape as businessAddress, if it differs from the registered address.

object

required

{ url, key, type } — type is one of Utility bill, Tax Bill, Electricity Bill, Lease agreement, Tenancy agreement, Recent utility bill, Council tax bill.

object

required

A map of document key → { url, key }. See Required documents.

string

Short description of what the business does.

string[]

List of business activities.

object

{ currency, amount } — expected monthly volume.

boolean

Whether the business has a website.

string

Website URL, if hasWebsite is true.

object

{ url?, type, name? } — where the business’s funds come from.

string

Tax identification number.

string

Legal name, if different from name.

Creating a business with a name or registrationNumber that already exists (on any business, not just your own) returns a 400.

Required documents

The documents object accepts flexible keys — Tradevu maps common aliases (cac_document, cac, certificate_of_incorporation, bank_statement, bn_form_1, combined_cac, etc.) to internal document types automatically. Anything not on this list falls back to an uppercased match against the supported document types (e.g. business_license → BUSINESS_LICENSE), and unrecognized keys are rejected. Every business needs a certificate of incorporation or business license and a six-month bank statement. Beyond that, requirements differ by businessType:

SoleProprietorship
LLC/LLP — CAC forms
LLC/LLP — status report

Also requires an application letter, plus either:

a cac_status_report, or
a bn_form_1 (BN Form 1)

{
  "name": "Example Nigeria Limitedd",
  "businessType": "SoleProprietorship",
  "registrationNumber": "RC1234e4567",
  "email": "[email protected]",
  "phoneNumber": "+2348012345678",
  "natureOfBusiness": {
    "nature": "Retail and distribution",
    "code": "retail"
  },
  "businessAddress": {
    "houseNumber": "12",
    "street": "Adeola Odeku Street",
    "city": "Lagos",
    "state": "Lagos",
    "zipCode": "101233"
  },
  "proofOfAddress": {
    "url": "https://example.com/documents/utility-bill.pdf",
    "key": "business/utility-bill.pdf",
    "type": "Utility bill"
  },
  "documents": {
    "cac_document": {
      "url": "https://example.com/certificate.pdf",
      "key": "business/certificate.pdf"
    },
    "application_letter": {
      "url": "https://example.com/application-letter.pdf",
      "key": "business/application-letter.pdf"
    },
    "bank_statement": {
      "url": "https://example.com/six-month-bank-statement.pdf",
      "key": "business/six-month-bank-statement.pdf"
    },
    "cac_status_report": {
      "url": "https://example.com/cac-status-report.pdf",
      "key": "business/cac-status-report.pdf"
    },
    "bn_form_1": {
      "url": "https://example.com/bn-form-1.pdf",
      "key": "business/bn-form-1.pdf"
    }
  },
  "businessDescription": "Retail and distribution company",
  "activities": ["Retail", "Distribution"],
  "monthlyTransactionVolume": { "currency": "NGN", "amount": "5000000" },
  "hasWebsite": true,
  "businessWebsite": "https://example.com",
  "sourceOfFund": {
    "url": "https://example.com/documents/source-of-funds.pdf",
    "type": "Business revenue",
    "name": "Bank statement"
  }
}

cac_document (aliased to a certificate document) satisfies the certificate requirement — you don’t also need cac. bn_form_1 alone is enough to satisfy the status-report-or-BN-Form-1 rule; the cac_status_report above is included for completeness but isn’t required if bn_form_1 is present.

Also requires memorandum & articles of association and a board resolution, plus one of:

a cac_status_report,
a combined_cac document, or
all five individual CAC forms: cac_form_2, cac_form_2_1, cac_form_3, cac_form_4, cac_form_7

{
  "name": "Example Nigeria Limited e",
  "businessType": "LLC",
  "registrationNumber": "RC1234e567",
  "email": "[email protected]",
  "phoneNumber": "+2348012345678",
  "natureOfBusiness": {
    "nature": "Retail and distribution",
    "code": "retail"
  },
  "businessAddress": {
    "houseNumber": "12",
    "street": "Adeola Odeku Street",
    "city": "Lagos",
    "state": "Lagos",
    "zipCode": "101233"
  },
  "proofOfAddress": {
    "url": "https://example.com/documents/utility-bill.pdf",
    "key": "business/utility-bill.pdf",
    "type": "Utility bill"
  },
  "documents": {
    "cac_document": {
      "url": "https://example.com/documents/certificate-of-incorporation.pdf",
      "key": "business/certificate-of-incorporation.pdf"
    },
    "business_license": {
      "url": "https://example.com/documents/business-license.pdf",
      "key": "business/business-license.pdf"
    },
    "memorandum_articles": {
      "url": "https://example.com/documents/memorandum-and-articles.pdf",
      "key": "business/memorandum-and-articles.pdf"
    },
    "board_resolution": {
      "url": "https://example.com/documents/board-resolution.pdf",
      "key": "business/board-resolution.pdf"
    },
    "bank_statement": {
      "url": "https://example.com/documents/six-month-bank-statement.pdf",
      "key": "business/six-month-bank-statement.pdf"
    },
    "combined_cac": {
      "url": "https://example.com/documents/combined-cac-forms.pdf",
      "key": "business/combined-cac-forms.pdf"
    },
    "cac_form_2": {
      "url": "https://example.com/documents/cac-form-2.pdf",
      "key": "business/cac-form-2.pdf"
    },
    "cac_form_2_1": {
      "url": "https://example.com/documents/cac-form-2-1.pdf",
      "key": "business/cac-form-2-1.pdf"
    },
    "cac_form_3": {
      "url": "https://example.com/documents/cac-form-3.pdf",
      "key": "business/cac-form-3.pdf"
    },
    "cac_form_4": {
      "url": "https://example.com/documents/cac-form-4.pdf",
      "key": "business/cac-form-4.pdf"
    },
    "cac_form_7": {
      "url": "https://example.com/documents/cac-form-7.pdf",
      "key": "business/cac-form-7.pdf"
    },
    "application_letter": {
      "url": "https://example.com/documents/application-letter.pdf",
      "key": "business/application-letter.pdf"
    }
  }
}

Sending combined_cac and all five individual CAC forms (as above) is redundant but harmless — only one of the three options is required.

Same core requirements as above, satisfied here with a cac_status_report instead of CAC forms:

{
  "name": "Example Nigeria Limited 4",
  "businessType": "LLC",
  "registrationNumber": "09284507",
  "email": "[email protected]",
  "phoneNumber": "+2348012345678",
  "natureOfBusiness": {
    "nature": "Retail and distribution",
    "code": "retail"
  },
  "businessAddress": {
    "houseNumber": "12",
    "street": "Adeola Odeku Street",
    "city": "Lagos",
    "state": "Lagos",
    "zipCode": "101233"
  },
  "proofOfAddress": {
    "url": "https://example.com/documents/utility-bill.pdf",
    "key": "business/utility-bill.pdf",
    "type": "Utility bill"
  },
  "documents": {
    "cac_document": {
      "url": "https://example.com/documents/certificate-of-incorporation.pdf",
      "key": "business/certificate-of-incorporation.pdf"
    },
    "business_license": {
      "url": "https://example.com/documents/business-license.pdf",
      "key": "business/business-license.pdf"
    },
    "memorandum_articles": {
      "url": "https://example.com/documents/memorandum-and-articles.pdf",
      "key": "business/memorandum-and-articles.pdf"
    },
    "board_resolution": {
      "url": "https://example.com/documents/board-resolution.pdf",
      "key": "business/board-resolution.pdf"
    },
    "bank_statement": {
      "url": "https://example.com/documents/six-month-bank-statement.pdf",
      "key": "business/six-month-bank-statement.pdf"
    },
    "cac_status_report": {
      "url": "https://example.com/documents/cac-status-report.pdf",
      "key": "business/cac-status-report.pdf"
    },
    "application_letter": {
      "url": "https://example.com/documents/application-letter.pdf",
      "key": "business/application-letter.pdf"
    }
  },
  "businessDescription": "Retail and distribution company",
  "activities": ["Retail", "Distribution"],
  "monthlyTransactionVolume": { "currency": "NGN", "amount": "5000000" },
  "hasWebsite": true,
  "businessWebsite": "https://example.com",
  "sourceOfFund": {
    "url": "https://example.com/documents/source-of-funds.pdf",
    "type": "Business revenue",
    "name": "Bank statement"
  }
}

Response (all variants)

{
  "message": "Business created successfully",
  "data": {
    "_id": "66f1c2...",
    "name": { "value": "Example Nigeria Limited", "status": "PENDING" },
    "type": "LLC",
    "registrationNumber": { "value": "RC1234567", "status": "PENDING" },
    "country": { "name": "Nigeria", "code": "NG", "flag": "🇳🇬", "continent": "Africa" },
    "status": "STARTED",
    "stage": 5,
    "wallets": [{ "currency": "NGN", "flag": "🇳🇬" }]
  }
}

Add a director or UBO

At minimum one director and one UBO are required before Tradevu will submit the business for verification — the last call that completes both automatically triggers submission.

curl -X POST https://api.tradevu.co/v1/api/business/66f1c2.../director \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
        "firstName": "Jane",
        "lastName": "Doe",
        "email": "[email protected]",
        "phoneNumber": "+2348012345678",
        "title": "Director",
        "gender": "Female",
        "dateOfBirth": "1990-01-01",
        "meanOfIdentificationType": "currentPassport",
        "meanOfIdentificationUrl": "https://example.com/documents/passport.pdf",
        "idNumber": "A12345678",
        "percentageOwnership": "50",
        "address": {
          "houseNumber": "12",
          "street": "Adeola Odeku Street",
          "city": "Lagos",
          "state": "Lagos",
          "zipCode": "101233"
        },
        "idDocumentFront": {
          "url": "https://example.com/documents/id-front.pdf",
          "key": "business/id-front.pdf"
        }
      }'

POST /api/business/:businessId/ubo takes the identical shape. Use POST .../director for a director/officer and POST .../ubo for a beneficial owner — the same person can be added to both if they hold both roles.

string

required

string

required

string

required

string

required

string

required

string

required

One of IdCard, BioMetricResidencePermit, BirthCertificate, currentPassport, driverLicense, bvnNumber, nationalId.

string

required

URL of the uploaded ID document.

object

required

{ houseNumber, street, city, state, zipCode, subdivision? }.

object

required

{ url, key }.

object

{ url, key }.

string

Email address.

string

Job title / role.

string

Ownership percentage, for UBOs.

string

Response

{
  "message": "Director added successfully",
  "data": {
    "_id": "66f1c3...",
    "firstName": "Jane",
    "lastName": "Doe",
    "status": "PENDING"
  }
}

Check business status

curl https://api.tradevu.co/v1/api/business/66f1c2... \
  -H "x-api-key: <your-api-key>"

Response

{
  "message": "Business fetched successfully",
  "data": {
    "_id": "66f1c2...",
    "name": { "value": "Example Nigeria Limited", "status": "PENDING" },
    "type": "LLC",
    "status": "SUBMITTED",
    "directors": [{ "_id": "66f1c3...", "firstName": "Jane", "lastName": "Doe", "status": "PENDING" }],
    "UBOs": [{ "_id": "66f1c4...", "firstName": "John", "lastName": "Doe", "status": "PENDING" }],
    "documents": {
      "CAC": { "url": "https://example.com/certificate.pdf", "status": "PENDING" },
      "BankStatement": { "url": "https://example.com/six-month-bank-statement.pdf", "status": "PENDING" }
    }
  }
}

Each field-level object (name, registrationNumber, individual documents, directors, UBOs) carries its own status (PENDING, APPROVED, REJECTED, …) and, when rejected, a reason — poll this endpoint or check your dashboard to see what’s outstanding.

Update a business

PATCH /api/business/:businessId accepts the same body as create, minus name and registrationNumber, and all fields optional — send only what you want to change. Any field you update (address, documents, TIN, etc.) is reset to PENDING status for re-review.

Full endpoint reference

See exact request/response schemas for every endpoint above.

Get Started

Guides

Business Onboarding

The flow

Uploading a document

Create a business

Required documents

Add a director or UBO

Check business status

Update a business

Full endpoint reference

​The flow

​Uploading a document

​Create a business

​Required documents

​Add a director or UBO

​Check business status

​Update a business

Full endpoint reference

The flow

Uploading a document

Create a business

Required documents

Add a director or UBO

Check business status

Update a business