Identity tiers
There are four distinct identity tiers in the platform. They look similar from the outside but have different verification requirements, different ownership rules, and different home tables. Getting them confused is the most common cause of "wrong endpoint" bugs.
The four tiers
| Tier | Who they are | Table | Verification |
|---|---|---|---|
| 1 | Seismic, the platform itself | None | None |
| 2 | Org, a fintech that signs up to use Orchestration API. One org per fintech. | orgs | KYB |
| 3 | Org admin, a human with dashboard credentials, member of an org. Can mint API keys, manage memberships, drive their org's KYB. | users + org_memberships | None directly. If they're a UBO/director/signer, their personal info travels in their org's KYB submission as associated_persons[]. |
| 4 | End-customer, an individual or business that the org onboards onto rails to move money. | customer_individuals / customer_businesses | KYC (individuals) or KYB (businesses), driven via the polymorphic /v0/customers/* surface. |
Worked examples
Solo freelancer using ramps directly. Alice signs up at seismic.systems. The signup flow creates her org (Tier 2), a one-person business, and her personal user (Tier 3). She drives her own org's KYB via /v0/org/kyb/*. Then she creates a customer for herself (Tier 4) via POST /v0/customers with type: "individual". That customer represents her as the end-user. She drives KYC by PUT /v0/customers/{id}/kyc/profile followed by POST /v0/customers/{id}/kyc/submit.
Neobank onboarding individuals. Acme Inc. signs up to move money for its app's users. Acme's CFO Bob is a Tier-3 user. Acme is Tier 2 (drives KYB). Bob mints an API key and his app starts creating one customer per signed-up app user (Tier 4) with type: "individual". Each Tier-4 customer goes through KYC via the polymorphic customer surface.
Marketplace with business sellers. Same as above, except Acme's customers are themselves businesses. Acme creates customers with type: "business" via POST /v0/customers. The same submit / state / resync endpoints handle KYB instead of KYC, picked off the type discriminator.
What each tier ISN'T
- A Tier-3 admin does not undergo personal KYC to log in. The dashboard credential is just for managing the org's resources.
- A Tier-4 end-customer is not a member of an org in the auth sense. They live in
customer_individuals/customer_businessesand have no credentials or memberships. They're a "person identity" pointer, nothing more. - The org's own KYB does not include personal KYC for arbitrary employees, only those listed as
associated_persons(UBOs/directors/signers).
Where each verification flow lives
- Tier-2 KYB:
/v0/org/kyb/*, keyed onorgs.id, one submission per org. - Tier-4 KYC / KYB:
/v0/customers/*, the polymorphic customer surface.type: "individual"drives KYC,type: "business"drives KYB. The same/kyc/submit,/kyc/state,/kyc/resync,/kyc/documents, and/kyc-link/rotateendpoints serve both.
If you're ever unsure whether to use /orgs/kyb or /customers/*: ask whose verification this is. The org's? /orgs/kyb. An end-user the org is onboarding? /customers/*.