Skip to main content
Verify a consumer or business once to create an identity. Submit an identity you’ve already collected or embed Baselayer’s hosted verification flow. Both options create a durable principal_ref (and business_ref, if a business is involved), against which credentials can be minted. Using Baselayer’s hosted verification flow lets you complete consumer verification using the consumer’s name and phone number, and business verification using the business’s registered name and address. For individuals acting as an authorized representative of a business, Baselayer also validates the authority of the individual to act on behalf of the business.

​
Before you start

You need an org API key with identity submission permissions. Direct submission requires you to have already collected the person’s full legal name, DOB, phone number, address, and SSN. An incomplete identity can never earn a principal_ref. Hosted enrollment requires only a template configured for your org (see Path B below); the user supplies the rest.

​
Choosing a path

​
Path A: Submit an identity you already collected

  1. Submit. POST /identity_submissions/consumer (person only) or POST /identity_submissions/consumer_business (person + the business they operate). Both return 202 with a submission_id immediately — verification runs asynchronously.
  2. Poll or subscribe. GET /identity_submissions/{submission_id} until state is terminal, or subscribe to the OnboardingSession.completed webhook. Recommended: poll every 2 seconds; consumer KYC usually completes in seconds, a full KYB pipeline can take minutes.
  3. Read the verdict. APPROVED, UNDER_REVIEW, or REJECTED, plus the resulting principal_ref (and business_ref / business_operator_link_status, for a consumer+business submission).
Submissions are idempotent per idempotency_key — resubmitting the same key returns the original submission rather than starting a second verification.

​
Path B: Use the hosted enrollment interface

  1. Pick a template (optional). GET /onboarding/templates lists the flows configured for your org.
  2. Mint a session. POST /onboarding/sessions with a template_id returns an embed_url and a one-time session_token. Render the URL in an iframe, or redirect the applicant to it.
  3. The applicant completes the flow inside Baselayer’s hosted UI — you don’t call its internal steps yourself.
  4. Learn the outcome the same way as Path A: poll GET /identity_submissions/{id} (the session’s id is the submission_id) or receive the webhook.

​
Re-verifying an identity

POST /identities/principals/{principal_ref}/reverify starts a fresh verification cycle against the identity’s most recent submitted attributes — the principal_ref never changes. Use this instead of a fresh submission when an identity has expired.

​
Checking an identity before minting

GET /identities/principals/{principal_ref} tells you whether an identity is current (verification_state: CURRENT), which attributes it can attest to (active_keys), and which businesses a person is linked to (where applicable).

​
Troubleshooting