Skip to main content
Business customers complete Know Your Business verification inside the Etherfuse app. As a partner, you don’t drive KYB through the API; you authenticate the user with a kyb-scoped JWT and launch them into the app’s KYB flow, and the app collects everything and walks them through it.
1

(Optional) Pre-create the business and invite its members

This step is optional. If you skip it, your customer creates the business themselves when they first launch into KYB, and the app asks them for a company name and country. Pre-create it yourself when you want the organization and its members in place before anyone launches.Create the business with POST /ramp/organization and accountType: business. You may pass your own id (a UUID) to match an identifier from your own system. If you omit it, Etherfuse assigns one and returns it as organizationId. Pass country to generate the KYB onboarding at creation so the user lands straight in KYB. Omit it and they choose their country when they begin.
{
  "displayName": "Acme Inc.",
  "accountType": "business",
  "country": "MX"
}
The organizationId identifies the business. A person is identified separately by their customerId, the sub you sign into their JWT. The two are never interchangeable. To keep them apart, this guide writes organization ids as 00000000-0000-4000-8000-000000000001 and customer ids as cccccccc-cccc-4ccc-8ccc-cccccccccc01.
Now add the people who’ll complete KYB with POST /ramp/organization/00000000-0000-4000-8000-000000000001/member, two ways:
  • By email: the invite is accepted automatically the first time that email launches via your kyb JWT. You may pass an optional emailInviteLink to send them an email invite pointing at your own page.
  • By customerId: add an existing customer directly by their sub. No email is sent. A customerId exists only after that person has launched or exchanged a JWT via POST /auth/token.
{ "email": "[email protected]", "role": "member" }
You can change membership anytime: add a member, list members, remove a member, or revoke a pending invite.
2

Launch your users into their organization's KYB

Sign a user JWT with scope: kyb for the person signing in (their sub is their customerId) and hand their browser to /auth/launch with target: /kyb. If that person belongs to more than one organization, append ?org=<organizationId> to the target (for example target: /kyb?org=00000000-0000-4000-8000-000000000001) to choose which one. With a single organization it’s selected automatically. The signing and launch mechanics are in JWT User Authentication. This flow’s scope and target are in Business KYB. The launch lives on the app host, not the API host.If you pre-created the business, the user lands directly in its KYB flow (an emailed invite is accepted automatically at this point). If you didn’t, the app first prompts them to create the business, then continues into KYB.
3

Watch for status changes

Subscribe to the kyb_updated webhook. It fires whenever a business’s KYB status changes and carries the business’s organizationId and new status, so you learn the moment verification is approved (or needs attention) without anyone watching the app.To read the current state on demand, GET /ramp/organization/{id}/kyb/progress returns the status and requirement counts. When a customer created their own business and you only have their sub, GET /ramp/customer/{customer_id}/organization lists the businesses they belong to so you can find its organizationId.
Once a business is approved, it can transact. The forms, document collection, and review all live in the Etherfuse app. That’s the whole integration.