Sarafi API
Sarafi is a neutral credit intelligence layer for Nigerian digital lenders. Before disbursing, call the check endpoint with an applicant's BVN to find out whether they have active loans or recorded defaults at other lenders in the network.
The API is a standard REST interface. All requests and responses use JSON. All endpoints are served over HTTPS at:
The API is currently in a closed pilot. To obtain an API key, contact hello@sarafi.ng.
Authentication
All endpoints require an API key passed in the Authorization header
as a Bearer token. Your API key is issued when you join the pilot programme.
Your API key carries full access to your account. Never expose it in client-side code, public repositories, or logs.
Request header
| Header | Value |
|---|---|
| Authorization | Bearer sarafi_your_api_key_here |
If the key is missing or invalid, the API returns 401 Unauthorized.
If your account is suspended, it returns 403 Forbidden.
BVN Privacy
You send raw BVN numbers to the API. Sarafi hashes every BVN using SHA-256 with a secret pepper immediately on receipt — the raw number never enters the database. This means Sarafi cannot reveal BVN numbers it does not store.
You can verify this independently: hash any BVN you submitted and compare it
to the bvn_hash returned in the report response. The algorithm
is SHA-256(SECRET_KEY + ":" + bvn).
When you query /v1/check, you receive only a signal derived from
aggregate network flags. The identities of lenders who submitted those flags
are never returned.
Errors
All errors return a JSON object with an error field and an
optional detail field describing the problem.
detail field for specifics.Check a BVN
Submit an applicant's BVN before disbursing. Sarafi checks it against every active flag in the network and returns a risk signal. This is the core product endpoint — call it once per loan application, before funds are released.
The response tells you whether the BVN is flagged, how many flags exist, whether any flag is an active loan or a recorded default. You make the final lending decision.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| bvn | string | Required | The applicant's 11-digit Bank Verification Number. Must be exactly 11 numeric digits. |
Response fields
| Field | Type | Description |
|---|---|---|
| is_flaggedboolean | True if this BVN has one or more active flags in the network. | |
| flag_countinteger | Total number of active flags across all lenders in the network. | |
| lender_countinteger | Number of distinct lenders who have submitted active flags for this BVN. A borrower flagged by multiple lenders independently carries more weight than multiple flags from the same lender. | |
| has_active_loanboolean | True if this BVN has an active loan recorded elsewhere in the network right now. | |
| has_defaultboolean | True if this BVN has a recorded default in the network. | |
| resolved_loansinteger | Count of active_loan flags that have been resolved (repaid) for this BVN across the network. A positive creditworthiness signal. |
|
| days_since_last_flaginteger | null | Number of days since the most recent active flag was created. Null if the BVN has no active flags. | |
| checked_atstring | ISO 8601 timestamp of when this check was performed (UTC). |
Report a flag
Submit a BVN flag to the network. Call this when you disburse a new loan or identify a defaulter.
The reason field is stored for your internal records only.
It is never returned to other lenders through the API.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| bvn | string | Required | The 11-digit BVN of the borrower being reported. |
| record_type | string | Required | active_loan — borrower has an open loan with you now. defaulter — borrower has failed to repay. |
| reason | string | Optional | Internal note. Max 500 characters. Never shared with other lenders. |
| expires_at | string | Required for active_loan | ISO 8601 datetime (UTC). Required for active_loan — set to the loan term end date so the flag clears automatically. Optional for defaulter — Sarafi sets an automatic expiry based on the borrower's history (18 months for a first default, 36 months for repeat defaulters). |
Response fields
| Field | Type | Description |
|---|---|---|
| record_idstring | Unique identifier for this specific flag. Can be used for precise single-flag resolution via DELETE /v1/report/{record_id}. |
|
| bvn_hashstring | The SHA-256 hash of the BVN stored. Confirms the raw BVN was not stored. | |
| record_typestring | The type of flag recorded: active_loan or defaulter. |
|
| expires_atstring | When this flag will auto-expire. For active_loan, this is what you provided. For defaulter, this is the server-computed expiry. |
|
| created_atstring | ISO 8601 timestamp of when the flag was recorded (UTC). |
Resolve flags by BVN
Resolve your active flags for a BVN when a loan is repaid. Pass the borrower's
BVN directly — you do not need to retrieve the record_id from
when the flag was originally submitted.
Optionally pass record_type to resolve only flags of that type.
If omitted, all your active flags for this BVN are resolved. You can only
resolve flags that your account submitted.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| bvn | string | Required | The 11-digit BVN whose flags you want to resolve. |
| record_type | string | Optional | If provided, only resolve flags of this type (active_loan or defaulter). If omitted, all your active flags for this BVN are resolved. |
Response fields
| Field | Type | Description |
|---|---|---|
| resolved_countinteger | Number of flags resolved in this call. | |
| bvn_hashstring | Hash of the BVN that was resolved. | |
| resolved_atstring | ISO 8601 timestamp of when the flags were resolved (UTC). |
To resolve a single specific flag by its record_id, use DELETE /v1/report/{record_id} instead. This is useful when a BVN has multiple active flags and you only want to clear one.
Health check
Returns 200 OK if the API is operational. No authentication required.
Use this endpoint to monitor uptime or verify connectivity before making
authenticated calls.