Non-Document Verification API

Verify individual identities using credit bureaus and government databases without requiring document uploads. Non-document checks validate identity against multiple authoritative sources in real-time.

Database-Driven Verification

Non-document verification checks validate identity against credit bureaus and government databases. No document upload required - verification uses name, date of birth, and address data.

Key Features

Multi-bureau validation - Check against multiple credit bureaus simultaneously
2+2 verification - Require 2 identity matches + 2 address matches for higher confidence
No document upload - Frictionless verification using existing data
Real-time webhooks - Instant notifications when checks complete

Non-Document Check Object

A non-document check represents a non-document verification workflow that validates identity against credit bureaus and government databases.

Core Attributes

Field	Type	Description
`check_id`	uuid	Unique identifier for the non-document check
`entity_id`	uuid	ID of the individual entity being verified
`entity_name`	string	Name of the individual being verified
`status`	string	Check state: `pending`, `in_progress`, `completed`, `failed`, `error`
`outcome`	string	Verification result: `pending`, `clear`, `consider`, `attention`, `error`
`two_plus_two`	boolean	Whether 2+2 verification is enabled (2 identity + 2 address matches required)
`failure_details`	string	Detailed explanation if check did not pass
`created_at`	datetime	Check creation timestamp (ISO 8601)
`completed_at`	datetime	Check completion timestamp (ISO 8601), null if not completed
`created_by`	object	Profile who initiated the check (id, name, email)

Status Values

`pending`	Check created but not yet submitted to provider
`in_progress`	Check submitted and awaiting results
`completed`	Check finished with results available
`failed`	Check could not be completed (data issues, etc.)
`error`	System error occurred during check processing

Outcome Values

`pending`	Check not yet completed
`clear`	Identity verified successfully - all checks passed
`consider`	Partial matches found - manual review recommended
`attention`	Identity could not be verified - manual review required
`error`	Technical error prevented verification

Check Eligibility

POST /api/v1/non-document/eligibility/

Verify that an entity has the required data to perform a non-document check. This endpoint validates entity type, required fields (name, DOB, national ID), and complete address information.

Request Body

Parameter	Type	Required	Description
`entity_id`	uuid	Yes	ID of entity to check eligibility for

Response (200 OK)

{
  "eligible": true,
  "reason": "Entity meets all requirements for non-document verification",
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "entity_type": "individual",
  "missing_fields": []
}

Response - Not Eligible (200 OK)

{
  "eligible": false,
  "reason": "Entity data is incomplete",
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "entity_type": "individual",
  "missing_fields": [
    "date_of_birth",
    "national_id_number",
    "address_postal_code"
  ]
}

Initiate Non-Document Check

POST /api/v1/non-document/checks/

Initiate a new non-document identity verification check for an individual entity. The check is processed asynchronously, and you'll receive a webhook notification when it completes. Credits are charged after successful completion (not on initiation).

Request Body

Parameter	Type	Required	Description
`entity_id`	uuid	Yes	ID of individual entity to verify
`two_plus_two`	boolean	No	Enable 2+2 verification (requires 2 identity + 2 address matches). Default: `false`

Response (202 Accepted)

{
  "check_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "entity_name": "John Smith",
  "status": "in_progress",
  "outcome": "pending",
  "two_plus_two": true,
  "created_at": "2026-01-31T10:30:00Z",
  "created_by": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Jane Doe",
    "email": "[email protected]"
  }
}

Error Response - Not Eligible (400 Bad Request)

{
  "error": "Entity is not eligible for non-document check",
  "detail": "Entity data is incomplete. Missing: date_of_birth, national_id_number",
  "missing_fields": [
    "date_of_birth",
    "national_id_number"
  ],
  "entity_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error Response - Check In Progress (409 Conflict)

{
  "error": "Non-document check already in progress",
  "detail": "An active check exists for this entity",
  "existing_check_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "in_progress",
  "created_at": "2026-01-31T10:15:00Z"
}

Get Check Status

GET /api/v1/non-document/checks/{check_id}/

Retrieve current status and basic information for a non-document check. Use this endpoint to poll for completion or check current state.

Path Parameters

Parameter	Type	Description
`check_id`	uuid	ID of the non-document check

Response (200 OK)

{
  "check_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "entity_name": "John Smith",
  "status": "completed",
  "outcome": "clear",
  "two_plus_two": true,
  "failure_details": "",
  "created_at": "2026-01-31T10:30:00Z",
  "completed_at": "2026-01-31T10:32:15Z",
  "created_by": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Jane Doe",
    "email": "[email protected]"
  }
}

Get Detailed Results

GET /api/v1/non-document/checks/{check_id}/results/

Retrieve detailed non-document check results including bureau breakdown, match details, and credit scores (when available). Only available when check status is completed.

Path Parameters

Parameter	Type	Description
`check_id`	uuid	ID of the non-document check

Response (200 OK)

{
  "check_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "entity_name": "John Smith",
  "status": "completed",
  "outcome": "clear",
  "two_plus_two": true,
  "result_data": {
    "id": "64a9f2f8b5e1a3d2c4e7f9a1",
    "outcome": "clear"
  },
  "full_check_data": {
    "id": "64a9f2f8b5e1a3d2c4e7f9a1",
    "type": "non_document_check",
    "status": "complete",
    "result": {
      "outcome": "clear",
      "breakdown": {
        "identity_match": {
          "score": 95,
          "matches": 2,
          "sources": ["Experian", "Equifax"]
        },
        "address_match": {
          "score": 92,
          "matches": 2,
          "sources": ["TransUnion", "USPS"]
        },
        "credit_score": 750,
        "account_age_months": 84,
        "verification_level": "high"
      }
    },
    "entityName": "John Smith",
    "createdAt": "2026-01-31T10:30:00Z",
    "updatedAt": "2026-01-31T10:32:15Z"
  },
  "failure_details": "",
  "created_at": "2026-01-31T10:30:00Z",
  "completed_at": "2026-01-31T10:32:15Z",
  "created_by": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Jane Doe",
    "email": "[email protected]"
  },
  "cached": false
}

Error Response - Not Completed (400 Bad Request)

{
  "error": "Check not completed yet",
  "detail": "Check status is in_progress. Results are only available for completed checks.",
  "check_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "in_progress"
}

List Entity Checks

GET /api/v1/entities/{entity_id}/non-document-checks/

Retrieve all non-document checks for a specific entity, ordered by creation date (newest first).

Path Parameters

Parameter	Type	Description
`entity_id`	uuid	ID of the entity

Response (200 OK)

{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "entity_name": "John Smith",
  "total_checks": 2,
  "checks": [
    {
      "check_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "entity_name": "John Smith",
      "status": "completed",
      "outcome": "clear",
      "two_plus_two": true,
      "created_at": "2026-01-31T10:30:00Z",
      "completed_at": "2026-01-31T10:32:15Z",
      "created_by_name": "Jane Doe"
    },
    {
      "check_id": "8d0e7780-8536-51ef-b158-f18gd2g01bf8",
      "entity_name": "John Smith",
      "status": "completed",
      "outcome": "consider",
      "two_plus_two": false,
      "created_at": "2026-01-15T14:20:00Z",
      "completed_at": "2026-01-15T14:22:30Z",
      "created_by_name": "Bob Wilson"
    }
  ]
}

Submit Review Decision

POST /api/v1/non-document/checks/{check_id}/reviews/create/

Submit a manual review decision for a non-document check. Allows compliance/risk teams to override or confirm automated outcomes. The review updates the check's outcome and creates an auditable review record.

Path Parameters

Parameter	Type	Description
`check_id`	uuid	ID of the non-document check to review

Request Body

Parameter	Type	Required	Description
`decision`	string	Yes	Review decision: `approved`, `rejected`, or `flagged`
`notes`	string	Yes	Detailed explanation for the decision (minimum 10 characters)

Response (201 Created)

{
  "review_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "check_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "decision": "approved",
  "notes": "Manual review confirms identity matches. No adverse findings in credit history.",
  "reviewed_by": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Jane Doe",
    "email": "[email protected]"
  },
  "reviewed_at": "2026-01-31T11:00:00Z",
  "check_outcome": "clear"
}

Error Response - Invalid Notes (400 Bad Request)

{
  "notes": [
    "Ensure this field has at least 10 characters."
  ]
}

List Check Reviews

GET /api/v1/non-document/checks/{check_id}/reviews/

Retrieve all manual reviews submitted for a specific non-document check, ordered by review date (newest first).

Path Parameters

Parameter	Type	Description
`check_id`	uuid	ID of the non-document check

Response (200 OK)

{
  "check_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "entity_id": "550e8400-e29b-41d4-a716-446655440000\",
  "entity_name": "John Smith",
  "total_reviews": 2,
  "reviews": [
    {
      "review_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "decision": "approved",
      "notes": "Manual review confirms identity matches. No adverse findings in credit history.",
      "reviewed_by_name": "Jane Doe",
      "reviewed_at": "2026-01-31T11:00:00Z"
    },
    {
      "review_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "decision": "flagged",
      "notes": "Address verification shows minor discrepancy. Recommend additional documentation.",
      "reviewed_by_name": "Bob Wilson",
      "reviewed_at": "2026-01-31T10:45:00Z"
    }
  ]
}

Webhook Events

Non-document checks trigger webhook events at key points in the verification lifecycle. Configure webhooks in your webhook settings.

Available Events

Event Type	Description	Trigger
`non_document.check_initiated`	Check has been initiated	When check is successfully submitted to verification provider
`non_document.check_completed`	Check has completed	When verification provider completes the check with results
`non_document.check_failed`	Check failed	When check cannot be completed due to data issues or errors
`non_document.reviewed`	Manual review submitted	When a compliance/risk team member submits a review decision

Webhook Payload Example - Check Completed

{
  "event": "non_document.check_completed",
  "timestamp": "2026-01-31T10:32:15Z",
  "data": {
    "check_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "entity_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "outcome": "clear",
    "two_plus_two": true,
    "completed_at": "2026-01-31T10:32:15Z"
  }
}

Webhook Payload Example - Review Submitted

{
  "event": "non_document.reviewed",
  "timestamp": "2026-01-31T11:00:00Z",
  "data": {
    "check_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "entity_id": "550e8400-e29b-41d4-a716-446655440000",
    "review_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "decision": "approved",
    "outcome": "clear",
    "reviewed_at": "2026-01-31T11:00:00Z"
  }
}

Rate Limits

Non-document check endpoints are rate-limited to prevent abuse and ensure fair usage across all tenants.

Limits by Endpoint Type

Endpoint	Rate Limit	Window
Check Eligibility	100 requests	Per minute
Initiate Check	20 requests	Per minute
Get Status	100 requests	Per minute
Get Results	100 requests	Per minute
List Checks	100 requests	Per minute
Submit Review	50 requests	Per minute
List Reviews	100 requests	Per minute

Rate Limit Headers

All responses include rate limit information in headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706699460

Exceeded Rate Limit Response (429)

{
  "error": "Rate limit exceeded",
  "detail": "You have exceeded the rate limit for this endpoint. Please try again later.",
  "retry_after": 45
}