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>"
}
}
}{
"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>"
}
}
}{
"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 is rejected with a 401 Unauthorized response, the same response an unrecognised, malformed or revoked key returns. The API does not distinguish the two cases on the wire. Manage your keys and their permissions under Developer → API keys in the dashboard.
Headers
API version in ISO 8601 format. The only supported version is 2026-05-18, which is also the default when the header is omitted. Any other value is rejected with a 400 Bad Request.
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