Organizational Roles

Organizational roles are the formal positions held in a client account’s company: owner, CEO, chair and members of the board, auditor, accountant. Each role links a business partner to a client account with a role type. They are used in compliance reporting (shareholder register, tax cards), shown to the accountant, and rendered into the bookkeeping robot’s context.

Roles come from two sources:

  • Registry roles (source_system: "BRREG") are synced nightly from Brønnøysundregistrene and are read-only through the API. A role that leaves the registry is retired automatically.
  • Manual roles (source_system: "MANUAL") are positions the registry does not carry (CFO, CTO). They are created and removed through the API.

Roles are versioned: a removed role is kept with deleted_at set instead of being deleted, so the history of who held which role when can be reconstructed. A role that is added again after removal gets a new row.

Endpoints

Method Endpoint Description
GET /client-accounts/{client_account_id}/organizational-roles List live organizational roles
POST /client-accounts/{client_account_id}/organizational-roles Create a manual organizational role
DELETE /client-accounts/{client_account_id}/organizational-roles/{role_id} Remove a manual organizational role

Attributes

Attribute Type Description
id integer The unique ID of the organizational role
created_at datetime When Snapbooks first recorded the role (not the registry appointment date)
created_by_id integer The ID of the user that created the role (system user for synced roles)
updated_at datetime The date and time when the role was last updated
updated_by_id integer The ID of the user that last updated the role
deleted_at datetime When the role was removed; null while the role is live
deleted_by_id integer The ID of the user that removed the role
client_account_id integer The ID of the client account this role belongs to
business_partner_id integer The ID of the business partner assigned to this role
role_type string The type of organizational role (see Role Types below)
source_system string BRREG for registry-synced roles, MANUAL for user-created roles
source_role_code string The raw registry role code (e.g. DAGL, LEDE, MEDL); null for manual roles

Role Types

Value Source Description
SOLE_PROPRIETOR brreg Sole proprietor (Innehaver)
PARTNER brreg Partner in a partnership (Deltaker)
CEO brreg Chief Executive Officer / general manager (Daglig leder)
COB brreg Chair of the board (Styreleder)
DEPUTY_COB brreg Deputy chair of the board (Nestleder)
BOARD_MEMBER brreg Board member (Styremedlem)
BOARD_ALTERNATE brreg Board alternate (Varamedlem)
AUDITOR brreg Auditor (Revisor)
ACCOUNTANT brreg Accountant (Regnskapsfører)
CFO manual Chief Financial Officer (Økonomisjef)
CTO manual Chief Technology Officer (Teknologisjef)

Relationships

Relationship Type Description
business_partner BusinessPartner The business partner assigned to this role

Query Parameters (GET)

Parameter Type Description
include_history boolean Also return removed roles (deleted_at set). Default false
with string Include related data, e.g. business_partner

Request Body (POST)

Field Type Required Description
business_partner_id integer Yes A business partner of the client account to assign the role to
role_type string Yes One of the manual role types (CFO, CTO)

Example Request

curl -X POST "https://api.snapbooks.com/v2/client-accounts/7/organizational-roles" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "business_partner_id": 56,
    "role_type": "CFO"
  }'

Example Response

{
    "id": 1,
    "created_at": "2024-06-15T10:30:00Z",
    "created_by_id": 7,
    "updated_at": null,
    "updated_by_id": null,
    "deleted_at": null,
    "deleted_by_id": null,
    "client_account_id": 7,
    "business_partner_id": 56,
    "role_type": "CFO",
    "source_system": "MANUAL",
    "source_role_code": null
}

Notes

  • The authenticated user must have access to the specified client account.
  • A business partner can hold each role type once at a time. Creating a duplicate live assignment returns 409 Conflict with code client_account.role_already_held.
  • Creating a registry role type (CEO, COB, …) returns 400 with code client_account.role_type_not_manual, and an unknown role_type returns 400 with code client_account.role_unknown_type; registry roles are maintained by the nightly sync.
  • business_partner_id must belong to the same client account; otherwise the request returns 400 with code client_account.role_business_partner_not_in_client_account.
  • Deleting a registry role returns 403 with code client_account.role_registry_immutable.
  • DELETE sets deleted_at on a manual role and returns 204 No Content; the row remains visible with include_history=true.
  • GET returns a paginated list (default per_page is 100).
  • All dates are returned in ISO 8601 format.

Error Codes

Errors use the standard error envelope. Branch on code, not on message. In addition to the common codes, these endpoints return:

Code HTTP status When
client_account.role_client_account_access_denied 403 The user has no access to the client account
client_account.role_no_data 400 POST with an empty JSON value ({}, [] or null); a request without a JSON body is rejected before this check
client_account.role_unknown_type 400 role_type is not a known role type; details.role_type echoes it
client_account.role_type_not_manual 400 role_type is maintained from the business registry; details.role_type echoes it
client_account.role_business_partner_not_in_client_account 400 business_partner_id belongs to another client account
client_account.role_already_held 409 The business partner already holds a live role of that role_type
client_account.role_not_found 404 DELETE of a role that does not exist or is already deleted
client_account.role_registry_immutable 403 DELETE of a role that comes from the business registry

Example Error Response

{
    "error": {
        "code": "client_account.role_already_held",
        "message": "This business partner already holds that role.",
        "request_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
    }
}