Quickstart

Five-call curl happy path for the Partner API.

Get a test key, set your base URL, and run the five-call happy path.

Base URL

https://{host}/api/v1/{tenant_slug}/partner/v1

Examples:

• https://app.cladfy.com/api/v1/acme/partner/v1

Set {host} to your Cladfy API host if you use a custom domain or staging environment.

Authentication

Send your key on every request:

HTTP

X-API-Key: clfy_test_xxxxxxxx

Keys are created in Admin → Developers → API Keys. Prefer a test key while exploring.

Key prefix	Behavior
clfy_test_	Sandbox / deterministic fake data, even on the production host. No real ledger or payment side effects.
clfy_live_	Real tenant data and mutations (soft-delete + audit).

Never embed keys in browsers, mobile apps, or public repos.

Scopes: Write flows (POST /clients, POST /loans, POST /repayments) need * or matching write scopes. A read-only test key (e.g. loans:read only) will return 403. Use Admin → Developers to create a full-scope key, or run external/sample-apps/bootstrap_keys.py for lab keys.

1. Ping

Bash

curl -sS -H "X-API-Key: $API_KEY" \
  "$BASE/ping"

Expect code: success and an echo of the key environment (test or live).

2. Me

Bash

curl -sS -H "X-API-Key: $API_KEY" \
  "$BASE/me"

Returns tenant slug, key scopes, and environment. Never returns the secret itself.

3. Create a client

Bash

curl -sS -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ada",
    "last_name": "Lovelace",
    "phone": "[phone]",
    "gender": "female",
    "national_id": "12345678",
    "country": "KE",
    "id_issuing_country": "KE",
    "email": "[email protected]"
  }' \
  "$BASE/clients"

Save data.id as CLIENT_ID.

4. Create a loan

With a test key, use the sandbox product UUID 00000000-0000-4000-8000-000000000030 (also returned by GET /loans/products).
With a live key, pick a product_id from GET /loans/products.

Bash

curl -sS -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d "{
    \"client_id\": \"$CLIENT_ID\",
    \"product_id\": \"$PRODUCT_ID\",
    \"applied_amount\": 10000,
    \"term_days\": 180,
    \"purpose\": \"Working capital\"
  }" \
  "$BASE/loans"

Save data.id as LOAN_ID. With a test key, status transitions are simulated.

5. Post a repayment

Bash

curl -sS -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d "{
    \"loan_id\": \"$LOAN_ID\",
    \"client_id\": \"$CLIENT_ID\",
    \"amount\": 500,
    \"payment_method\": \"cash\"
  }" \
  "$BASE/repayments"

Live repayments require a disbursed loan. Approve and disburse via staff/admin workflows first.

Response envelope

All Partner responses follow a stable envelope:

JSON

{
  "code": "success",
  "message": "Success",
  "request_id": "…",
  "data": { }
}

Use request_id when contacting support.

Next steps

• Read the Integration guide: step-by-step onboarding with Python, Node.js, and JavaScript examples
• Import external/postman/01-quickstart.postman_collection.json
• Read Client portal for borrower/self-service flows
• Run the integration lab: external/sample-apps/ (make partner-lab)