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

# Clients workflow

> Understand internal vs external clients, list their accounts, and create external counterparties with the FinSync API.

# Clients workflow

In FinSync, a client is not only a person or company. It is the business entity that owns balances and participates in operations.

The application wiki distinguishes two client categories that matter when you automate against the API:

* Internal clients (`type = 0`): your own `cajas`, wallets, banks, or liquid accounts.
* External clients (`type = 1`): counterparties tracked as `cuentas corrientes`.

Each client can have one or more associated accounts, usually split by currency.

## List clients

Use `GET /api/clients` to retrieve company clients together with their related accounts.

```bash theme={null}
curl --request GET \
  --url "https://finsync.ar/api/clients?page=1&pageSize=10&description=acme" \
  --header "x-api-key: YOUR_API_KEY"
```

Useful query parameters:

* `page`
* `pageSize`
* `description`

The response includes:

* Client metadata such as `id`, `name`, `description`, and `type`
* The client's associated `accounts`
* Account-level balances and currencies

## Interpret balances correctly

The same numeric balance means different things depending on the client type:

* Internal client (`type = 0`): a positive balance means the company has funds available in that wallet or bank account. A negative balance means a deficit or overdraft.
* External client (`type = 1`): a positive balance means the company owes money to that client. A negative balance means that client owes money to the company.

This interpretation is essential before you build reconciliation, alerts, or approval rules on top of the client list.

## Inspect one client

Use `GET /api/clients/{id}` when you need the detailed record for one client, including its accounts.

This is the best follow-up call after listing clients when your workflow needs to:

* choose the correct account by currency
* inspect the latest stored balance per account
* confirm whether you are working with an internal or external counterparty

## Create an external client

Use `POST /api/clients` to create a new external counterparty for the company tied to the API key.

This endpoint is intentionally scoped to external clients. In app terms, it creates a `cuenta corriente`, not one of your internal `cajas`.

```bash theme={null}
curl --request POST \
  --url "https://finsync.ar/api/clients" \
  --header "Content-Type: application/json" \
  --header "x-api-key: YOUR_API_KEY" \
  --data '{
    "name": "ACME Brokers",
    "description": "Preferred FX counterparty"
  }'
```

The endpoint does not create portal access for the client. It only creates the accounting counterparty record.

## Typical integration flow

1. List clients with `GET /api/clients`.
2. Filter by `description` or your own matching logic to detect whether the counterparty already exists.
3. If it does not exist, create it with `POST /api/clients`.
4. Fetch the full record with `GET /api/clients/{id}` when you need to inspect account balances or pick the correct currency-specific account.
5. Reuse the returned client ID in operation workflows such as `UP`, `DOWN`, `OTHER`, or external `EXCHANGE`.

## Related endpoints

* `GET /api/clients`
* `POST /api/clients`
* `GET /api/clients/{id}`