HomeTrust API reference

Authenticate every request with your secret key in the x-api-key header. Keys look like ht_live_… and are tied to your employer account and wallet.

x-api-key: ht_live_3f9b0c1e8a7d4b2c9e6f5a1d0b8c7e2f

• Send and receive JSON with Content-Type: application/json. Keys are camelCase.
• Money values are integers in Rwandan francs (RWF). Dates are ISO 8601 in UTC.
• List endpoints return { items, total, page, pageSize }. Use ?page=1&pageSize=20.
• Charges are deducted from your prepaid wallet at the moment of the request.

Verify an ID number against the national registry. Provide a selfie URL (from the uploads endpoint) to add a face match.

curl -X POST https://hometrust-api.bahafrica.com/api/instant-checks \
  -H "x-api-key: ht_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "idType": "national_id", "idNumber": "1199080012345678", "firstName": "Claudine", "lastName": "Uwase", "dob": "1990-04-12" }'

HTTP/1.1 201 Created
{
  "id": "ic_8f2a1c",
  "idType": "national_id",
  "idNumber": "1199080012345678",
  "firstName": "Claudine",
  "lastName": "Uwase",
  "dob": "1990-04-12",
  "selfieUrl": null,
  "status": "verified",
  "result": {
    "registryFound": true,
    "registryName": "UWASE Claudine",
    "registryDob": "1990-04-12",
    "registryGender": "female",
    "nameMatch": 98,
    "dobMatch": true,
    "faceMatch": null,
    "watchlistMatches": 0
  },
  "price": 500,
  "createdAt": "2026-10-27T09:14:03.000Z"
}

status is verified, not_found or mismatch. nameMatch and faceMatch are 0–100 scores.

A role is a job opening with a package of checks. Price per applicant is computed by the server from the package, add-ons and number of guarantors/references.

Invite 1–50 candidates at once. The total (pricePerApplicant × n) is debited from your wallet in a single transaction; links expire after 7 days.

Applicants move through invited → in_progress → submitted → completed. The detail endpoint includes the full verification report.

A single registry lookup with optional selfie face match and watchlist screen. Each call costs RWF 500.

Search verified HomeTrust Protect incidents and report new ones. Only verified or resolved incidents are returned by search.

Read prices and packages, and check your balance before large invite batches.

Create a role

packageId is one of basic, standard, premium, custom. For custom, addOns is the full list of checks.

POST /api/roles
x-api-key: ht_live_YOUR_SECRET_KEY

{
  "title": "Live-in nanny — Kimihurura",
  "category": "domestic",
  "roleType": "nanny",
  "packageId": "premium",
  "addOns": ["health"],
  "guarantorsRequired": 2,
  "referencesRequired": 1,
  "location": "Gasabo, Kigali"
}

Invite candidates

POST /api/roles/rl_51c9/invites
x-api-key: ht_live_YOUR_SECRET_KEY

{
  "channel": "sms",
  "applicants": [
    { "firstName": "Claudine", "lastName": "Uwase", "phone": "+250788123456" },
    { "firstName": "Jean", "lastName": "Habimana", "email": "jean@example.rw" }
  ]
}

Search the watchlist

POST /api/watchlist/search
x-api-key: ht_live_YOUR_SECRET_KEY

{ "idNumber": "1199080012345678" }

HTTP/1.1 200 OK
{
  "matches": [
    {
      "incidentId": "in_7a20",
      "incidentType": "theft",
      "incidentDate": "2026-03-14",
      "district": "Gasabo",
      "status": "verified",
      "matchedOn": ["id_number"],
      "confidence": 100
    }
  ]
}

Errors use standard HTTP status codes and a consistent body. details is optional and, for validation errors, lists the offending fields.

HTTP/1.1 402 Payment Required
{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Your wallet balance is too low for this request.",
    "details": { "required": 39000, "balance": 12000 }
  }
}

In sandbox mode (GET /config returns "sandbox": true) the national registry is simulated. Use these rules to test every outcome:

• ID numbers ending in 0000 are not found in the registry.
• ID numbers ending in 9999 return a different name (name mismatch).
• ID numbers ending in 8888 fail the face match.
• Any other well-formed ID is found and matches the submitted name.
• Rwandan national IDs encode birth year in digits 2–5 and gender in digit 6 (8 = male, 7 = female).

Need help? Email us via the contact page or read the Online SLA.