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@example.com",
"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>"
}
}
}{
"code": "INTERNAL_SERVER_ERROR",
"error": "It's not you, it's us, please reach out to support",
"details": {}
}{
"code": "EXTERNAL_REQUEST_ERROR",
"error": "External request error",
"details": {}
}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. Calling INITIATE again while the registration is still waiting for its passcode returns that same registration with a 200. Requires the COMPLIANCE.KYB.SUBMIT key 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@example.com",
"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>"
}
}
}{
"code": "INTERNAL_SERVER_ERROR",
"error": "It's not you, it's us, please reach out to support",
"details": {}
}{
"code": "EXTERNAL_REQUEST_ERROR",
"error": "External request error",
"details": {}
}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. Manage your keys and their permissions under Developer → API keys in the dashboard.
A request whose key does not carry the permission the target
endpoint requires is rejected with 401 Unauthorized, the same
response an unrecognised, malformed, revoked or disabled key
returns. The API does not distinguish the two cases on the wire.
See the Permissions reference for the permission each endpoint requires.
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
- INITIATE
- CONFIRM_OTP
- SUBMIT
The step field selects the payload carried in data, and it is case insensitive (submit is accepted as SUBMIT).
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