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. Internal cajas may have several accounts in the same currency. External clients reuse one account per currency. GET /api/clients already returns both types when they exist, together with their accounts. An empty { data: [], count: 0 } means the company has no clients yet — it is not an internal-type filter.

List clients

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

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 (default 1)
pageSize (default 50, max 100)
description
type — 0 for internal cajas, 1 for external counterparties. Omit to return both.

The response includes:

Client metadata such as id, name, description, and type
The client’s associated accounts
Account-level balances and currencies
client_tags — company labels assigned to the client (join rows with a nested tag). See Client tags.

To discover only internal account IDs for UP/DOWN or same-currency OTHER legs:

curl --request GET \
  --url "https://finsync.ar/api/clients?type=0" \
  --header "x-api-key: YOUR_API_KEY"

List accounts

GET /api/accounts is a thin company-scoped view of the same account records embedded on GET /api/clients. Use it when you already know you need internal_account_id values.

curl --request GET \
  --url "https://finsync.ar/api/accounts?type=0" \
  --header "x-api-key: YOUR_API_KEY"

Optional filters: client_id, type (0 or 1).

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 (internal or external). 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 a client

Use POST /api/clients to create a client for the company tied to the API key.

Omit type or send type: 1 for an external cuenta corriente (existing integrator default).
Send type: 0 for an internal caja. This does not create a cuenta corriente or portal access.

curl --request POST \
  --url "https://finsync.ar/api/clients" \
  --header "Content-Type: application/json" \
  --header "x-api-key: YOUR_API_KEY" \
  --data '{
    "name": "Caja USD",
    "description": "Internal USD caja",
    "type": 0
  }'

External counterparty example (default type):

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"
  }'

Optional tag_ids assigns existing company tags on create (dashboard create). Unknown IDs return 404 and no client is created. To replace tags later, use PUT /api/clients/{id}/tags with the full tag_ids set. See Client tags. The endpoint does not create portal access for the client. It only creates the accounting record.

Create an account

Use POST /api/accounts to add an account on an existing client. Reuse currency_name values the company already uses (USD, ARS, …). This endpoint does not create currencies.

curl --request POST \
  --url "https://finsync.ar/api/accounts" \
  --header "Content-Type: application/json" \
  --header "x-api-key: YOUR_API_KEY" \
  --data '{
    "client_id": 123,
    "name": "Caja USD",
    "currency_name": "USD"
  }'

The response is the created account (id, client_id, name, currency_name, balance, …). For external clients, if an account already exists for that currency, the existing account is returned.

Typical integration flow

List clients with GET /api/clients (optionally ?type=0 for cajas).
If the company has no internals yet, create a caja with POST /api/clients and "type": 0.
Add accounts with POST /api/accounts (client_id, name, currency_name).
Fetch the full record with GET /api/clients/{id} or GET /api/accounts?client_id=… to pick internal_account_id.
Reuse those IDs in operation workflows such as UP, DOWN, OTHER, or EXCHANGE.

GET /api/clients
POST /api/clients
GET /api/clients/{id}
PUT /api/clients/{id}/tags
GET /api/tags
POST /api/tags
GET /api/accounts
POST /api/accounts

​Clients workflow

​List clients

​List accounts

​Interpret balances correctly

​Inspect one client

​Create a client

​Create an account

​Typical integration flow

​Related endpoints