Integration guide

Step-by-step onboarding: get a test key, verify connectivity, run the sandbox happy path (client → loan → repayment), then go live.

For runnable starters see Code examples.

Step 0: Prerequisites

A Cladfy tenant slug (e.g. acme) and staff access to Admin → Developers.
A server-side integration. Never embed API keys in browsers, mobile apps, or public repos.

Step 1: Create a test API key

Sign in as an admin → Admin → Developers → API Keys.
Create a test key with * scopes (or at least clients:write, loans:write, repayments:write).
Copy the secret once; it is shown only at creation or regenerate.

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).

Write flows return 403 on read-only keys. Details: Authentication, Test vs live.

Step 2: Configure your environment

Variable	Example
`BASE_URL`	`https://app.cladfy.com`
`TENANT_SLUG`	`acme`
`CLFY_TEST_KEY`	`clfy_test_…`

Partner base URL: {BASE_URL}/api/v1/{TENANT_SLUG}/partner/v1

Every request sends X-API-Key (and Content-Type: application/json on POST/PATCH).

export BASE_URL=https://app.cladfy.com
export TENANT_SLUG=acme
export API_KEY=clfy_test_xxxxxxxx
export PARTNER_BASE="$BASE_URL/api/v1/$TENANT_SLUG/partner/v1"

Step 3: Verify connectivity

curl -sS -H "X-API-Key: $API_KEY" "$PARTNER_BASE/ping"
curl -sS -H "X-API-Key: $API_KEY" "$PARTNER_BASE/me"

Confirm environment: test. Language clients unwrap the response envelope automatically — see Code examples.

Step 4: Response envelope

{
  "code": "success",
  "message": "Success",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {}
}

Read payloads from data. Log request_id when contacting support. Typical HTTP codes: 401 invalid key, 403 wrong tenant/scope, 400 validation, 404 missing resource.

Step 5: Create a client

Save data.id as CLIENT_ID.

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

Step 6: Create a loan

Test keys: use sandbox product 00000000-0000-4000-8000-000000000030.
Live keys: pick product_id from GET /loans/products. Save data.id as LOAN_ID.

export PRODUCT_ID=00000000-0000-4000-8000-000000000030

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\"
  }" \
  "$PARTNER_BASE/loans"

Step 7: Post a repayment

Sandbox loans accept simulated repayments immediately. Live repayments need a disbursed loan (staff approve/disburse first).

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\"
  }" \
  "$PARTNER_BASE/repayments"

Step 8: Go live

Create a least-privilege clfy_live_* key.
Confirm GET /ping returns environment: live.
Use real product IDs from GET /loans/products.
Send Idempotency-Key on money-moving POSTs when retrying.
Borrower self-service: Client portal.

Code examples — Python / Node / JavaScript starters
Quickstart — five-call curl smoke test
Integration lab: external/sample-apps/ (make partner-lab)