Organizational Roles

Organizational roles define the key positions held within a client account, such as CEO, CFO, board members, and sole proprietors. Each role links a business partner to a client account with a specific role type. These roles are used in compliance reporting (e.g. shareholder register, tax returns) and company administration.

Endpoints

Method	Endpoint	Description
GET	/client-accounts/{client_account_id}/organizational-roles	List organizational roles
POST	/client-accounts/{client_account_id}/organizational-roles	Create an organizational role
DELETE	/client-accounts/{client_account_id}/organizational-roles/{role_id}	Delete an organizational role

Attributes

Attribute	Type	Description
id	integer	The unique ID of the organizational role
created_at	datetime	The date and time when the role was created
created_by_id	integer	The ID of the user that created the role
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
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)

Role Types

Value	Description
CEO	Chief Executive Officer (Daglig leder)
CFO	Chief Financial Officer
CTO	Chief Technology Officer
COB	Chairman of the Board (Styreleder)
BOARD_MEMBER	Board member (Styremedlem)
SOLE_PROPRIETOR	Sole proprietor (Innehaver)

Relationships

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

Request Body (POST)

When creating an organizational role, send a JSON object with the following fields:

Field	Type	Required	Description
business_partner_id	integer	Yes	The ID of the business partner to assign the role to
role_type	string	Yes	One of the valid role types listed above

Example Request

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

Example Response

{
    "id": 1,
    "created_at": "2024-06-15T10:30:00Z",
    "created_by_id": 7,
    "updated_at": null,
    "updated_by_id": null,
    "client_account_id": 7,
    "business_partner_id": 56,
    "role_type": "CEO"
}

Notes

The authenticated user must have access to the specified client account.
Each combination of client_account_id, business_partner_id, and role_type must be unique. Attempting to create a duplicate assignment will result in an error.
The business_partner_id must reference an existing business partner. Typically this is a person (contact) rather than a company.
The created_by_id is automatically set to the authenticated user’s ID.
The DELETE endpoint permanently removes the role assignment and returns 204 No Content on success.
Use the with parameter to include related data: ?with=business_partner.
All dates are returned in ISO 8601 format.