individual_ref (and a business_ref when a business is involved), which you use to mint credentials.
In the hosted flow, the person:
- Enters their phone number, date of birth and country.
- Types the code Baselayer texts them.
- Confirms their details.
Choosing a path
You need an org API key with identity submission permissions (see Authentication). Every organization API key already has them. For every route, webhook and state on each path, see Hosted vs. direct.Every identity, credential and audit log call goes to
https://api.baselayer.com with your key in the X-API-Key header. Baselayer reads your organization and application from that key, never from the request body, and every read is scoped to both. Baselayer’s public signing keys and revocation lists are served from https://registry.baselayer.com and need no key.Baselayer runs the phone and email checks only in hosted enrollment. A person you submit directly holds
phone_possession or email_possession only when you attest to it in attestations, and only once the verification is approved.Path A: Submit details directly
Direct submission needs the person’s full legal name, date of birth, phone number, address and SSN (
national_id), all collected by you. A submission missing any of them is refused.-
Submit, with
typeset toindividual(person only) orbusiness(person + the business they operate). Person fields usegiven_name,family_name,birthdate,phone_numberandaddress, andnational_idis typed:{ "type": "us_ssn", "value": "..." }. A business sendslegal_name,addressand, if you have it,tax_idas{ "type": "us_ein", "value": "..." }. It returns202right away, and verification runs in the background.See the API reference. -
Poll until
stateis terminal, or subscribe to theVerification.completedandVerification.failedwebhooks. Poll every 2 seconds. A person’s check usually finishes in seconds. A full business check can take minutes.See the API reference. -
Read the verdict:
verdict:APPROVED,UNDER_REVIEW, orREJECTED- plus the resulting
individual_ref - and
business_refandbusiness_operator_link(itsstatusandreasons), for abusinessverification findingssays why a verification did not produce what was asked, for example why it went to review
Idempotency-Key header. A request without one is refused with 422. Resending the same key and body returns the original verification, marked Idempotent-Replayed: true, instead of starting a second one.
Path B: Use hosted enrollment
Hosted enrollment needs only a journey published in Console. The person enters the rest. Hosted enrollment must be turned on for your organization first (see Hosted Enrollment). Start a session on that journey from your server and send the person to itsembed_url, in an iframe or by redirect. You get the outcome by webhook or by polling the session’s results. See Sessions and embedding for the steps and Hosted Enrollment to build the journey, or try the Hosted Enrollment Playground.
Verify someone again
Start a new direct verification with the person’s current details and a newIdempotency-Key. Send the same reference_id you used before: a reference_id you already sent names the same individual, so the individual_ref doesn’t change.
Check readiness before minting
Look up the identity to see:- Which checks it holds (
active_keys), each with itsbasis(verifiedorattested) andtime. - Which fields a credential minted now can share (
available_disclosure_paths). - How many businesses the person has an operator link to (
operator_link_count), and how many credentials they hold (credential_counts).
Troubleshooting
The reference returns 404
References belong only to the organization and application they were issued to. An individual_ref (starts with prn_) or business_ref (starts with bus_) returns the same 404 when it is:
- From another organization.
- From your other environment.
- One that was never issued.
Verification is still running
Verification runs in the background after the202, and a full business check can take minutes. Keep polling the original verification, or wait for the webhook. A new Idempotency-Key would start a second verification.
Verification needs review
An operator link landsunder_review instead of verified unless:
- The business has a
tax_id. - The IRS matches it to the business name.
- The business is verified against its state registry.
tax_id, the business can still be APPROVED, but the link waits for review. The link’s reasons say which of these it met and which it fell short on. See Who Can Act for a Business.
Minting is refused
Minting needs:- An approved identity that holds the keys behind every field you ask to share.
- For a business credential, a
verifiedoperator link and current business evidence.
- Check the identity’s
active_keysandavailable_disclosure_pathswithGET /issuance/identities/individuals/{individual_ref}. - Ask only for fields it can back, or verify the person again with the missing details.
- Mint again.
type: business verification for the pair. See Minting Credentials.
Error codes
Error codes
See every error response in the API Reference for direct verifications.