General
The wealthAPI API is a RESTful interface for accessing the wealthAPI system programmatically.
Regulatory Compliance for Account Information Services
wealthAPI provides PSD2 relevant services via its partners. As a customer of wealthAPI services, regulatory requirements of the European PSD2 regulation (ZAG law in Germany) may apply to you. Please visit our PSD2 regulations page for details.
Technical documentation
You can find the technical description from the:
How to start using the API
wealthAPI uses a mandator based approach to securely separate user information from different domains (usually there is one mandator per SaaS customers). To start using the wealthAPI API please request a mandator account from our support. If you would just like to try the API, we will create an account on our Sandbox environment free of charge. Please include your companies’ information and a short description of your planned project in the request.
URI Information
URI format
The API endpoint format is https://{environment}/api/{version}/{resource}{additional-parameters}. The endpoints are versioned; versions will be upgraded in case of breaking changes or major functionality upgrades. The version will always be a full number. Example: https://sandbox.wealthapi.eu/api/v1/funds?isin=DE0009848119&isin=LU0323578657
URI parameters
An endpoint may support one or many query parameters. For each parameter, the API defines if it may occur only once, or if multiple occurrences (e.g. multiple IDs) are allowed. In case multiple occurrences are allowed, the parameter may be submitted multiple times. The API supports the ‘array’ as well as the ‘plain’ syntax. Array syntax: https://sandbox.wealthapi.eu/api/v1/accounts?id[]=1&id[]=2&id[]=3 Plain syntax: https://sandbox.wealthapi.eu/api/v1/accounts?id=1&id=2&id=3
Request Types
wealthAPI uses the request method GET, POST, PUT and DELETE. The API documentation clearly states which request type must be used. Submitting an invalid request type will result in an ‘invalid request type’ error.
Required request type in the API documentation
GET: is used to get data; query parameters are part of the URL; does not contain a request body. POST: is used to create data. Usually no query parameters are supported; the payload is contained as JSON body. PUT: is used to modify existing data. Usually only the ID of the entity to be modified is included in the URL path and no further query parameters are given. The payload is contained as JSON body. DELETE: is used to delete or invalidate existing data. The ID of the entity to be deleted is included in the URL path; does not contain a request body.
Status Codes
A successful request will return a success (200 or 202) status code. Any other status code indicates request error. The respective status codes for each operation are given in the API documentation.
Response codes including a short description are given in the API documentation
Accept and Content Types
The API only supports JSON request types. The standard response type is also JSON. A few methods support PDF as response type.
Response format
All responses returned simple or complex JSON types or objects, if not specified otherwise. In many cases, you will find a pagination option in the API parameters. The response will then contain the respective pagination setting.
The API documentation comes with example responses
See the API Reference Documentation for more examples on response types.
Date & Time format
Date and time format for request parameters is specified in the respective endpoint documentation, but will typically follow the format ‘yyyy-MM-dd’ (US Format). All response date formats follow the ISO 8601 format and is thus directly understood by most JS libraries.
Authentication
The wealthAPI API is end-user centric. It is intended to be directly used by a frontend library, e.g. the Javascript code running in the users browser or mobile device. When a user authenticates, a successful request will yield an auth token and a refresh token (see https://sandbox.wealthapi.eu/apiDocumentation#operation/login). The auth token is then included in the Authorization header of the http request (Authorization: Bearer auth_token). Auth tokens expire after one hour; as wealthAPI uses JWT an explicit “logout” is not possible. To logout simply delete the token. A refresh token may be used to obtain a new token using https://sandbox.wealthapi.eu/apiDocumentation#operation/refreshToken.
Mandator-Level authentication
In some cases, operations must be performed on mandator level and not on user level. An example could be to perform a support request for a user being unable to access his account. Thus, for some endpoints authentication as mandator is available. Use the header fields “X-Mandator-Client-Id” and “X-Mandator-Client-Secret” to submit the credentials.
User creation and mandators
A user is always attached to a mandator. Which mandator that is, is decided once at user creation time. Switching mandators is forbidden. When creating a user, make sure to provide your mandators public ID in order to have full access to the user later on. Note that users that were created using the mandator public ID always must confirm their email address. To skip email confirmation use the mandators private ID (see below).
Your mandator account
Your mandator account comes with two IDs, a private and a public ID. The public ID is used to perform non-sensitive mandator specific operations. E.g. you will provide the mandators public ID when creating a new user; or you will need the ID if you allowed anonymous users to comment on your site. Your mandators private ID is used to perform sensitive tasks and must always kept secret. E.g. it allows creating users without the need to confirm their email address. Be aware that unconfirmed email addresses pose a security thread and that you thus always keep your mandators private ID save.
Authorization
Roles
wealthAPI uses a role concept to limit access to certain API endpoints. Most endpoints require ROLE_USER, and thus allow access to the currently logged in users’ data. Each endpoint may define one or many roles governing access. The respective role permissions are documentation via each endpoints API documentation. Note that while administrative roles may have access to a wide range of user data, their access is always limited to users belonging to this administrators mandator. wealthAPI defines the following roles: ROLE_USER: A normal user; this is the default role. ROLE_STATS: Allows view access to aggregated statistics. ROLE_USER_MANAGEMENT: Allows to change user data. ROLE_ROLE_MANAGEMENT: Allows to assign and remove roles for users belonging to the administrators mandator. ROLE_SUBSCRIPTION_MANAGEMENT: Allows to manage subscriptions for the administrators mandator. ROLE_BI: Allows read and write access to aggregated statistical and business analytics data. ROLE_ACCOUNTING: Accountants may modify subscriptions and govern subscription billing cycles. ROLE_B2B_ADMIN: May create or update Business-to-Business users (a feature for bloggers). ROLE_APPLICATION_PROPERTY_ADMIN: May create or update application properties. ROLE_INSURANCE_ADMIN: May create or update insurance related master data. This role is only available to wealthAPI internal developers.
Assigning roles
Roles may be assigned by a role manager (ROLE_ROLE_MANAGEMENT) to individual users using the ‘/api/v1/roles’ endpoint. By default, each newly created users has role ROLE_USER assigned.
Anonymous access
Some endpoints allow anonymous access. Such endpoints have the ‘x-roles: IS_AUTHENTICATED_ANONYMOUSLY’ annotation.
x-roles: IS_AUTHENTICATED_ANONYMOUSLY annotation.