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

# Create a facility

> Turn an approving Decision into a standing grant a client may draw several Loans from.

This call creates a Facility from a Decision you name: a grant of one amount at one price, for one Client and one product, inside a validity window.

You state the window and nothing else. The Client, the product Configuration, the amount, the rate and the currency all come from the Decision — a grant that restated what was approved would be a grant that can disagree with it.

<Warning>
  A Facility is never edited and never deleted. It ends by its expiry passing and in no other way. There is no revocation, no freeze and no early close: the grant caps and never entitles, so a Tenancy that distrusts one stops issuing under it.
</Warning>

## Path parameters

<ParamField path="tenant_id" type="string" required>
  The Tenancy creating the grant. Another Tenancy's path answers `403`.
</ParamField>

## Body

<ParamField body="decision_id" type="string" required>
  A recorded Decision of your Tenancy whose outcome is `approve`, or a `refer` a person resolved as an approval at the [console](/authentication/console). A Decision that refused, a `refer` nobody resolved, and a `refer` resolved as a refusal grant nothing; one your Tenancy never recorded answers `404`.

  A Decision grants at most one Facility: a second from one approval is the approved exposure counted twice.
</ParamField>

<ParamField body="opens_on" type="string" required>
  The first day the grant may be drawn on, as `YYYY-MM-DD`. Inclusive.
</ParamField>

<ParamField body="expires_on" type="string" required>
  The last day the grant may be drawn on, inclusive. Not before `opens_on`, and no more than 30 days after the Decision's `bound_from` — the day its application states where that is earlier than the day it was recorded on — or, for a resolved `refer`, after the day it was resolved. A line may reach 180 days: see [below](#a-line).
</ParamField>

<ParamField body="line" type="boolean">
  Grant a line rather than a one-draw grant. Admitted only from a Decision that approved a `limit`; any other is refused `422 invalid_creation`.
</ParamField>

<ParamField body="supersedes" type="string">
  The line this line renews: a line of the same Client for the same Configuration that no other line has superseded. Refused `422 cannot_supersede` otherwise, and refused `422 invalid_creation` on a creation that is not a line.
</ParamField>

<ParamField body="context" type="object">
  Your key-value object: at most 16 keys, 64 bytes a key, 4096 bytes rendered, string values. Stored, echoed on every read, read by nothing — and part of what a repeat naming the same Decision restates.
</ParamField>

## The window is the whole of the staleness answer

Between creating a grant and any draw under it, the Platform re-reads nothing about the Client — whatever the Decision read: what you declared, the Platform's own book, or a bureau report.

So a fact that turned against the Client after the grant — an arrear taken at another lender, an income that ended — is as invisible on the last draw as it was on the first. The length of the window is the whole of the Platform's answer to that, which is why it is bounded at 30 days rather than 90.

<Info>
  The products that hold a pre-approval open this long re-pull the bureau and re-score at every drawdown. The Platform does not look again, so a window three times the precedent's, carrying strictly less evidence, would be the wrong end of that trade twice over.
</Info>

The window bounds drawing and not repayment. A Loan issued inside it may mature long after the expiry.

## A line

A line is the one grant whose headroom comes back. Its headroom is its amount less the principal still outstanding on the Loans drawn from it, so principal a receipt repays, a return unwinds or a prepayment settles is drawable again from that day, and a cancelled or voided draw gives back everything it took. A reversal takes the refill back. A written-off, accelerated or ceded draw gives back nothing: that money is lost, demanded or sold, not repaid.

Its window may reach 180 days from the Decision rather than 30, and the reason is the one above turned round: every draw from a line re-reads the Platform's own book. The Client-level guards the Configuration version states — the open-loan count, the exposure cap — are held at every draw, and a draw is refused `client_overdue` while any Loan of the Client's stands overdue, whatever the version states. A bureau is still not re-read, which is why the bound is not longer.

A line is renewed only by a new limit Decision and a new line that names it in `supersedes`. What is still drawn under the old line counts against the new one — a renewal mints no headroom — and the old line refuses draws anchored on or after the day the new line opens (`facility_superseded`).

## Response

<ResponseField name="id" type="string" required>
  The Platform's identifier for the grant. A Loan names it as `facility_id`.
</ResponseField>

<ResponseField name="client_id" type="string" required>
  The Client the Decision approved. An issuance for anybody else is refused.
</ResponseField>

<ResponseField name="configuration_id" type="string" required>
  The product the grant is for. Carried by identifier rather than by version, so a later version of the same Configuration may still be drawn under it.
</ResponseField>

<ResponseField name="decided_version" type="integer" required>
  The Configuration version the Decision was decided against. Provenance: it governs nothing at issuance.
</ResponseField>

<ResponseField name="decision_id" type="string" required>
  The Decision this was created from. Every Loan drawn under the grant records it.
</ResponseField>

<ResponseField name="amount" type="object" required>
  The Decision's approved principal, or the resolution's for a resolved `refer`, as `minor_units` and `currency`.
</ResponseField>

<ResponseField name="rate" type="object" required>
  The Decision's exact annual rate, as `numerator`, `denominator` and `quotation`, and as `percent` — the decimal percentage a Loan states. An issuance stating any other rate is refused, whatever the Configuration's corridor admits; one stating none takes this rate.
</ResponseField>

<ResponseField name="opens_on" type="string" required>
  The first day the grant may be drawn on.
</ResponseField>

<ResponseField name="expires_on" type="string" required>
  The last day the grant may be drawn on.
</ResponseField>

<ResponseField name="context" type="object">
  Your object, as the creation carried it. Absent where none was attached.
</ResponseField>

<ResponseField name="line" type="boolean">
  `true` on a line. Absent on a one-draw grant.
</ResponseField>

<ResponseField name="supersedes" type="string">
  The line this one renewed. Absent where it renewed none.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  RFC 3339 in UTC: the moment the grant was recorded.
</ResponseField>

The creation carries no headroom. Nothing has been drawn yet, and deriving it is a question the Facility read answers.

## Creating again

`201` is a grant this request created. `200` is one it found already created under that Decision, with the same window — that is how a retry after a lost response is told apart from the request that granted it.

A second creation naming a different window, or attaching a different `context`, is `409` `window_disagrees`, and the grant already recorded stands unchanged. `details.recorded_id` names it, and `details.field` reads `context` where that was the difference.

## Refusals

This route reads no query parameter.

| Status | When |
| - | - |
| `400` | The body names a field this call does not read, or states one twice |
| `403` | The key authenticates for another Tenancy, or its scope is read-only |
| `404` | Your Tenancy recorded no such Decision |
| `409` | That Decision already granted a Facility, with a different window |
| `422` | The Decision granted nothing, the window admits no day, the expiry reaches past the Platform's bound, a line was asked of a Decision that approved no limit, or `supersedes` names a line this one cannot renew |

At the Console door this is a person's act: creating a grant stands up an amount and a price that issuance will honour, so an agent credential is refused it on a live Tenancy and served it on a sandbox.

<RequestExample>
  ```bash Create theme={null}
  BODY='{
    "decision_id": "4e19e899-fa40-4047-bb33-2b2ab40f8dea",
    "opens_on": "2026-08-24",
    "expires_on": "2026-09-23"
  }'

  curl -X POST https://api.capcells.com/v1/tenants/capyplazo/facilities \
    -H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" POST /v1/tenants/capyplazo/facilities "$BODY")" \
    -H "Content-Type: application/json" \
    -d "$BODY"
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "3a156e45-e3df-4dc1-9a80-8dca3e58a0cc",
    "client_id": "client-alonso",
    "configuration_id": "9ae76f4e-2eb4-43ce-831c-f3b1aa7b5dd6",
    "decided_version": 1,
    "decision_id": "4e19e899-fa40-4047-bb33-2b2ab40f8dea",
    "amount": { "minor_units": 1000000, "currency": "MXN" },
    "rate": { "numerator": 9, "denominator": 20, "quotation": "annual nominal", "percent": "45" },
    "opens_on": "2026-08-24",
    "expires_on": "2026-09-23",
    "created_at": "2026-08-24T22:23:58.162514Z"
  }
  ```

  ```json 409 A different window theme={null}
  {
    "error": "facility: the decision already granted a different window: decision 4e19e899-fa40-4047-bb33-2b2ab40f8dea already granted a facility open from 2026-08-24 to 2026-09-23, and this creation states 2026-08-24 to 2026-09-03",
    "code": "window_disagrees"
  }
  ```

  ```json 422 Past the bound theme={null}
  {
    "error": "facility: the window reaches past the platform's bound: the window expires on 2026-09-24 and decision 4e19e899-fa40-4047-bb33-2b2ab40f8dea was taken on 2026-08-24, so the grant would stay drawable past the platform's bound of 30 days, which falls on 2026-09-23 — thirty days is the precedent's length without the precedent's re-check: the products that hold a pre-approval open this long re-pull the bureau at every drawdown, and this platform re-reads nothing about the client between the grant and the draw",
    "code": "outside_window_bound"
  }
  ```

  ```json 422 The decision granted nothing theme={null}
  {
    "error": "facility: the decision granted nothing: decision b10e4eed-d856-4683-a26d-04f6ac6816c8 was decided refuse, and only an approval grants anything",
    "code": "not_approved"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.