# Clients

> An accounting practice's clients, their bank accounts and transactions, and onboarding links.

Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer <API key or access token>`.

## List clients

`GET /api/public/v1/clients`

SDK: `prosaic.clients.list(params)`

Returns client users (`client` and `standard_user` roles) in the workspace tied to the token.
Callers authenticated as client or standard_user only ever receive their own client record,
even within a shared workspace. Accountant-style roles receive the full list (subject to filters).

### Query parameters

- `clientId` (string): Filter by specific client ID.
- `email` (string): Filter by client email address.

### Responses

- `200`: Successful response
  - `data` (array of objects, required)
    - `id` (string, required)
    - `email` (string, required)
    - `name` (string, nullable, required)
    - `tradingName` (string, nullable, required)
    - `createdAt` (string, date-time, required)
    - `bankAccounts` (array of objects, required)
      - `id` (string, required)
      - `name` (string, required)
  - `meta` (object)
    - `count` (number, required)
- `401`: Unauthorized - Invalid or missing API key
  - `error` (string)
- `404`: Workspace not found or access denied
  - `error` (string)
  - `code` (string)
- `500`: Internal server error
  - `error` (string)
  - `code` (string)

### Example (Node SDK)

```ts
const { data } = await prosaic.clients.list();
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/clients \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## List client's bank transactions

`GET /api/public/v1/clients/{clientId}/transactions`

SDK: `prosaic.clients.listTransactions(clientId, params)`

Returns paginated bank transactions for the specified client.

Access control:
- Authenticated user must be the client themselves, OR
- Authenticated user must be in the same workspace as the client (accountant/advisor)

Supports filtering by:
- Bank account IDs (comma-separated)
- Date range (dateFrom, dateTo)
- Reconciliation status (reconciled | unreconciled)

### Path parameters

- `clientId` (string, required)

### Query parameters

- `bankAccountIds` (array of strings): Comma-separated list of bank account IDs to filter by.
- `dateFrom` (string, date): Start date for filtering transactions (ISO 8601 format)
- `dateTo` (string, date): End date for filtering transactions (ISO 8601 format)
- `reconciliationStatus` (string): Filter by reconciliation status. One of: `reconciled`, `unreconciled`.
- `page` (integer): Page number (starts at 1) Default: `1`.
- `pageSize` (integer): Number of items per page. Default: `20`.

### Responses

- `200`: Successful response
  - `data` (array of objects, required)
    - `entityId` (string, nullable, required)
    - `reconciliationStatus` (string, required): One of: `reconciled`, `unreconciled`.
    - `journalId` (string, nullable, required)
    - `bankAccount` (object, required)
      - `id` (string, required)
      - `entityId` (string, nullable, required)
      - `externalId` (string, required)
      - `name` (string, required)
      - `alias` (string, nullable, required)
      - `institution` (string, nullable, required)
      - `accountNumber` (string, nullable, required)
      - `logoUrl` (string, nullable, required)
      - `type` (string, required)
      - `sourceType` (string, nullable, required)
      - `entityAccount` (object, nullable, required)
        - `id` (string, required)
        - `updatedAt` (string)
        - `reportCategoryReviewedAt` (string, nullable)
        - `reportCategoryReviewVersion` (number)
        - `code` (string, required)
        - `name` (string, required)
        - `type` (string, required)
        - `subtype` (string, required)
        - `reportGroup` (object, nullable, required)
          - `id` (string, required)
          - `key` (string, required)
          - `name` (string, required)
          - `status` (string, required)
          - `accountType` (string, required)
        - `reportCategory` (object, nullable, required)
          - `id` (string, required)
          - `key` (string, required)
          - `name` (string, required)
          - `status` (string, required)
        - `taxCode` (string, required)
        - `description` (string, nullable, required)
        - `mappedCode` (string, nullable, required)
        - `isSystem` (boolean, required)
        - `systemRole` (string, nullable)
        - `parentId` (string, nullable)
        - `isExcluded` (boolean)
        - `isIncluded` (boolean)
        - `source` (string): One of: `template`, `overridden`, `custom`.
    - `merchant` (object, nullable, required)
      - `id` (string, required)
      - `name` (string, required)
      - `provider` (string, nullable, required)
      - `identifier` (string, required)
    - `category` (object, nullable, required)
      - `id` (string, required)
      - `name` (string, required)
      - `identifier` (string, required)
    - `user` (object, required)
      - `id` (string, required)
      - `email` (string, required)
      - `name` (string, nullable, required)
      - `tradingName` (string, nullable, required)
      - `createdAt` (string, date-time, required)
    - `suggestions` (array of objects)
      - `id` (string, required)
      - `sourceType` (string, required)
      - `confidence` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic.
      - `status` (string, required)
      - `ruleId` (string, nullable, required)
      - `ruleName` (string, nullable, required)
      - `lines` (array of objects, required)
        - `id` (string, required)
        - `proportion` (string, nullable, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic.
        - `credit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic.
        - `debit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic.
        - `entityAccountId` (string, required)
        - `entityAccount` (object, required)
          - `id` (string, required)
          - `code` (string, required)
          - `name` (string, required)
        - `taxRateId` (string, nullable, required)
        - `taxRate` (object, nullable, required)
          - `id` (string, required)
          - `code` (string, required)
          - `name` (string, required)
          - `description` (string, nullable, required)
          - `rate` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic.
    - `id` (string, required)
    - `date` (string, date-time, required)
    - `amount` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic.
    - `description` (string, required)
    - `type` (string, required)
    - `particulars` (string, nullable, required)
    - `code` (string, nullable, required)
    - `reference` (string, nullable, required)
  - `pagination` (object, required)
    - `currentPage` (number, required)
    - `pageSize` (number, required)
    - `totalCount` (number, required)
    - `totalPages` (number, required)
    - `hasNextPage` (boolean, required)
    - `hasPreviousPage` (boolean, required)
- `400`: Bad request - invalid parameters
  - `error` (string)
  - `code` (string)
- `401`: Unauthorized - Invalid or missing API key/token
  - `error` (string)
- `403`: Forbidden - User does not have access to this client
  - `error` (string)
- `404`: Client not found
  - `error` (string)
- `500`: Internal server error
  - `error` (string)
  - `code` (string)

### Example (Node SDK)

```ts
const page = await prosaic.clients.listTransactions(clientId);
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/clients/$CLIENT_ID/transactions \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## List client's bank accounts

`GET /api/public/v1/clients/{clientId}/bank-accounts`

SDK: `prosaic.clients.listBankAccounts(clientId)`

Returns all bank accounts belonging to the specified client.

Access control:
- Authenticated user must be the client themselves, OR
- Authenticated user must be in the same workspace as the client (accountant/advisor)

### Path parameters

- `clientId` (string, required)

### Responses

- `200`: Successful response
  - `data` (array of objects, required)
    - `id` (string, required)
    - `entityId` (string, nullable, required)
    - `externalId` (string, required)
    - `name` (string, required)
    - `alias` (string, nullable, required)
    - `institution` (string, nullable, required)
    - `accountNumber` (string, nullable, required)
    - `logoUrl` (string, nullable, required)
    - `type` (string, required)
    - `sourceType` (string, nullable, required)
    - `entityAccount` (object, nullable, required)
      - `id` (string, required)
      - `updatedAt` (string)
      - `reportCategoryReviewedAt` (string, nullable)
      - `reportCategoryReviewVersion` (number)
      - `code` (string, required)
      - `name` (string, required)
      - `type` (string, required)
      - `subtype` (string, required)
      - `reportGroup` (object, nullable, required)
        - `id` (string, required)
        - `key` (string, required)
        - `name` (string, required)
        - `status` (string, required)
        - `accountType` (string, required)
      - `reportCategory` (object, nullable, required)
        - `id` (string, required)
        - `key` (string, required)
        - `name` (string, required)
        - `status` (string, required)
      - `taxCode` (string, required)
      - `description` (string, nullable, required)
      - `mappedCode` (string, nullable, required)
      - `isSystem` (boolean, required)
      - `systemRole` (string, nullable)
      - `parentId` (string, nullable)
      - `isExcluded` (boolean)
      - `isIncluded` (boolean)
      - `source` (string): One of: `template`, `overridden`, `custom`.
  - `meta` (object)
    - `count` (number, required)
- `401`: Unauthorized - Invalid or missing API key/token
  - `error` (string)
- `403`: Forbidden - User does not have access to this client
  - `error` (string)
- `404`: Client not found
  - `error` (string)
- `500`: Internal server error
  - `error` (string)
  - `code` (string)

### Example (Node SDK)

```ts
const { data } = await prosaic.clients.listBankAccounts(clientId);
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/clients/$CLIENT_ID/bank-accounts \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Create a client

`POST /api/public/v1/clients`

SDK: `prosaic.clients.create(params)`

Creates a new client in the workspace associated with the API key. If a client with the same email already exists, returns the existing client.

### Request body

Content type: `application/json`

- `name` (string, required)
- `email` (string, required)
- `tradingName` (string)
- `sendInvite` (boolean)
- `message` (string)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `id` (string, required)
    - `email` (string, required)
    - `name` (string, nullable, required)
    - `tradingName` (string, nullable, required)
    - `createdAt` (string, date-time, required)
    - `bankAccounts` (array of objects, required)
      - `id` (string, required)
      - `name` (string, required)
  - `meta` (object)
    - `count` (number, required)
- `400`: Validation failed
  - `error` (string)
  - `code` (string)
  - `details` (array of objects)
- `401`: Unauthorized - Invalid or missing API key
  - `error` (string)
- `404`: Workspace not found or access denied
  - `error` (string)
  - `code` (string)
- `429`: Invitation email rate limit exceeded
  - `error` (string)
  - `code` (string)
- `500`: Internal server error
  - `error` (string)
  - `code` (string)

### Example (Node SDK)

```ts
const { data } = await prosaic.clients.create({
  name: 'Example Ltd',
  email: 'accounts@example.com',
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/clients \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Ltd",
    "email": "accounts@example.com"
  }'
```

## Create onboarding link

`POST /api/public/v1/clients/{clientId}/onboarding`

SDK: `prosaic.clients.createOnboardingLink(clientId, params)`

### Path parameters

- `clientId` (string, required)

### Request body

Content type: `application/json`

- `integrationId` (string)
- `callbackURL` (string)
- `state` (string)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `magicLink` (string, required)
  - `meta` (object)
    - `count` (number, required)

### Example (Node SDK)

```ts
const { data } = await prosaic.clients.createOnboardingLink(clientId, {
  integrationId: 'INTEGRATION_ID',
  callbackURL: 'https://example.com/callback',
  state: 'string',
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/clients/$CLIENT_ID/onboarding \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationId": "INTEGRATION_ID",
    "callbackURL": "https://example.com/callback",
    "state": "string"
  }'
```