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

# Register a client

> Register your identifier for a borrower: an id, an optional label, and no field for a person.

A Client is registered before the first Loan names it. The registry holds your identifier, an optional label, and nothing else — a field for a name, a birth date or a document is refused by name. [Clients](/lending/clients) carries the registry's rules in full.

## Path parameters

<ParamField path="tenant_id" type="string" required>
  The Tenancy registering.
</ParamField>

## Body

<ParamField body="id" type="string" required>
  Your identifier for the borrower: 1–64 characters of `a–z A–Z 0–9 - _`. The value every Loan, Receipt and read names as `client_id`.
</ParamField>

<ParamField body="label" type="string">
  Optional, at most 200 characters — the only free text the Platform stores about a Client, read by nothing. Stated as `""` or `null` it is one refusal: a registration that carries no label states none.
</ParamField>

## Response

`201` with the registration: `id`, `tenant_id`, `created_at`, and `label` only where one was stated — an unlabelled Client answers with no `label` key at all.

Registration is idempotent under the identifier, and the comparison is exact — against what is recorded **now**, so [a correction](/api-reference/clients/correct) moves what a replay is compared against:

| The repeat | Answer |
| - | - |
| The same `id` and the same `label` | <Badge color="green">200</Badge> — the registration on file |
| The same `id`, a different `label` | <Badge color="red">409</Badge> `conflicting_registration` |
| The same `id`, the `label` omitted | <Badge color="red">409</Badge> — omitting a label on a retry counts as stating none, and dropping a label is a disagreement |

A registration is never deleted: the storage holds no delete, and an identifier once registered stays resolvable for as long as its record needs naming.

<RequestExample>
  ```bash Register theme={null}
  BODY='{ "id": "c-0001", "label": "contract-0001" }'

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

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "c-0001",
    "tenant_id": "t-0001",
    "label": "contract-0001",
    "created_at": "2026-08-18T22:26:41.410593Z"
  }
  ```

  ```json 400 A field for a person theme={null}
  {
    "error": "reading the request: json: unknown field \"name\"",
    "code": "malformed_request"
  }
  ```

  ```json 409 A disagreeing repeat theme={null}
  {
    "error": "client: the registration disagrees with the one recorded: c-0001 is registered with a different label",
    "code": "conflicting_registration"
  }
  ```
</ResponseExample>


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