> ## Documentation Index > Fetch the complete documentation index at: https://docs.baselayer.com/llms.txt > Use this file to discover all available pages before exploring further. # Start a direct verification > Verifies an identity you collected: an individual, or an individual and the business they operate. Verification runs asynchronously: the request is accepted with a `202` and the verification — poll `GET /issuance/identities/verifications/{verification_id}` or subscribe to the `Verification.completed` and `Verification.failed` webhooks for the outcome. The body is chosen by `type`: `INDIVIDUAL` verifies `individual` alone, `BUSINESS` verifies `individual` with `business` and the link between them. It requires an `Idempotency-Key`. To re-verify an individual you already verified, use `POST /issuance/identities/individuals/{individual_ref}/reverify`. This is direct verification: you send an identity you collected. For a hosted enrollment session, where the applicant completes your published journey on Baselayer's page, use `POST /onboarding/sessions`. ## OpenAPI ````yaml /api-reference/openapi.json post /issuance/identities/verifications openapi: 3.1.0 info: title: baselayer-api-service version: 0.1.0 servers: - url: https://api.baselayer.com/ security: [] paths: /issuance/identities/verifications: post: tags: - Identities summary: Start a direct verification description: >- Verifies an identity you collected: an individual, or an individual and the business they operate. Verification runs asynchronously: the request is accepted with a `202` and the verification — poll `GET /issuance/identities/verifications/{verification_id}` or subscribe to the `Verification.completed` and `Verification.failed` webhooks for the outcome. The body is chosen by `type`: `INDIVIDUAL` verifies `individual` alone, `BUSINESS` verifies `individual` with `business` and the link between them. It requires an `Idempotency-Key`. To re-verify an individual you already verified, use `POST /issuance/identities/individuals/{individual_ref}/reverify`. This is direct verification: you send an identity you collected. For a hosted enrollment session, where the applicant completes your published journey on Baselayer's page, use `POST /onboarding/sessions`. operationId: issuance_identities_verifications_create parameters: - name: Idempotency-Key in: header required: true schema: type: string description: >- Required. An opaque key, ideally a UUID: a second request with the same key, path and body answers with the verification the first one created, marked `Idempotent-Replayed: true`; the same key with a different request is refused with 422. Keys are scoped to your application. title: Idempotency-Key description: >- Required. An opaque key, ideally a UUID: a second request with the same key, path and body answers with the verification the first one created, marked `Idempotent-Replayed: true`; the same key with a different request is refused with 422. Keys are scoped to your application. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/v1.CreateVerificationRequest' application/vnd.baselayer.v1+json: schema: $ref: '#/components/schemas/v1.CreateVerificationRequest' responses: '202': description: Response content: application/json: schema: $ref: '#/components/schemas/v1.Verification' application/vnd.baselayer.v1+json: schema: $ref: '#/components/schemas/v1.Verification' headers: Location: description: The verification to poll. schema: type: string Idempotent-Replayed: description: >- `true` when the verification was answered from an earlier request with the same `Idempotency-Key`. schema: type: string '409': description: A request with this `Idempotency-Key` is still being processed. content: application/json: schema: $ref: '#/components/schemas/Error' title: IdempotencyKeyConflict description: >- A request with this idempotency key is being processed and its resource could not be returned yet. Retry with the same key. examples: - type: idempotency_key_conflict code: 6701 message: >- A request with this idempotency key is being processed and its resource could not be returned yet. Retry with the same key. metadata: {} '422': description: >- The body or the `Idempotency-Key` header is invalid, or the key was already used with a different request. content: application/json: schema: $ref: '#/components/schemas/Error' title: IdempotencyKeyPayloadMismatch description: >- This idempotency key was already used with a different request. Send a new key for a new request; see metadata.resource_id for the resource the key already names. examples: - type: idempotency_key_payload_mismatch code: 6700 message: >- This idempotency key was already used with a different request. Send a new key for a new request; see metadata.resource_id for the resource the key already names. metadata: {} security: - APIKeyHeader: [] components: schemas: v1.CreateVerificationRequest: description: >- A direct verification, chosen by ``type``. Re-verify an individual with ``POST /issuance/identities/individuals/{individual_ref}/reverify``. discriminator: mapping: BUSINESS: '#/components/schemas/v1.BusinessVerificationRequest' INDIVIDUAL: '#/components/schemas/v1.IndividualVerificationRequest' propertyName: type oneOf: - $ref: '#/components/schemas/v1.IndividualVerificationRequest' - $ref: '#/components/schemas/v1.BusinessVerificationRequest' title: CreateVerificationRequest v1.Verification: description: >- A verification of an individual, or of an individual and the business they operate, submitted directly. The body of every ``/issuance/identities/verifications`` route and of the ``Verification.*`` webhooks. properties: verification_id: description: Unique id of the verification. format: uuid title: Verification Id type: string type: $ref: '#/components/schemas/v1.VerificationType' description: Whether a business is verified too. state: $ref: '#/components/schemas/v1.VerificationState' description: Lifecycle state of the verification workflow. automated_verdict: anyOf: - $ref: '#/components/schemas/v1.OnboardingVerdict' - type: 'null' default: null description: >- What the checks concluded, `APPROVED` or `UNDER_REVIEW`; null until the verification completes. verdict: anyOf: - $ref: '#/components/schemas/v1.OnboardingVerdict' - type: 'null' default: null description: >- The effective verdict: your reviewer's decision when one was made, otherwise `automated_verdict`. terminal_reason: anyOf: - $ref: '#/components/schemas/v1.IdentitySubmissionTerminalReasonResponse' - type: 'null' default: null description: >- Typed state and detail when the workflow ended in FAILED; null otherwise. individual_ref: anyOf: - type: string - type: 'null' default: null description: >- Your pairwise reference to the verified individual, stable across re-verification; set once the verification completes and is approved. title: Individual Ref business_ref: anyOf: - type: string - type: 'null' default: null description: >- Your pairwise reference to the verified business, when the verification covered one. title: Business Ref business_operator_link_status: anyOf: - $ref: '#/components/schemas/v1.BusinessOperatorLinkStatus' - type: 'null' default: null description: >- Status of the individual-operates-business link as of this verification. reference_id: anyOf: - type: string - type: 'null' default: null description: Caller-supplied correlation id. title: Reference Id idempotency_key: anyOf: - type: string - type: 'null' default: null description: The `Idempotency-Key` the verification was created with. title: Idempotency Key environment: $ref: '#/components/schemas/v1.ApplicationType' description: The environment the verification ran in. created_at: description: When the verification was created. format: date-time title: Created At type: string completed_at: anyOf: - format: date-time type: string - type: 'null' default: null description: When the verification reached a terminal status. title: Completed At required: - verification_id - type - state - environment - created_at title: Verification (v1) type: object Error: properties: type: type: string title: Type description: >- Stable snake_case name of the error. Branch on this, never on `message`. code: type: integer title: Code description: Integer catalog code of the error. message: type: string title: Message description: For a human reading a log; not stable and not localized. metadata: additionalProperties: true type: object title: Metadata description: Context documented per `type`. request_id: anyOf: - type: string - type: 'null' title: Request Id description: The `X-Request-ID` of the failed request. type: object required: - type - code - message title: Error description: The one body of every error a KYA route answers. v1.BusinessVerificationRequest: additionalProperties: false description: Verifies an individual together with the business they operate. properties: type: const: BUSINESS description: >- `BUSINESS` verifies `individual` together with `business` and the link between them. title: Type type: string reference_id: anyOf: - maxLength: 128 type: string - type: 'null' default: null description: Caller-supplied correlation id. title: Reference Id individual: $ref: '#/components/schemas/v1.IndividualIdentityPayload' description: The individual who operates the business. business: $ref: '#/components/schemas/v1.BusinessIdentityPayload' description: The business the individual operates. required: - type - individual - business title: BusinessVerificationRequest (v1) type: object v1.IndividualVerificationRequest: additionalProperties: false description: Verifies an individual you collected. properties: type: const: INDIVIDUAL description: '`INDIVIDUAL` verifies the individual alone.' title: Type type: string reference_id: anyOf: - maxLength: 128 type: string - type: 'null' default: null description: Caller-supplied correlation id. title: Reference Id individual: $ref: '#/components/schemas/v1.IndividualIdentityPayload' description: The identity to verify. required: - type - individual title: IndividualVerificationRequest (v1) type: object v1.VerificationType: description: |- What a verification verifies: an ``INDIVIDUAL`` alone, or an individual together with the ``BUSINESS`` they operate. enum: - INDIVIDUAL - BUSINESS title: VerificationType type: string v1.VerificationState: description: |- A verification's lifecycle as a customer reads it: the workflow's states, with an internal stop reported as ``FAILED``. enum: - PENDING - EXECUTING - WAITING - COMPLETED - FAILED - EXPIRED title: VerificationState type: string v1.OnboardingVerdict: description: Normalized onboarding verdict used across provider-specific outputs. enum: - APPROVED - UNDER_REVIEW - REJECTED title: OnboardingVerdict type: string v1.IdentitySubmissionTerminalReasonResponse: description: Typed explanation for a submission that did not complete. properties: state: $ref: '#/components/schemas/v1.TerminalReasonState' description: Terminal workflow state. message: anyOf: - type: string - type: 'null' default: null description: Human-readable detail recorded by the workflow. title: Message required: - state title: IdentitySubmissionTerminalReasonResponse (v1) type: object v1.BusinessOperatorLinkStatus: description: |- Your organization's status for the link between an individual and a business they operate. VERIFIED is earned by the full evidence recipe (TIN provided + IRS-matched + KYB-verified) on one of your own sessions, or decided by your organization; UNDER_REVIEW is every automatic shortfall; REJECTED is your organization's refusal, which stands until you decide again. Another organization's evidence or decision never changes it. enum: - VERIFIED - UNDER_REVIEW - REJECTED title: BusinessOperatorLinkStatus type: string v1.ApplicationType: enum: - sandbox - production title: ApplicationType type: string v1.IndividualIdentityPayload: additionalProperties: false description: The identity of an individual you collected, for verification. properties: first_name: description: Legal first name. maxLength: 128 minLength: 1 title: First Name type: string middle_name: anyOf: - maxLength: 128 type: string - type: 'null' default: null description: Legal middle name, if any. title: Middle Name last_name: description: Legal last name. maxLength: 128 minLength: 1 title: Last Name type: string dob: description: Date of birth (YYYY-MM-DD). format: date title: Dob type: string phone_number: description: Phone number in E.164 format. pattern: ^\+[1-9]\d{1,14}$ title: Phone Number type: string email: anyOf: - type: string - type: 'null' default: null description: Email address, if collected. title: Email address: description: >- Residential address as a single line; normalized server-side before verification. examples: - 1640 Riverside Drive, Hill Valley, CA 95420 maxLength: 500 minLength: 2 title: Address type: string national_id: description: >- US national id (SSN), nine digits; separators are accepted and stripped. Required: identity continuity is anchored on it, and a submission without one could never earn a individual_ref. title: National Id type: string required: - first_name - last_name - dob - phone_number - address - national_id title: IndividualIdentityPayload (v1) type: object v1.BusinessIdentityPayload: additionalProperties: false description: |- The business a customer asserts the individual operates. Exactly the ``POST /searches`` input surface — the submission backs a KYB BusinessSearch, so it accepts every lookup input that route does, with the same names and validation. Note the operator link can only auto-verify when a ``tin`` is supplied and the IRS confirms it; without one, KYB runs registry verification alone. properties: name: description: The name of the business to search for. examples: - White, Floyd and Cook maxLength: 500 minLength: 1 title: Name type: string address: description: The address of the business to search for. examples: - 155 Carla Circles Jordanfurt, OK 59066 maxLength: 500 minLength: 2 title: Address type: string officer_names: anyOf: - items: type: string type: array - type: 'null' default: null description: The officer names to include in the search. examples: - - Nathan Harrington - Alexander Wolfe title: Officer Names website: anyOf: - type: string minLength: 1 format: uri - type: 'null' default: null description: The website to include in the search. examples: - https://www.figueroa.com/ title: Website phone_number: anyOf: - maxLength: 24 type: string - type: 'null' default: null description: The phone number to include in the search. examples: - 436-502-9710 title: Phone Number email: anyOf: - maxLength: 64 type: string - type: 'null' default: null description: The email to include in the search. examples: - zacharymoore@example.com title: Email alternative_names: anyOf: - items: type: string type: array uniqueItems: true - type: 'null' default: null description: The alternative names to include in the search. examples: - - Joe's Pizza - Joe's Pizzeria title: Alternative Names tin: anyOf: - maxLength: 9 minLength: 9 type: string - type: 'null' default: null description: The TIN/EIN to search for. examples: - '732842774' title: Tin required: - name - address title: BusinessIdentityPayload (v1) type: object v1.TerminalReasonState: description: |- The terminal state a ``terminal_reason`` explains: only a failure carries one. enum: - FAILED title: TerminalReasonState type: string securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.