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.
Creating a registry role type (CEO, COB, …) returns 400; those are maintained by the nightly sync.
Deleting a registry role returns 403.
DELETE sets deleted_at on a manual role and returns 204 No Content; the row remains visible with include_history=true.
All dates are returned in ISO 8601 format.