API documentation

What is available?

The currently implemented public developer resource is provider discovery. It lets an approved integration search provider profiles by supported filters. Additional resources should only be added here after the backend endpoint, authentication, permissions, rate limits and operational handling exist.

Legacy and new API policy

Account types

Charges and subscriptions

There is currently no published API subscription price or per-request charge in this implementation. We will not silently charge an API key. If KHS introduces paid API access, the applicable plan, limits, billing period, transaction/request charges and overage rules must be presented before the account is moved to that paid service.

Authentication

Create a key from Developer API. Keys currently use the providers:read scope. Store the secret only on your server. Send it as an Authorization Bearer token.

Authorization: Bearer khs_live_your_key

GET /api/v1/providers

Returns provider discovery data. Query parameters are county, town, verified=true|false, and limit. The server clamps limit to 1–50 and defaults to 20.

curl "https://backend.christech.co.ke/api/v1/providers?county=Kiambu&town=Ruiru&verified=true&limit=20"   -H "Authorization: Bearer $KHS_API_KEY"

Response

{
  "data": [
    {
      "id": "provider-id",
      "name": "Provider Name",
      "county": "Kiambu",
      "town": "Ruiru",
      "verified": true,
      "avatar_url": "https://...",
      "bio": "Provider description",
      "experience_years": 5,
      "phone": "0712345678",
      "whatsapp": "0712345678",
      "availability": "...",
      "price_range": "...",
      "verification_badge_version": "verified",
      "verified_at": "2026-10-08T10:00:00Z",
      "latitude": -1.1,
      "longitude": 36.9,
      "services": [{"id":"service-id","name":"Cleaning","category":"Cleaning"}]
    }
  ],
  "pagination": {"limit": 20, "returned": 1}
}

Provider phone/WhatsApp and location fields are sensitive integration data. Access and use must follow KHS terms, privacy requirements and the scope granted to your account.

Examples in common languages

const response = await fetch("https://backend.christech.co.ke/api/v1/providers?county=Kiambu&limit=20", {
  headers: { Authorization: `Bearer ${process.env.KHS_API_KEY}` }
});
const result = await response.json();
if (!response.ok) throw new Error(result.error || "KHS API request failed");

import os, requests
response = requests.get(
    "https://backend.christech.co.ke/api/v1/providers",
    params={"county": "Kiambu", "limit": 20},
    headers={"Authorization": "Bearer " + os.environ["KHS_API_KEY"]},
    timeout=10,
)
response.raise_for_status()
providers = response.json()["data"]

$ch = curl_init("https://backend.christech.co.ke/api/v1/providers?county=Kiambu&limit=20");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("KHS_API_KEY")],
  CURLOPT_TIMEOUT => 10,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status < 200 || $status >= 300) throw new RuntimeException("KHS API request failed");
$data = json_decode($response, true);

curl "https://backend.christech.co.ke/api/v1/providers?county=Kiambu&limit=20"   -H "Authorization: Bearer $KHS_API_KEY"

Errors and lifecycle