Client Accounts API

Client Accounts

Client accounts represent individual business entities within the system. Each client account has its own settings, users, and business data.

Endpoints

Method	Endpoint	Description
GET	/client-accounts	List client accounts
GET	/client-accounts/{id}	Get a specific client account
PUT/PATCH	/client-accounts/{id}	Update a client account

Query Parameters

The GET /client-accounts endpoint supports the following query parameters:

Parameter	Type	Required	Description
order_by	string	No	Sort order
page	integer	No	Page number for pagination (default: 1)
per_page	integer	No	Number of items per page (default: 100)
has_direct_role	boolean	No	Filter by user’s direct role. Values: `true` (has direct ClientAccountUser), `false` (no direct role)
is_provider	boolean	No	Filter by provider status. Values: `true` (is a provider), `false` (not a provider)
provider_type	string	No	Filter by specific provider type. Values: `ACCOUNTANT`, `AUDITOR`
is_active	boolean	No	Filter by active status. Values: `true` (active), `false` (inactive)

Direct Role vs Contract Access

Client accounts can be accessed in two ways:

Direct Role: Users have a direct ClientAccountUser association with the client account. This is typical for regular customers who have direct access to their own company.
Contract Access: Agency users (like accountants and auditors) may have access through a contract between their agency and the client account, without having a direct role.

Filtering Examples

The has_direct_role parameter helps distinguish between these access types:

# Get client accounts where user has a direct role (e.g. customer's own company)
GET /client-accounts?has_direct_role=true

# Get client accounts where user has only contract-based access (e.g. accountant's clients)
GET /client-accounts?has_direct_role=false

# Get all accessible client accounts regardless of access type
GET /client-accounts

# Get only provider accounts (accountants/auditors)
GET /client-accounts?is_provider=true

# Get only accountant accounts
GET /client-accounts?provider_type=ACCOUNTANT

# Get only active accounts
GET /client-accounts?is_active=true

# Combine filters
GET /client-accounts?is_provider=true&provider_type=ACCOUNTANT&is_active=true

Attributes

Attribute	Type	Description
id	integer	The unique identifier of the client account
created_at	datetime	When the client account was created
created_by_id	integer	The ID of the user who created the account
updated_at	datetime	When the account was last updated
updated_by_id	integer	The ID of the user who last updated the account
unique_name	string	Unique identifier for the account
display_name	string	Display name for the account
is_active	boolean	Whether the account is active
accounting_currency	string	The main currency used for accounting
organization_id	integer	The ID of the associated organization
organization_number	string	The organization number
metadata	object	Additional metadata for the account
is_provider	boolean	Whether the account is a provider (accountant/auditor)
provider_type	string	Type of provider if applicable (ACCOUNTANT/AUDITOR)

Relationships

Relationship	Type	Description
organization	Organization	The associated organization
users	[ClientAccountUser]	Users with access to this account
provider_contracts	[Contract]	Contracts where this account is the provider
client_contracts	[Contract]	Contracts where this account is the client
settings	ClientAccountSettings	Historical settings for this account
current_settings	ClientAccountSettings	Current active settings
statistics	object	Statistical information about the account

Example Response

{
    "id": 1,
    "created_at": "2023-05-10T12:00:00Z",
    "created_by_id": 1,
    "updated_at": "2023-05-10T12:00:00Z",
    "updated_by_id": 1,
    "unique_name": "acme-corp",
    "display_name": "ACME Corporation",
    "is_active": true,
    "accounting_currency": "EUR",
    "organization_id": 1,
    "organization_number": "123456789",
    "metadata": {
        "industry": "Technology",
        "size": "Medium"
    },
    "is_provider": true,
    "provider_type": "ACCOUNTANT",
    "organization": {
        "id": 1,
        "name": "ACME Corporation"
    },
    "current_settings": {
        "id": 1,
        "active_from": "2023-01-01",
        "plan": "ENTERPRISE",
        "vat_liable": true,
        "project_module": true,
        "bank_integration_module": true
    },
    "statistics": {
        "total_users": 10,
        "active_projects": 5
    }
}

Error Responses

Status Code	Description
400	Invalid query parameters
403	User not authorized to access client account
404	Client account not found

Notes

Only users with appropriate permissions can access a client account.
The unique_name must be unique across all client accounts.
When updating a client account, only certain fields can be modified (unique_name, display_name, is_active, accounting_currency, metadata).
The created_by_id/updated_by_id is automatically set to the authenticated user’s ID.
All dates are returned in ISO 8601 format.
Settings are versioned with active_from/active_to dates to track changes over time.