---
title: "Companies & settings API"
canonical: https://documentation.maventa.com/api-specification/rest-api/companies-and-settings-api/
---

The Companies & Settings API lets you manage company accounts, profiles, settings, and users. Use it to create company accounts, activate invoice receiving networks such as Peppol, configure notification settings, manage departments, and handle user access and authorization.

For a full walkthrough of account setup and management, see the [companies and settings integration guide](https://documentation.maventa.com/integration-guide/account-management/companies-and-settings/).

## API endpoints

### GET /v1/company/profiles

List network registrations

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| network | query | array[string] | no | Network filter |
| status | query | array[string] | no | Status filter |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | List network registrations | `array[API_Entities_CompanyProfile]` |

### POST /v1/company/profiles

Create network registration request

**Request body**

Schema: `postV1CompanyProfiles`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| profiles | `array[string]` | no | List of profile names |
| profile_version | `string` | no | Profile version, eg. EHF30, PEPPOLBIS30 |
| endpoint_id | `string` | no | Endpoint identifier |
| scheme | `string` | no | ISO6523 code of the endpoint_id scheme. eg. 0192 for NO:ORG |
| network | `string` | no | Target network, defaults to PEPPOL |
| profiles_with_extensions | `array[string]` | no | List of profile names with extensions |
| network_settings | `object` | no | Additional network settings |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 201 | Create network registration request | `API_Entities_CompanyProfile` |
| 422 | - **profile_name_conflict**: Profile is already registered for given endpoint id - **profile_eia_conflict**: Endpoint id is already in use - **profile_eia_bid_conflict**: Endpoint id does not match the company business id - **profile_not_supported**: Profile is not supported | `API_Entities_Error` |

### PUT /v1/company/profiles/{id}/extensions


EXPERIMENTAL Create extensions for profiles

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | Profile Subscription Id |

**Request body**

Schema: `putV1CompanyProfilesIdExtensions`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| profile_name | `string` | yes | Profile name |
| extensions | `array[string]` | yes | Extensions |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | EXPERIMENTAL Create extensions for profiles |  |

### GET /v1/company/profiles/{id}

Fetch a network registration

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | Profile id |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Fetch a network registration | `API_Entities_CompanyProfile` |

### PATCH /v1/company/profiles/{id}

Update a network registration

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | Profile id |

**Request body**

Schema: `patchV1CompanyProfilesId`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| network_settings | `object` | no | Additional network settings |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 204 | Profile updated succesfully |  |

### DELETE /v1/company/profiles/{id}

Delete a network registration

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | Profile id |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 204 | Registration deleted succesfully |  |
| 409 | - **profile_deletion_not_allowed**: Deletion of profile is not allowed | `API_Entities_Error` |

### GET /v1/company/settings

Fetch company settings

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| fields | query | array[string] | no | Filter the response to only include requested fields.                                     Possible values: invoice_notifications, send_invoice_email, address, details, send_invoice_print, send_invoice_general, logos, email_reports, billing_details |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Fetch company settings | `API_Entities_CompanySettings_Settings` |

### PATCH /v1/company/settings

Modify company settings

### Company billing details
 ```
{
  "billing_details": {
    "electronic_invoicing_details": {
      "invoicing_eia": "Company electronic invoicing address (Billing information: The delivery method priority is following 1 = einvoice, 2 = email, 3 = print, if all below values are given. If company prefers Invoicing via normal post, invoicing_eia, invoicing_operator and invoicing_email should be left blank).",
      "invoicing_operator": "Company electronic invoicing operator address"
    },
    "invoicing_email": "info@company.com",
    "invoicing_street_address1": "My street 1",
    "invoicing_street_address2": "My street 2",
    "invoicing_post_code": "123456",
    "invoicing_post_office": "Helsinki",
    "billing_company_id": "123456"
  }
}
```




### Company email reports

```
{
  "email_reports": {
    "report_interval": "off | daily | weekly | monthly",
    "email_reports": [
      "info@company.com",
      "reports@company.com"
    ]
  }
}
```



### Company logos

```
{
  "logos": {
    "pdf": {
      "content": "Base64 encoded string of PNG or JPEG image for use as logo on generated PDF invoices"
    },
    "email_header": {
      "content": "Base64 encoded string of PNG only image for use as header image on sent email invoices"
    }
  },
}
```


### Company general settings

```
{
  "send_invoice_general": {
    "hold_multiple_recipients": false,
    "stop_duplicate_numbers": false
  }
}
```


### Company invoice print settings

```
{
  "send_invoice_print": {
    "enabled": false,
    "letter_class": "ECONOMY",
    "color_scheme": "BLACK_AND_WHITE",
    "attachment_print": false,
    "marketing_page": false,
    "use_own_pdf": false
  }
}
```


### Company details

```
{
  "details": {
    "name": "My Company Ltd",
    "email": "info@company.com",
    "website": "https://my.company.com"
  }
}
```

### Company address
 ```
{
  "address": {
    "street_address": "My street 1",
    "post_code": "123456",
    "post_office": "Oslo",
    "city": "Oslo",
    "country": "NO"
  }
}
```



### Company send invoice email related settings

```
{
  "send_invoice_email": {
    "enabled": true,
    "how_to_send": "EMBEDDED | WITH_OBJECTIONS | WITH_LINK | EMBEDDED_MERGE (only if enabled is true)",
    "reminder_frequency": 4,
    "content_data": {
      "note_to_receiver": "A message added to the receiver",
      "contact": {
        "email": "invoices@company.com (this is validated by sending a link email to the email)",
        "name": "Info User",
        "phone": "+555 55 555 5555"
      }
    }
  }
}
```


### Company invoice notification settings

```
{
  "invoice_notifications": {
    "on_receiving": {
      "enabled": true,
      "how_to_send": "OTHER_EMAIL",
      "other_email": "info@company.com"
    },
    "on_send_errors": {
      "to_user": true,
      "to_emails": [
        "info@company.com"
      ]
    }
  }
}
```

**Request body**

Schema: `patchV1CompanySettings`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| details | `API_Entities_CompanySettings_CompanyDetails` | yes | Company details |
| address | `API_Entities_CompanySettings_CompanyAddress` | yes | Company address |
| invoice_notifications | `API_Entities_CompanySettings_CompanyInvoiceNotifications` | yes | Company invoice notifications |
| send_invoice_email | `API_Entities_CompanySettings_CompanySendInvoiceEmail` | no | Company send invoices via emails |
| send_invoice_print | `API_Entities_CompanySettings_CompanySendInvoicePrintSettings` | no | Company invoice sending print settings |
| send_invoice_general | `API_Entities_CompanySettings_CompanySendInvoiceGeneralSettings` | no | Company invoice sending general settings |
| logos | `API_Entities_CompanySettings_CompanyLogos` | no | Company logos |
| email_reports | `API_Entities_CompanySettings_CompanyEmailReports` | no | Email reports |
| billing_details | `API_Entities_CompanySettings_CompanyBillingDetails` | no | Company billing details |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 204 | Settings updated successfully |  |
| 400 | - **invalid_parameters**: Request parameters are invalid | `API_Entities_Error` |

### GET /v1/company/consumers

List B2CNO Consumers - DEPRECATED 2025

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| query | query | string | no | List by phonenumber, name, customer_number and reference_number |
| status | query | array[string] | no | List of statuses |
| page | query | integer | no | Page to fetch |
| per_page | query | integer | no | Number of items per page, values up to 100 supported |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | List B2CNO Consumers - DEPRECATED 2025 | `array[API_Entities_CompanyConsumers_Consumer]` |

### GET /v1/company/notifications

List notification subscriptions

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | List notification subscriptions | `array[API_Entities_Notifications_Notification]` |

### POST /v1/company/notifications

Create new notification subscription

**Request body**

Schema: `postV1CompanyNotifications`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| destination_type | `string` | yes | Type of notification. Possible values: WEBHOOK, VENDOR_WEBHOOK |
| destination | `string` | yes | Notification destination. For WEBHOOK and VENDOR_WEBHOOK types, must be an HTTPS URL. |
| vendor_key | `string` | no | Name/Key of registered vendor key |
| events | `array[string]` | yes | Type of events |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 201 | Create new notification subscription | `API_Entities_Notifications_Notification` |

### GET /v1/company/notifications/{id}

Fetch a specific notification subscription

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | Notification id |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Notification subscription | `API_Entities_Notifications_Notification` |

### DELETE /v1/company/notifications/{id}

Delete a specific notification subscription

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | Notification id |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 204 | Notification subscription was deleted |  |

### POST /v1/company/notifications_resend_unacknowledged

[EXPERIMENTAL] Resend unacknowledged notifications

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Request accepted. Unacknowledged webhooks for all subscriptions will get retriggered at a later point |  |

### GET /v1/company/vendors


Vendor API key link status

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Vendor API key link status | `API_Entities_LinkVendorAPIKey` |

### POST /v1/company/vendors


Link vendor API key

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 201 | Link vendor API key | `API_Entities_LinkVendorAPIKey` |

### DELETE /v1/company/vendors


Unlink vendor API key

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 204 | Vendor unlinked |  |

### GET /v1/company/authorization

Company authorization status. In order to use company account to send, receive and activate services status needs to be verified

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Company authorization status. In order to use company account to send, receive and activate services status needs to be verified | `API_Entities_CompanyAuthorizationStatus` |

### POST /v1/company/authorization


Authorize your company. Required to complete KYC process and take company account into use

**Request body**

Schema: `postV1CompanyAuthorization`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| auth_email | `string` | yes | Email to send the Visma sign request to. The person signing will be strongly authenticated. |
| locale | `string` | yes | Locale to use on the signin invitation email, visma sign portal and agreement PDF. |
| options | `string` | no | JSON string used to provide proof of KYC process. Mandatory when partner has own KYC process. |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Sign request sent | `API_Entities_CompanyAuthorization` |
| 400 | Bad request | `API_Entities_Error` |

### GET /v1/company/users


List existing users

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | List existing users | `array[API_Entities_CompanyUsers_User]` |

### POST /v1/company/users


Add a new or existing user to a company

**Request body**

Schema: `postV1CompanyUsers`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| email | `string` | yes | User email |
| first_name | `string` | yes | First name |
| last_name | `string` | no | Last name |
| phone | `string` | no | Phone number |
| user_role | `string` | no | User role |
| notifications_disabled | `boolean` | no | If set to true, user will not receive e-mail notifications for their invoices. |
| emails_disabled | `boolean` | no | If set to true, user will not receive any e-mail notifications e.g. invoice send errors and such. |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 201 | User was successfully created | `API_Entities_CompanyUsers_NewUser` |
| 200 | User was added to company | `API_Entities_CompanyUsers_User` |

### GET /v1/company/users/{user_id}


Fetch user info

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| user_id | path | string | yes |  |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 |  | `API_Entities_CompanyUsers_User` |

### PATCH /v1/company/users/{user_id}


Update user info

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| user_id | path | string | yes |  |

**Request body**

Schema: `patchV1CompanyUsersUserId`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| first_name | `string` | no | First name |
| last_name | `string` | no | Last name |
| phone | `string` | no | Phone number |
| notifications_disabled | `boolean` | no | If set to true, user will not receive e-mail notifications for their invoices. |
| emails_disabled | `boolean` | no | If set to true, user will not receive any e-mail notifications e.g. invoice send errors and such. |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 204 |  |  |

### DELETE /v1/company/users/{user_id}


Remove a user from this company

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| user_id | path | string | yes |  |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 204 |  |  |

### POST /v1/company/users/{user_id}/roles


Update user role

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| user_id | path | string | yes |  |

**Request body**

Schema: `postV1CompanyUsersUserIdRoles`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| user_role | `string` | yes | User role |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 204 |  |  |

### POST /v1/company/keep_active


Mark company as active even if no transactions have occurred during the past year.

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 201 | Mark company as active even if no transactions have occurred during the past year. |  |

### GET /v1/company/departments


List departments [EXPERIMENTAL]

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | List departments [EXPERIMENTAL] | `array[API_Entities_Company]` |

### POST /v1/company/departments


Create a department [EXPERIMENTAL]

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| name | formData | string | yes | Company name. Name has to be at least 3 characters long |
| bid | formData | string | yes | Company organization number/Business ID/VAT |
| id_type | formData | string | yes | Electronic address identifier type |
| eaid | formData | string | yes | Electronic address identifier |
| no_vat | formData | boolean | no | Deprecated, no need to give this param anymore |
| address1 | formData | string | yes | Street address |
| address2 | formData | string | no | Additional address |
| post_code | formData | string | yes | Postal number/code, |
| post_office | formData | string | yes | Post office |
| city | formData | string | yes | Registered city |
| state | formData | string | no | State of address |
| country | formData | string | yes | Country code for company, mandatory. Allowed countries FI, SE, NO, DK, NL, BE |
| email | formData | string | yes | Contact email address for company |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 201 | Create a department [EXPERIMENTAL] | `API_Entities_Company` |

### GET /v1/companies

List active companies the user has access to

List all companies without giving params, or check if user belongs to a given company.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| bid | query | string | no | Business id. |
| country | query | string | no | Country in ISO 3166-1 alpha-2 format (2 letters) |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | List active companies the user has access to | `array[API_Entities_UserCompany]` |

### POST /v1/companies


Create a Company

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| vendor_api_key | formData | string | yes | Identifies partner/ERP |
| user_api_key | formData | string | yes | The user API key |
| name | formData | string | yes | Company name. Name has to be at least 3 characters long |
| bid | formData | string | yes | Company organization number/Business ID/VAT |
| no_vat | formData | boolean | no | Deprecated, no need to give this param anymore |
| address1 | formData | string | yes | Street address |
| address2 | formData | string | no | Additional address |
| post_code | formData | string | yes | Postal number/code, |
| post_office | formData | string | yes | Post office |
| city | formData | string | yes | Registered city |
| state | formData | string | no | State of address |
| country | formData | string | yes | Country code for company, mandatory. Allowed countries FI, SE, NO, DK, NL, EE, BE, DE, LV. IT and PL are in experimental mode. |
| email | formData | string | yes | Contact email address for company |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 201 | Create a Company | `API_Entities_Company` |

### POST /v1/companies/authorizations


Authorize one or multiple companies. Required to complete KYC process and take company account into use

**Request body**

Schema: `postV1CompaniesAuthorizations`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| auth_email | `string` | yes | Email to send the Visma sign request to. The person signing will be strongly authenticated. |
| company_ids | `array[string]` | yes | Company UUIDs to authorize. Admin user needs to have access to all of the companies given. |
| locale | `string` | yes | Locale to use on the signin invitation email, visma sign portal and agreement PDF. |
| options | `string` | no | JSON string used to provide proof of KYC process. Mandatory when partner has own KYC process. |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 |  | `API_Entities_CompanyAuthorization` |
| 202 |  | `API_Entities_CompanyAuthorization` |
| 400 | Bad request | `API_Entities_Error` |

### GET /v1/companies/{id}/status


Company authorization status. In order to use company account to send, receive and activate services status needs to be verified

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | Company ID |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Company authorization status. In order to use company account to send, receive and activate services status needs to be verified | `API_Entities_CompanyAuthorizationStatus` |

### POST /v1/users


Create a User

**Request body**

Schema: `postV1Users`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| vendor_api_key | `string` | yes | Vendor API key |
| email | `string` | yes | User email |
| first_name | `string` | no | User first name |
| last_name | `string` | no | User last name |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 201 | Create a User | `API_Entities_ApiUser` |


_OpenAPI spec snapshot: 2026-05-06_