Skip to main content
These pages are for agent platforms, and businesses running their own agents, that verify people and businesses and give agents credentials. Verify a person, or a person and their business, once. You can submit details you already collected, or send the person through Baselayer’s hosted enrollment flow. If you verified a person yourself, you can also add them directly. Both give you a lasting individual_ref (and a business_ref when a business is involved), which you use to mint credentials. In the hosted flow, the person:
  1. Enters their phone number, date of birth and country.
  2. Types the code Baselayer texts them.
  3. Confirms their details.
A business is verified from its registered name and address. When a person acts for a business, Baselayer also checks that they may act for it. See Who Can Act for a Business.

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.
  1. Submit, with type set to individual (person only) or business (person + the business they operate). Person fields use given_name, family_name, birthdate, phone_number and address, and national_id is typed: { "type": "us_ssn", "value": "..." }. A business sends legal_name, address and, if you have it, tax_id as { "type": "us_ein", "value": "..." }. It returns 202 right away, and verification runs in the background.
    See the API reference.
  2. Poll until state is terminal, or subscribe to the Verification.completed and Verification.failed webhooks. Poll every 2 seconds. A person’s check usually finishes in seconds. A full business check can take minutes.
    See the API reference.
  3. Read the verdict:
    • verdict: APPROVED, UNDER_REVIEW, or REJECTED
    • plus the resulting individual_ref
    • and business_ref and business_operator_link (its status and reasons), for a business verification
    • findings says why a verification did not produce what was asked, for example why it went to review
Every verification needs an 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 its embed_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 new Idempotency-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 its basis (verified or attested) and time.
  • 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).
See the API reference. Next: Mint a credential.

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.
Call with a key from the application the person was verified in. See Sandbox and Testing.

Verification is still running

Verification runs in the background after the 202, 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 lands under_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.
Without a 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 verified operator link and current business evidence.
To fix it:
  1. Check the identity’s active_keys and available_disclosure_paths with GET /issuance/identities/individuals/{individual_ref}.
  2. Ask only for fields it can back, or verify the person again with the missing details.
  3. Mint again.
If the business evidence for the pair is over a year old, send a new type: business verification for the pair. See Minting Credentials.
See every error response in the API Reference for direct verifications.