curl --request POST \
--url https://sandbox.api.afriex.com/api/v1/sme-registration \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"step": "INITIATE",
"data": {
"mobile": "254712345678",
"email": "admin@company.co.ke",
"businessType": 2
}
}
'{
"data": {
"onboardingRequestId": "<string>",
"step": "INITIATE",
"status": "OTP_PENDING",
"nextStep": "CONFIRM_OTP",
"expiresAt": "2023-11-07T05:31:56Z"
}
}{
"code": "<string>",
"error": "<string>",
"details": {
"errorMessage": "<string>",
"friendlyMessage": "<string>",
"data": {
"customerId": "<string>"
}
}
}{
"code": "<string>",
"error": "<string>",
"details": {
"errorMessage": "<string>",
"friendlyMessage": "<string>",
"data": {
"customerId": "<string>"
}
}
}Register SME
Registers a business as its own SME so that dedicated virtual accounts are issued under the business’s own legal entity rather than the shared default. The flow is stateful and driven by this single endpoint: the step field selects the payload carried in data. Call the steps in order — INITIATE (triggers a one-time passcode to the supplied mobile number), CONFIRM_OTP, then SUBMIT (company details, directors and documents). Upload each document first via POST /api/v1/media/url and pass the returned object keys in the SUBMIT payload. Requires an API key with admin permission.
curl --request POST \
--url https://sandbox.api.afriex.com/api/v1/sme-registration \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"step": "INITIATE",
"data": {
"mobile": "254712345678",
"email": "admin@company.co.ke",
"businessType": 2
}
}
'{
"data": {
"onboardingRequestId": "<string>",
"step": "INITIATE",
"status": "OTP_PENDING",
"nextStep": "CONFIRM_OTP",
"expiresAt": "2023-11-07T05:31:56Z"
}
}{
"code": "<string>",
"error": "<string>",
"details": {
"errorMessage": "<string>",
"friendlyMessage": "<string>",
"data": {
"customerId": "<string>"
}
}
}{
"code": "<string>",
"error": "<string>",
"details": {
"errorMessage": "<string>",
"friendlyMessage": "<string>",
"data": {
"customerId": "<string>"
}
}
}step field selects which payload shape goes in data.
businessType must be 2 in the INITIATE step.Flow
INITIATE
mobile, email, and businessType. Afriex creates an onboarding request, returns an onboardingRequestId, and sends a one-time passcode to the supplied mobile number.CONFIRM_OTP
onboardingRequestId from step 1 and the 6-digit otp the customer received.SUBMIT
directors[], and optional organizationShareholders[] / media[]. Every file field is an object key returned by Generate Upload URL. Upload each file first, then reference the returned key here.status: OTP_PENDING after INITIATE, DETAILS_PENDING after CONFIRM_OTP, and SUBMITTED after SUBMIT. The nextStep field tells you what to call next; expiresAt is the deadline for that step (OTP window after INITIATE, submit window after CONFIRM_OTP).Mobile number format
Every mobile number, the applicant’s onINITIATE and each director’s on SUBMIT, must be a valid Kenyan number. Any of these forms is accepted and normalised to E.164:
| Format | Example |
|---|---|
E.164 with + | +254712345678 |
International without + | 254712345678 |
| National with leading zero | 0712345678 |
| National without leading zero | 712345678 |
422. Directors do not need a countryCode, it is derived from the number, and is ignored if you send one.
Once submitted, poll Get SME Registration Status for the review outcome. Dedicated KES virtual accounts under your entity are issued only after the review reaches APPROVED.Authorizations
Static business API key issued from the dashboard. A business can provision multiple API keys, each scoped to a configurable set of permissions (e.g. read transactions, create deposits, etc). Permissions are chosen per key at creation time in the dashboard and may be revoked by deleting the key. Requests made with a key that does not include the permission required by the target endpoint will be rejected with a 403 Forbidden response; an unrecognised, malformed or revoked key returns 401 Unauthorized. Manage your keys and their permissions under Developer → API keys in the dashboard.
Headers
API version in ISO 8601 format (e.g. 2025-12-28). Defaults to latest stable.
Body
Selects the payload shape carried in data.
INITIATE, CONFIRM_OTP, SUBMIT Step-specific payload. INITIATE: mobile, email, businessType (must be 2 — only Limited Liability Companies are supported at this time). CONFIRM_OTP: onboardingRequestId, otp. SUBMIT: company details, directors[], and optional organizationShareholders[] / media[], where every file field is an object key returned by POST /api/v1/media/url.
Every mobile number (the applicant's on INITIATE and each director's on SUBMIT) must be a valid Kenyan number. Any of 254712345678, +254712345678, 0712345678 or 712345678 is accepted and normalised to E.164; a number that is not Kenyan is rejected with 422. Directors do not need a countryCode: it is derived from the number, and ignored if sent.
Response
Step processed successfully.
Show child attributes
Show child attributes