Business

Search Kenyan business registrations via POST /api/v1/business/ke. All of registration_number, search_type, and consent (must be true) are required. Use search_type: pvt (company — shares & encumbrances), bn (sole proprietor — partners only), llp (limited liability partnership), or bo (beneficial owner — partners only). Registration format is validated per type. Fresh registry snapshots are reused for up to 7 days. Other country codes are not supported yet.

Test data

Sandbox test data

Use these values against the sandbox host. Click a value to copy it.

Sandbox registration numbers

Verify business registration

POST/api/v1/business/ke

{{baseUrl}}/api/v1/business/ke

Header

Header	Type	Description
Authorization	string	`Bearer YOUR_ACCESS_TOKEN` from the OAuth client-credentials flow
Content-Type	string	application/json

Body Parameters

Parameter	Type	Description	Required
registration_number	string	Company / BN / LLP registration number. Format rules: bn → BN-prefixed or numeric (≥3 digits); pvt → starts with PVT, PLC, or C; llp → starts with LLP; bo → any of those formats	required
search_type	string	One of: pvt \| bn \| llp \| bo (also accepts GENERAL / BENEFICIAL_OWNER). Billing: bn → business; pvt/GENERAL → company; llp → limitted; bo → business-ownership	required
consent	boolean	Must be true — confirms data-subject consent to perform this verification	required
customer_number	string	Optional reference for your own tracking (max 255 characters)	optional

Company search (pvt / llp)

Request payload for Company search (pvt / llp):

Sample dataRequest payload

{
  "registration_number": "CPV/2019/184726H",
  "search_type": "pvt",
  "consent": true
}

Expected response for Company search (pvt / llp):

200 OKSample dataExpected response

{
  "success": true,
  "response_code": 200,
  "message": "Company Search verification successful",
  "country": "ke",
  "data": {
    "registration_number": "CPV/2019/184726H",
    "business_name": "SAMPLE HOLDINGS LIMITED",
    "status": "registered",
    "registration_date": "18 March 2019",
    "postal_address": "100 - 00100",
    "physical_address": "123 SAMPLE STREET, NAIROBI, Fl: N/A, Room/Door: N/A, NAIROBI",
    "phone_number": "+254712345678",
    "branch": null,
    "email": "info@sample-holdings.example",
    "kra_pin": null,
    "verified": true,
    "partners": [
      {
        "type": "director_shareholder",
        "shares": [
          { "name": "ORDINARY", "shareCount": 600 }
        ],
        "postal_code": "",
        "postal_address": "",
        "phone_number": "",
        "name": "JOHN DOE SAMPLE",
        "id_type": "citizen",
        "id_number": "12345678",
        "gender": "M",
        "email": ""
      },
      {
        "type": "director_shareholder",
        "shares": [
          { "name": "ORDINARY", "shareCount": 400 }
        ],
        "postal_code": "",
        "postal_address": "",
        "phone_number": "",
        "name": "JANE DOE SAMPLE",
        "id_type": "alien",
        "id_number": "10224095",
        "gender": "F",
        "email": ""
      }
    ],
    "shares": [
      { "name": "ORDINARY", "value": 100, "shares": 1000 }
    ],
    "encumbrances": []
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Sole proprietor (bn) / beneficial owner (bo)

Request payload for Sole proprietor (bn) / beneficial owner (bo):

Sample dataRequest payload

{
  "registration_number": "BN/2019/847261K",
  "search_type": "bn",
  "consent": true
}

Expected response for Sole proprietor (bn) / beneficial owner (bo):

200 OKSample dataExpected response

{
  "success": true,
  "response_code": 200,
  "message": "Sole Proprietor verification successful",
  "country": "ke",
  "data": {
    "registration_number": "BN/2019/847261K",
    "business_name": "SAMPLE CONSULTANCY",
    "status": "registered",
    "registration_date": "15 January 2020",
    "postal_address": "100 - 00100",
    "physical_address": "123 SAMPLE STREET, NAIROBI",
    "phone_number": "+254712345678",
    "branch": null,
    "email": "info@sample-consultancy.example",
    "kra_pin": null,
    "verified": true,
    "partners": [
      {
        "type": "proprietor",
        "shares": [],
        "postal_code": "",
        "postal_address": "",
        "phone_number": "",
        "name": "JOHN DOE SAMPLE",
        "id_type": "citizen",
        "id_number": "12345678",
        "gender": "M",
        "email": ""
      }
    ]
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440001"
}

Response Fields

Field	Type	Description
success	boolean	Whether the request succeeded
response_code	number	Application response code (typically mirrors HTTP)
message	string	Human-readable status message (varies by search_type)
country	string	Country code from the path (ke)
data.registration_number	string	Business registration number
data.business_name	string	Registered business / company name
data.status	string	Registry status as returned by the registry (e.g. registered)
data.registration_date	string\|null	Registration date when available (often day Month year, e.g. 19 September 2024)
data.postal_address	string\|null	Postal address when available
data.physical_address	string\|null	Physical address when available
data.phone_number	string\|null	Contact phone when available (often E.164, e.g. +254…)
data.branch	boolean\|null	Branch flag when provided by the registry
data.email	string\|null	Contact email when available
data.kra_pin	string\|null	KRA PIN when available; null when not returned
data.verified	boolean\|null	Registry verified flag when available
data.partners	array	Directors / partners / owners (always present)
data.partners[].type	string	Role code from registry (e.g. director_shareholder, proprietor)
data.partners[].name	string	Partner full name
data.partners[].id_type	string	ID type code (e.g. citizen, alien, visitor)
data.partners[].id_number	string	Partner ID number
data.partners[].gender	string	Gender code (M / F) when available
data.partners[].shares	array	Partner shareholdings: [{ name, shareCount }]
data.partners[].email	string	Partner email (may be empty string)
data.partners[].phone_number	string	Partner phone (may be empty string)
data.partners[].postal_code	string	Partner postal code (may be empty string)
data.partners[].postal_address	string	Partner postal address (may be empty string)
data.shares	array	Share capital (pvt / llp only — omitted for bn / bo). Items: { name, value, shares } — e.g. name ORDINARY
data.encumbrances	array	Encumbrances (pvt / llp only — omitted for bn / bo). Items: { date, description, people, amount }
request_id	string	UUID for support and audit trails

Error codes

Standard Peleza HTTP / response_code values (same across all API calls). Validation message text is endpoint-specific. Full reference: Error Codes.

Code	When	Billed?
200	Business details returned — billed as business (bn), company (pvt/GENERAL), limitted (llp), or business-ownership (bo)	Yes
422	Validation — missing/invalid registration_number, search_type, or consent (must be true)	No
401	Missing or invalid Bearer token	No
402	Insufficient wallet balance or credit limit	No
403	No active wallet or billing profile (or service not enabled)	No
404	Business not found in the registry	Yes
404	Unsupported country (not ke)	No
429	Rate limited	No
500	Unexpected server error during verification	No
503	Business verification service unavailable	No

Invalid registration format

422Sample dataInvalid registration format

{
  "success": false,
  "response_code": 422,
  "message": "Validation failed",
  "country": "ke",
  "errors": {
    "registration_number": [
      "Company registration numbers must start with PVT, PLC, or C and include a valid suffix"
    ]
  },
  "data": null,
  "request_id": "550e8400-e29b-41d4-a716-446655440010"
}

Business not found

404Sample dataBusiness not found

{
  "success": false,
  "response_code": 404,
  "message": "Business not found",
  "country": "ke",
  "data": null,
  "request_id": "550e8400-e29b-41d4-a716-446655440011"
}

Set {{baseUrl}} to https://api.peleza.com (production) or https://sandbox.peleza.com (sandbox). Authenticated calls need a Bearer token from POST /api/v1/oauth/token.