Turn a prospect into an AML file, without retyping anything

An administrator creates it from Paramètres → Intégrations → Créer un environnement de test. Its files are invisible to every other organization, so your test data can never land in someone's compliance figures.

A sandbox never calls the Belgian registry: your tests would otherwise depend on a third party and on data that changes underneath them. These numbers, and only these, work.

The last two are the point. You cannot make the real registry fail on demand, so without them both branches of your retry logic ship untested.

Ask for the narrowest set that does your job. webhooks:manage lets your application register its own webhooks; reports:read is declared and grants nothing.

The response carries a hostedUrl: a link for your customer, valid 30 days, revocable, and audited on every open. Send it by email; it is not for you.

A 404 means the enterprise number does not exist: never retry it. A 500 means the registry is down: retry in a few minutes. Treating them alike breaks in one direction or the other.

POST /api/v2/onboardings/{id}/beneficiaries

{ "firstName": "Marie", "lastName": "Dupont",
  "role": "Gérant", "percentage": 75,
  "externalRef": "crm:company_person:42" }

curl -X POST .../onboardings/{id}/documents \
  -H "authorization: Bearer $TOKEN" \
  -F [email protected] -F kind=IDENTITY_CARD -F beneficiaryId={ownerId}

POST /api/v2/onboardings/{id}/submit

Name, role and share are enough to record an owner: send what you know, and the officer completes the rest, helped by the reading of the identity document attached to them. The file cannot be submitted while an owner lacks a birth date or an identity document type and number, and each owner's missing says which.

{
  "id": "cmf3k2l0000abc",
  "status": "VALIDATED",
  "risk": { "level": "LOW", "score": 120, "max": 530, "ratio": 23 },
  "externalRef": "crm:company:abc123",
  "company": { "name": "EXAMPLE SRL", "vatNumber": "BE0675566990" }
}

risk is always an object, never null. On a file nobody has assessed yet, its fields are null.

GET /api/v2/register/companies/BE0403091220

{
  "enterpriseNumber": "0403091220",
  "name": "SOLVAY",
  "score": { "grade": "B", "score": 78, "zScoreZone": "safe" },
  "financials": [{ "year": 2024, "revenue": 13500000000, ... }],
  "organization": { "isWatched": true, "isClient": false, "alertsCount": 2 }
}

These reads are not scoped to your organization, and that is deliberate: a register entry says the same thing to everyone, so you can ask about any company, onboarded or not. The organization block is the one part that differs between two callers, and it is what turns a public lookup into something a compliance officer can act on.

Watching is a PUT on the number rather than a toggle, so a retry after a dropped connection leaves the company watched instead of quietly unwatching it. changed tells a first call from a retry.

curl -X POST https://amlcompany.com/api/v2/verifications \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "purpose": "mandate",
        "enterpriseNumber": "BE0675566990",
        "expectedPerson": { "firstName": "Jean", "lastName": "Dupont" },
        "reference": "your-own-id-42" }'

{ "id": "cmg1v0k2x0000abc", "reference": "your-own-id-42",
  "status": "PENDING", "hostedUrl": "https://amlcompany.com/verification/...",
  "hostedUrlExpiresAt": "2026-10-02T12:00:00.000Z" }

Send hostedUrl to the person, or open it for them. On a desktop it shows a QR code, so they finish on the phone that carries itsme or a camera. The token needs verifications:write.

{ "id": "cmf9x2k10000",
  "kind": "verification.concluded",
  "data": { "subject": { "type": "verification", "id": "cmg1v0k2x0000abc" },
            "id": "cmg1v0k2x0000abc", "reference": "your-own-id-42",
            "purpose": "mandate", "status": "VERIFIED",
            "decision": "pass", "reasons": ["mandate.matched"] } }

GET /api/v2/verifications/cmg1v0k2x0000abc

{ "decision": "pass", "reasons": ["mandate.matched"],
  "identity": { "firstName": "Jean", "lastName": "Dupont",
                "birthDate": "1980-04-12", ... },
  "mandate": { "role": "Gérant", "since": "2017-05-09",
               "publicationId": "24338112", "signingAuthority": "unknown",
               "source": { "readAt": "2026-06-02T14:49:15Z",
                           "coverage": "complete" } } }

expectedPerson is a signal, not a filter: someone else verifying sends the check to review, never to a refusal. signingAuthority is always unknown, since holding a mandate is not the power to bind the company alone. We never return a national register number, a document serial, a facial image or the company's other managers.

The signed string is the timestamp, a dot, and the raw request body. Signing the body alone will never match, and neither will re-serialising the parsed JSON: sign the bytes you received.

const expected = "v1=" + crypto
  .createHmac("sha256", secret)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");

// Constant time, and refuse anything older than 5 minutes.
const a = Buffer.from(expected), b = Buffer.from(signature);
return a.length === b.length && crypto.timingSafeEqual(a, b);

Answer 2xx quickly, then do the work. A handler that finishes a long job before replying will time out and be retried, which is how duplicates are born. Deliveries are at least once, so make your handler idempotent on x-amlcompany-event-id.

We retry a 5xx, a 408, a 429 or a timeout up to 12 times over roughly a day, honouring Retry-After. Any other 4xx stops immediately. Redirects are never followed: configure the final URL.

Your endpoint must be publicly reachable over HTTPS. We refuse to deliver to private address space, including loopback and cloud metadata addresses.

{
  "error": { "code": "forbidden", "message": "Scope onboardings:write is required for this call" },
  "requestId": "9f1c8e2a-..."
}

Quote requestId when you contact us: it identifies the exact call in our logs.

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. A 429 adds Retry-After in seconds. The budget refills continuously rather than in one lump, so back off instead of spinning.

Register reads carry a second, separate budget: a monthly quota of lookups, set by your plan. Reaching it answers 402 with a quota object naming the cap and where you stand against it, until the month rolls over. A request you got wrong and an outage on our side are both uncounted.