> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clarivo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Authenticate and make your first Clarivo API call in minutes

## Before you begin

You'll need:

* A Clarivo tenant account
* OAuth2 client credentials (`client_id` and `client_secret`) from [app.clarivo.co](https://app.clarivo.co)
* The base URL for your environment: `https://ledger.clarivo.co/v1` (production) or `https://ledger.staging.clarivo.co/v1` (staging)

***

### Step 1: Get an access token

Exchange your client credentials for a bearer token using the OAuth2 client credentials flow.

```bash theme={null}
curl -X POST https://auth.example.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=hpts:payments:write hpts:balances:read hpts:ledger:read"
```

```json Response theme={null}
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

<Tip>Tokens expire after 1 hour. Cache and refresh them rather than requesting a new one for every API call.</Tip>

***

### Step 2: Verify connectivity

Check that the service is live and your network can reach it — no authentication required.

```bash theme={null}
curl https://ledger.clarivo.co/v1/health/live
```

```json Response theme={null}
{
  "status": "ok",
  "version": "1.4.2",
  "git_sha": "a3f9e12"
}
```

***

### Step 3: Post your first payment

Record a loan payment. Every POST requires an `Idempotency-Key` — choose a deterministic key that is unique per event.

```bash theme={null}
curl -X POST https://ledger.clarivo.co/v1/payments \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payment:loan_42:proc_txn_abc123" \
  -d '{
    "loan_id": "11111111-1111-1111-1111-111111111111",
    "borrower_id": "22222222-2222-2222-2222-222222222222",
    "amount_minor": "88849",
    "currency": "USD",
    "effective_at": "2026-05-01",
    "source_method": "ach",
    "external_ref": "stripe_ch_xyz123"
  }'
```

```json Response (201 Created) theme={null}
{
  "payment_event_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "journal_entry_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  "allocation": {
    "fees_minor": "500",
    "interest_minor": "10000",
    "principal_minor": "78349",
    "suspense_minor": "0"
  },
  "posted_at": "2026-05-01T12:00:00Z"
}
```

<Note>
  `amount_minor` is always expressed in the currency's minor unit as a string (e.g. cents for USD) to avoid floating-point precision issues.
</Note>

***

### Step 4: Read the loan balance

```bash theme={null}
curl "https://ledger.clarivo.co/v1/loans/11111111-1111-1111-1111-111111111111/balance" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```json Response theme={null}
{
  "loan_id": "11111111-1111-1111-1111-111111111111",
  "currency": "USD",
  "as_of_date": "2026-05-01",
  "principal_outstanding_minor": "921651",
  "interest_receivable_minor": "0",
  "fees_receivable_minor": "0",
  "total_exposure_minor": "921651"
}
```

***

## Next steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="terminal" href="/api-reference/introduction">
    Full reference for all endpoints with request/response schemas.
  </Card>

  <Card title="Idempotency" icon="rotate" href="/api-reference/introduction">
    Learn the idempotency contract and recommended key formats.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/api-reference/introduction">
    All errors follow RFC 7807 Problem Details format.
  </Card>

  <Card title="Local development" icon="code" href="/development">
    Run these docs locally to contribute or preview changes.
  </Card>
</CardGroup>