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 Conflictwith codeclient_account.role_already_held. - Creating a registry role type (
CEO,COB, …) returns400with codeclient_account.role_type_not_manual, and an unknownrole_typereturns400with codeclient_account.role_unknown_type; registry roles are maintained by the nightly sync. business_partner_idmust belong to the same client account; otherwise the request returns400with codeclient_account.role_business_partner_not_in_client_account.- Deleting a registry role returns
403with codeclient_account.role_registry_immutable. - DELETE sets
deleted_aton a manual role and returns204 No Content; the row remains visible withinclude_history=true. - GET returns a paginated list (default
per_pageis 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"
}
}