How to manage white-label accounts and users with the Partner API

Each of your customers needs its own Qvalia account.
Every person who will use the portal must exist as a user on the customer's account, whichever login method you choose.
The user's email address is the login key.
API integration must be active on every customer account, otherwise you cannot manage the account through the API.

The full reference is in the Partner API documentation.

Environments and authentication

Environment

Base URL

Test

https://api-test.qvalia.com

Production

https://api.qvalia.com

Requests are authenticated with an API key in the Authorization header, or with a bearer JWT obtained from the Authentication API. API credentials are for server-to-server calls only and must never be exposed in a browser.

Operations you will use

All paths are under /partner/{partnerRegNo}.

Resource

Operations

Path

Accounts

List, create, read, update

/account, /account/{accountRegNo}

Users

List, create, read, update, delete

/account/{accountRegNo}/user[/{userEmail}]

Bank accounts

List, create, read, update, delete

/account/{accountRegNo}/bankaccount[/{bankAccount}]

Peppol identifiers

List, read, add or update (PUT), delete

/account/{accountRegNo}/peppol[/{peppolId}]

Peppol lookup

Look up any Peppol participant

/peppol/lookup/{peppolId}

Create a customer account

Create the account with POST /partner/{partnerRegNo}/account. Enable API integration so you can manage the account through the API, plus the features the customer should have:

  {
 
    "accountRegNo": "FI01234567",
 
    "name": "Customer Oy",
 
    "address": "Esimerkkikatu 1",
 
    "postalCode": "00100",
 
    "city": "Helsinki",
 
    "country": "FI",
 
    "currency": "EUR",
 
    "appFeatures": {
 
      "apiIntegration": { "active": true },
 
      "invoiceManagement": { "active": true },
 
      "orderManagement": { "active": true }
 
    }
 
  }

If your users sign in through a token (JWT) forward from your application, also add the whiteLabel feature with your partner alias to appFeatures. The alias must match the wl parameter in the login request. It is not needed if your users use the Qvalia portal login.

  "whiteLabel": { "active": true, "wl_partners": ["
   
    "] }

Add users to each account

Create users with POST /partner/{partnerRegNo}/account/{accountRegNo}/user. With Qvalia portal login, the email address is the username. With token login, it must be identical to the email parameter in the login request, otherwise the sign-in is rejected.

  {
 
    "email": "user@customer.example",
 
    "name": "Example User",
 
    "language": "fi",
 
    "privilege": "admin"
 
  }

Things to know

accountRegNo, name, address, postalCode and country (ISO 3166 alpha-2) are required. The accountRegNo is the value used as account in the login request.
API integration must be active on every child account, otherwise you cannot manage it through the API.
Users require email, name and language (en, sv or fi), with the privilege viewer, user or admin.
Keep users in sync with your own system: add, update and remove them through the API as people join or leave.
In a white-label setup, the bank account marked is_default is used on invoices the customer creates. Only one default is allowed.
Peppol identifiers are created and updated with a full-object PUT. Read the current object first, then send the changed version.
Register CreditNote whenever you register Invoice.
Rate limits apply per account. On 429, wait for the number of seconds in Retry-After before retrying.
Errors use a common envelope. Branch on the stable type code, for example E_VALIDATION, not on the message text. See API error codes and responses.

If it still does not work

Check that API integration is active on the account and that you call the right environment with the credentials for that environment.
Have your partner registration number, the accountRegNo, the endpoint, the time of the call and the type code from the error response ready.
Contact your Qvalia partner manager, or reach Qvalia Support via qvalia.com/contact-support.