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

# Ask whether a Client is barred

> Ask whether a recorded refusal currently bars a Client from re-applying, and when the bar lifts.

This call answers whether a Client is barred on a day you name, and the day the bar lifts.

A refusal decided under a cutoff band or a knockout that carries a moratorium bars the Client for that many whole days from the Decision's `bound_from`. The answer is derived from the recorded Decisions rather than stored beside the Client, so it cannot disagree with them.

<Warning>
  By default the Platform answers this question and does not enforce the answer. A barred Client's next application is decided and recorded exactly as any other. To have the Platform refuse it instead, adopt the policy with `enforce_bar: true`: the application is then refused with `409 client_barred`, naming the day the bar lifts and the refusal, and nothing is recorded.
</Warning>

## Path parameters

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

<ParamField path="client_id" type="string" required>
  The Client asked about. One your Tenancy never registered answers as unbarred: nothing was ever recorded against them here.
</ParamField>

## Query parameters

<ParamField query="on" type="string" required>
  The day the question is about, as `YYYY-MM-DD`.

  It is required and never defaulted. The Platform supplies no today, for the same reason the delinquency read does not: whether a Client is barred is a question about a day, and a caller that meant now can say which day that is.
</ParamField>

## Response

<ResponseField name="barred" type="boolean" required>
  Whether a recorded refusal bars the Client on the day asked about.
</ResponseField>

<ResponseField name="lifts_on" type="string">
  The day the bar lifts, as `YYYY-MM-DD`. Absent when nothing bars.

  Where several refusals bar a Client at once, this is the latest day any of them lifts. On the day named, nothing bars.
</ResponseField>

<ResponseField name="decision" type="string">
  The recorded refusal whose moratorium lifts last, or, where that refusal is a person's resolution of a `refer`, the decision it resolved. Absent when nothing bars.
</ResponseField>

## How the bar is counted

A refusal counting from 2026-08-24 under a band carrying 30 days bars the Client through 2026-09-22 and lifts on 2026-09-23.

| Asked about | Answer |
| - | - |
| 2026-08-29 | `barred: true`, lifting on 2026-09-23 |
| 2026-09-23 | `barred: false` |

The first day counts. That day is the application's `submitted_on` where it is earlier than the day the refusal was recorded on, and the recording day otherwise, read in the time zone the Decision froze. A refusal recorded today for an application stating 2026-01-01 lifted on 2026-01-31.

## Refusals

This route takes no body.

| Status | When |
| - | - |
| `400` | The URL carries a parameter this route does not read, states `on` twice, or leaves it present with no value |
| `403` | The key authenticates for another Tenancy |
| `422` | `on` is absent, or is not a day the Platform can read |

A read-scoped key is enough.

<RequestExample>
  ```bash Ask theme={null}
  curl "https://api.capcells.com/v1/tenants/capyplazo/credit-bar/client-alonso?on=2026-08-29" \
    -H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" GET "/v1/tenants/capyplazo/credit-bar/client-alonso?on=2026-08-29")"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Barred theme={null}
  {
    "barred": true,
    "lifts_on": "2026-09-23",
    "decision": "6a279744-0a45-45f2-a0ae-cc3e94a2af14"
  }
  ```

  ```json 200 Nothing bars theme={null}
  {
    "barred": false
  }
  ```

  ```json 422 No day given theme={null}
  {
    "error": "risk: the application cannot be decided: whether a client is barred is answered as of a day, and none was given -- there is no today the platform can supply",
    "code": "invalid_application"
  }
  ```
</ResponseExample>


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