> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capcells.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Your first loan in the sandbox: a key, a product, a client, a quote, an issued loan, and the money reported against it.
Six calls take an empty sandbox Tenancy to an issued Loan with its first instalment settled.
At the end you hold a Loan on record, the Schedule the borrower repays it over, and one instalment reported as paid. Nothing here is real money: a sandbox Tenancy owes nobody, and every call is safe to repeat.
The walk stays in one shell. If a term in it is new, [Concepts](/getting-started/concepts) defines it, and no definition is repeated here.
## Prerequisites
Two things exist before the first call, and the walk creates everything else.
| Requirement | Value |
| ------------ | ----------------------------------------------------------------------------------- |
| Tenancy kind | `sandbox`: its records stand for nothing, and every operation is permitted. |
| Credential | A key of `write` scope for that Tenancy, minted by an administrator at the Console. |
What each kind permits is on [Sandbox and live](/getting-started/environments). The objects the calls create are defined on [Concepts](/getting-started/concepts), and no field table is reproduced here.
Every call goes to `https://api.capcells.com`, which stops before `/v1`. Snippets read two shell variables: `$TENANT_ID` names your Tenancy, and `$CAPCELLS_API_KEY` carries the key, presented as a bearer token.
## Issue a Loan
Four calls turn terms into an agreement on record.
Create the terms you sell. The frame of the `instalment` Archetype decides which fields `values` must carry, and refuses any field it does not admit by name.
```bash Create the configuration theme={null}
curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/product-configurations" \
-H "Authorization: Bearer $CAPCELLS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"archetype": "instalment",
"values": {
"principal_min": { "minor_units": 100000, "currency": "MXN" },
"principal_max": { "minor_units": 2000000, "currency": "MXN" },
"rate_min": "36",
"rate_max": "60",
"penalty_rate_min": "36",
"penalty_rate_max": "90",
"day_count_basis": "actual_360",
"schedule": { "kind": "anchored_monthly" },
"terms": [6, 12, 18],
"origination_fee": { "minor_units": 25000, "currency": "MXN" },
"late_fee": { "minor_units": 15000, "currency": "MXN" }
}
}'
```
```json Response theme={null}
{
"id": "d57bfbfb-7703-4d87-8a0e-94d4200d3645",
"tenant_id": "t-0001",
"archetype": "instalment",
"created_at": "2026-08-18T22:26:41.407349Z",
"version": 1,
"values": {
"principal_min": { "minor_units": 100000, "currency": "MXN" },
"principal_max": { "minor_units": 2000000, "currency": "MXN" },
"rate_min": "36",
"rate_max": "60",
"penalty_rate_min": "36",
"penalty_rate_max": "90",
"day_count_basis": "actual_360",
"origination_fee": { "minor_units": 25000, "currency": "MXN" },
"late_fee": { "minor_units": 15000, "currency": "MXN" },
"terms": [6, 12, 18],
"schedule": { "kind": "anchored_monthly" }
}
}
```
The answer is `201`: `version` is `1`, and `id` is the value an issuance names as its `configuration_id`.
Register the identifier the Loan will name. A Client carries an identifier, an optional label and nothing else. A field for a name, a birth date or a document is refused by name.
```bash Register the Client theme={null}
curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/clients" \
-H "Authorization: Bearer $CAPCELLS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "id": "c-0001", "label": "contract-0001" }'
```
```json Response theme={null}
{
"id": "c-0001",
"tenant_id": "t-0001",
"label": "contract-0001",
"created_at": "2026-08-18T22:26:41.410593Z"
}
```
The answer is `201`, and the issuance body names this `id` as its `client_id`.
Quote the agreement before recording it. A preview reads the body an issuance takes, without its `reference`, and records nothing. The wire form of every value is on [Model](/getting-started/model).
Every figure here comes from one Loan: MXN 8,000.00 over 12 Periods at `"45.5"` per year, anchored `2026-03-02` in `MX`. It runs on the configuration above, under its `actual_360` day count. Its `penalty_rate` is `"60"`, and tax runs at 16% on interest, fee, penalty and late fee.
```bash Preview the Loan theme={null}
curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/loans/preview" \
-H "Authorization: Bearer $CAPCELLS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_id": "c-0001",
"configuration_id": "d57bfbfb-7703-4d87-8a0e-94d4200d3645",
"configuration_version": 1,
"principal": { "minor_units": 800000, "currency": "MXN" },
"term_periods": 12,
"rate": "45.5",
"penalty_rate": "60",
"anchor": "2026-03-02",
"jurisdiction": "MX",
"tax": { "rate": "16", "on": ["interest", "fee", "penalty", "late_fee"] }
}'
```
```json Response theme={null}
{
"configuration": { "id": "d57bfbfb-7703-4d87-8a0e-94d4200d3645", "version": 1 },
"terms": {
"client_id": "c-0001",
"principal": { "minor_units": 800000, "currency": "MXN" },
"term_periods": 12,
"rate": "45.5",
"penalty_rate": "60",
"anchor": "2026-03-02",
"jurisdiction": "MX",
"tax": { "rate": "16", "on": ["interest", "fee", "penalty", "late_fee"] }
},
"periods": [
{
"index": 1,
"scheduled_on": "2026-04-02",
"due_on": "2026-04-06",
"principal": { "minor_units": 51291, "currency": "MXN" },
"interest": { "minor_units": 31344, "currency": "MXN" },
"fee": { "minor_units": 2083, "currency": "MXN" },
"tax": { "minor_units": 5348, "currency": "MXN" },
"payment": { "minor_units": 90066, "currency": "MXN" }
},
{
"index": 2,
"scheduled_on": "2026-05-02",
"due_on": "2026-05-04",
"principal": { "minor_units": 54720, "currency": "MXN" },
"interest": { "minor_units": 28388, "currency": "MXN" },
"fee": { "minor_units": 2083, "currency": "MXN" },
"tax": { "minor_units": 4875, "currency": "MXN" },
"payment": { "minor_units": 90066, "currency": "MXN" }
},
…
{
"index": 12,
"scheduled_on": "2027-03-02",
"due_on": "2027-03-02",
"principal": { "minor_units": 84204, "currency": "MXN" },
"interest": { "minor_units": 2980, "currency": "MXN" },
"fee": { "minor_units": 2084, "currency": "MXN" },
"tax": { "minor_units": 810, "currency": "MXN" },
"payment": { "minor_units": 90078, "currency": "MXN" }
}
],
"disclosure": { "jurisdiction": "MX", "figure": "64.9" },
"regime": {
"penalty_rate": "60",
"late_fee": { "minor_units": 15000, "currency": "MXN" },
"grace_days": 0,
"penalty_base": "overdue_principal",
"capitalises": false,
"acceleration": { "forbidden": false, "missed_periods": 3, "notice_days": 15 }
}
}
```
Nine of the twelve period rows are cut above; `disclosure.figure` carries the CAT, and nothing was recorded. The quoted `payment` of 90066 (MXN 900.66) rounds down to a whole centavo; the final Period's 90078 absorbs the 12-centavo residual.
Issue under the same body, now carrying its `reference`: your own identifier for this agreement, unique within the Tenancy.
```bash Issue the Loan theme={null}
curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/loans" \
-H "Authorization: Bearer $CAPCELLS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reference": "loan-0001",
"client_id": "c-0001",
"configuration_id": "d57bfbfb-7703-4d87-8a0e-94d4200d3645",
"configuration_version": 1,
"principal": { "minor_units": 800000, "currency": "MXN" },
"term_periods": 12,
"rate": "45.5",
"penalty_rate": "60",
"anchor": "2026-03-02",
"jurisdiction": "MX",
"tax": { "rate": "16", "on": ["interest", "fee", "penalty", "late_fee"] }
}'
```
```json Response theme={null}
{
"id": "7771aef0-9e65-4a0a-a902-aab4e970d33f",
"tenant_id": "t-0001",
"state": "active",
"created_at": "2026-08-18T22:26:41.420114Z",
…
}
```
The answer is `201` and `state` answers `active`; the body continues with the recorded events and the preview's document, priced once at issuance. A retry carrying the same `reference` and the same statements answers `200` and this same Loan.
Preview and issue read one body. A preview ignores `reference` and records nothing; an issuance retried under its `reference` answers `200` with the Loan on file, not a second Loan.
## Report the money
You hold the funds: money is reported as a Receipt against the Client, and every figure after it is derived.
Report the first instalment as it arrives. Period 1 is scheduled on `2026-04-02`, a non-working day in `MX`, so collection moved to `2026-04-06`, the value date the borrower pays on.
```bash Report the Receipt theme={null}
curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/receipts" \
-H "Authorization: Bearer $CAPCELLS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reference": "receipt-0001",
"client_id": "c-0001",
"amount": { "minor_units": 90066, "currency": "MXN" },
"value_date": "2026-04-06"
}'
```
```json Response theme={null}
{
"receipt": { … },
"rule": {
"jurisdiction": "MX",
"charge_order": ["penalty", "late_fee", "fee", "interest", "principal"],
"period_order": "oldest first",
"undesignated_loans": "most_onerous_then_oldest"
},
"settled": { "minor_units": 90066, "currency": "MXN" },
"residual": { "minor_units": 0, "currency": "MXN" },
"excess": { "minor_units": 0, "currency": "MXN" },
"loans": [
{
"loan_id": "7771aef0-9e65-4a0a-a902-aab4e970d33f",
"reference": "loan-0001",
"chosen_by": "default_rule",
"settled": { "minor_units": 90066, "currency": "MXN" },
"prepayment": { "minor_units": 0, "currency": "MXN" },
"residual": { "minor_units": 0, "currency": "MXN" },
"owed_back": { "minor_units": 0, "currency": "MXN" },
"periods": [
{
"index": 1,
"due_on": "2026-04-06",
"total": { "minor_units": 90066, "currency": "MXN" },
"charges": [
{ "charge": "fee", "amount": { "minor_units": 2083, "currency": "MXN" }, "tax": { "minor_units": 333, "currency": "MXN" }, "total": { "minor_units": 2416, "currency": "MXN" } },
{ "charge": "interest", "amount": { "minor_units": 31344, "currency": "MXN" }, "tax": { "minor_units": 5015, "currency": "MXN" }, "total": { "minor_units": 36359, "currency": "MXN" } },
{ "charge": "principal", "amount": { "minor_units": 51291, "currency": "MXN" }, "tax": { "minor_units": 0, "currency": "MXN" }, "total": { "minor_units": 51291, "currency": "MXN" } }
]
}
]
}
],
"anomalies": []
}
```
The answer is `201`, `settled` is the whole 90066, and `excess` is zero. Inside Period 1 the money ran fee, then interest, then principal, each charge with its tax beside it. The cut `receipt` block echoes the report, with the Platform's `id` and `reported_at` added.
Ask what the Client owes, as of a date you name: the Platform supplies no today, and a read without `on` is refused `422`. The route answers per Loan: what is overdue, the next instalment, the payoff, and what an unnamed amount would do.
```bash Read the payment options theme={null}
curl "https://api.capcells.com/v1/tenants/$TENANT_ID/clients/c-0001/payment-options?on=2026-04-13" \
-H "Authorization: Bearer $CAPCELLS_API_KEY"
```
```json Response theme={null}
{
"client_id": "c-0001",
"on": "2026-04-13",
"loans": [
{
"loan_id": "7771aef0-9e65-4a0a-a902-aab4e970d33f",
"reference": "loan-0001",
"overdue": { "total": { "minor_units": 0, "currency": "MXN" }, "charges": [] },
"instalment": {
"index": 2,
"scheduled_on": "2026-05-02",
"due_on": "2026-05-04",
"owed": { "total": { "minor_units": 90066, "currency": "MXN" }, "charges": [ … ] },
"actionable_from": "2026-05-04",
"requires_overdue_settled": false
},
"payoff": {
"owed": { "total": { "minor_units": 787367, "currency": "MXN" }, "charges": [ … ] },
"actionable_on": "2026-04-13",
"requires_payoff_intent": true,
"requires_designation": false
},
"any_other_amount": {
"treatment": "reduces_principal",
"description": "everything overdue is settled first; what remains is applied exclusively to outstanding principal under the statutory rule on early payment, which keeps the term and lowers the payments that follow"
},
"anomalies": []
}
]
}
```
The two cut `charges` arrays split each total by fee, interest and principal, as on the Receipt above. `overdue.total` is zero, and `instalment` names Period 2, due `2026-05-04`, at the same 90066. `payoff.owed.total` answers 787367 (MXN 7,873.67) for `2026-04-13`: a payoff is stated by `payoff_intent` on its Receipt, never inferred from the amount.