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

Query Parameters

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

Direct Role vs Contract Access

Client accounts can be accessed in two ways:

1. 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.
2. 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

Relationships

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

Creating Client Accounts

Basic Client Account Creation

Any user can create a basic client account by providing the required organization information:

POST /client-accounts
{
    "organization_id": 12345,
    "display_name": "New Client Company AS",
    "accounting_currency": "NOK"
}

Provider Creating Client Account with Contract

Accountant and auditor providers can create client accounts with contracts in a single request. The contract will be automatically approved since the provider is creating both the client account and the contract:

POST /client-accounts
{
    "organization_id": 12345,
    "display_name": "New Client Company AS",
    "accounting_currency": "NOK",
    "client_contracts": [
        {
            "provider_client_account_id": 123,
            "service_provided": "ACCOUNTING",
            "start_date": "2025-01-01"
        }
    ]
}

Response:

{
    "id": 789,
    "display_name": "New Client Company AS",
    "organization_id": 12345,
    "accounting_currency": "NOK",
    "client_contracts": [
        {
            "id": 456,
            "provider_client_account_id": 123,
            "client_account_id": 789,
            "service_provided": "ACCOUNTING",
            "start_date": "2025-01-01",
            "approval_status": "APPROVED",
            "is_active": true
        }
    ]
}

Authorization Rules

• Basic creation: Any authenticated user can create client accounts
• With contracts: Only provider accounts (accountants/auditors) can create client accounts with contracts
• Organization uniqueness: Each organization can only have one client account
• Provider validation: Users can only create contracts for their own provider accounts

Notes

• Only users with appropriate permissions can access a client account.
• The unique_name must be unique across all client accounts.
• Each organization can only have one client account - attempts to create duplicate accounts will be rejected.
• When updating a client account, only certain fields can be modified (unique_name, display_name, is_active, accounting_currency, metadata).
• Contracts created during client account creation are automatically approved.
• 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.