0808API integration
Open a file from your own software.
If your colleagues enter a client in your practice software and then retype it here, the second entry will drift. The API exists so the file starts from where the client is already known.
This page says what an integration looks like and what it asks for. The full technical reference, with the requests, the responses and the signature verification code, lives on the page for developers.
01Authentication
OAuth2, scope by scope.
Access goes through OAuth2 client credentials. Tokens last an hour: cache them and refresh on expiry rather than on every call.
Declared scopes
- onboardings:read
- onboardings:write
- clients:read
- clients:write
- companies:read
- register:read
- register:write
- reports:read
- verifications:read
- verifications:write
- webhooks:manage
Ask for the narrowest set that does your job. The onboarding and register endpoints exist today: reports:read and webhooks:manage are declared for endpoints not yet built and grant nothing.
02The usual path
Three calls and a living file.
The commonest integration does not try to rebuild the application. It creates the file with what your software already knows, lets compliance happen here, and keeps up with what follows.
- GET
/api/v2/register/companies/{n}Read the register
Before you open anything: identity, address, activities, financial score, filed accounts and Gazette notices. A company you have never onboarded answers too, because the register is public.
Returns the public record, and what your organization already knows about it - POST
/api/v2/onboardingsCreate the file
A company number is enough: the record pre-fills from the official register, so you are not sending legal data you do not control.
Returns the identifier of the file created - POST
/api/v2/onboardings/{id}/beneficiariesFill it in
Add what your software holds and the register does not give: contact people, nature of the engagement, documents already collected.
Returns the beneficial owner added to the file - POST
/api/v2/onboardings/{id}/submitFollow the decision
Rather than polling the API in a loop, let the webhook tell you when the file changes state.
Returns the file handed to the compliance officer, the rest arrives by webhook
03Webhooks
Signed, and to be verified.
Every delivery carries a signature computed with your shared secret. Receiving without verifying would accept any request claiming to come from us, which is exactly the risk the signature exists to remove.
POST https://votre-app.example.com/hooks/aml
x-amlcompany-signature: v1=9f86d0818…
04Sandbox
Try it without creating real files.
A test environment lets you walk the whole path with data meant for it, before connecting the integration to your real organisation.
Reserved company numbers
| Number | What happens |
|---|---|
| BE0999999001 | A complete company, SANDBOX TEST SRL |
| BE0999999002 | A company shaped to assess as higher risk |
| BE0999999404 | Always absent: the path you must never retry |
| BE0999999500 | Always failing: the path you must retry |
A sandbox never queries the official register: your tests would depend on a third party and on data moving underneath them. The last two numbers are the main point, since the real register cannot be made to fail on demand.
The sandbox credentials, the test company numbers and the reproducible error codes are listed in the developer reference.