API Documentation - Readiwork

Authentication

All API requests require an API key passed in the X-API-Key header. Get your API key by contacting us.

# Include in every request
X-API-Key: rw_live_your_api_key_here
Content-Type: application/json

Use rw_test_ prefixed keys for sandbox testing. Sandbox calls return realistic mock data and are not billed.

Base URL

All API endpoints are relative to the base URL:

https://readi.work/api/v1

Error Handling

Errors return a JSON object with success: false and a descriptive message:

{
  "success": false,
  "error": "invalid_id",
  "message": "National ID not found in registry"
}

Rate Limits

Standard accounts: 60 requests per minute. Exceeding the limit returns HTTP 429. Enterprise accounts have higher limits — contact us for custom rates.

Identity Verification

Verify a National ID against the Kenya IPRS registry via Metropol CRB.

POST /verify/identity Verify National ID

Request Body

Parameter	Type	Required	Description
`national_id`	string	required	6–10 digit Kenyan National ID number

Example Request

curl -X POST https://readi.work/api/v1/verify/identity \
  -H "X-API-Key: rw_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"national_id": "12345678"}'

Example Response

{
  "success": true,
  "data": {
    "first_name": "JANE",
    "other_name": "WANJIKU",
    "last_name": "KAMAU",
    "date_of_birth": "1990-05-15",
    "gender": "F",
    "citizenship": "Kenyan",
    "is_valid": true
  },
  "credits_used": 199
}

CRB Blacklist Check

Check if a National ID is listed for unpaid loans at Metropol CRB.

POST /crb/blacklist Check CRB listing status

Request Body

Parameter	Type	Required	Description
`national_id`	string	required	6–10 digit Kenyan National ID number

Example Response

{
  "success": true,
  "data": {
    "is_listed": false,
    "delinquency_code": "001",
    "total_outstanding": 0,
    "npa_accounts": 0
  },
  "credits_used": 249
}

Credit Score

Retrieve a borrower's credit score (200–900 scale) with historical comparatives.

POST /crb/score Get credit score

Example Response

{
  "success": true,
  "data": {
    "credit_score": 720,
    "score_band": "Good",
    "ppi": "M2",
    "probability_of_default": "8.2%",
    "score_3m": 710,
    "score_6m": 695,
    "score_12m": 680
  },
  "credits_used": 299
}

Loan Eligibility

Combined identity verification + CRB blacklist check in one call. Returns a single eligibility verdict.

POST /check/eligibility Check loan eligibility

Example Response

{
  "success": true,
  "data": {
    "eligible": true,
    "verdict": "ELIGIBLE",
    "identity_verified": true,
    "crb_listed": false,
    "full_name": "JANE WANJIKU KAMAU"
  },
  "credits_used": 349
}

Full Credit Report

Retrieve a comprehensive credit report including all accounts, repayment history, sector data, and institutions.

POST /crb/report Full credit report

Returns identity data, credit score, all loan accounts, sector performance, reporting institutions, and credit events. See pricing page for report variants and costs.

HTTP Response Codes

Code	Meaning
200	Success — check completed and result returned
400	Bad request — invalid or missing parameters
401	Unauthorized — invalid or missing API key
402	Insufficient credits — top up your balance
404	Not found — National ID not found in registry
429	Too many requests — rate limit exceeded
500	Server error — contact support if this persists

Pricing

API calls deduct credits from your balance. See the full pricing page for all rates. For questions or enterprise pricing, contact us.