Consumer Checks: API Quickstart

This guide explains how to use the Baselayer API to:

Create a Person Search with multiple verification options
Poll for completion or listen for webhook events
Interpret the person verification results
Run standalone checks (OFAC, PEP, TIN, SCRA, MLA)
Add an individual to Portfolio Monitoring

For background on person verification concepts, check types, and when to use each approach, see Consumer Checks: Basics.

Overview

High-Level Flow

Submit a Person Search POST /person_searches
Wait for completion (poll or webhook) GET /person_searches/{id}/status or listen for PersonSearch.completed
Retrieve results GET /person_searches/{id}
Optionally: add to portfolio monitoring POST /portfolio/items with person_search_id

Base URL & Authentication

Base URL

Use the appropriate base URL in your integration:https://api.baselayer.com In the examples below, we refer to this as:

{{baseUrl}}

Authentication

All requests are authenticated using an API key via the X-API-Key header:

X-API-Key: {{apiKey}}

Step 1: Create a Person Search

Use the Person Search endpoint to submit a new individual for verification.

Endpoint

POST /person_searches
Content-Type: application/json

Request Body Example

{
  "first_name": "John",
  "last_name": "Doe",
  "ssn": "123456789",
  "middle_name": "Michael",
  "date_of_birth": "1985-06-15",
  "gender": "M",
  "address": "123 Main St, Anytown, CA 12345",
  "phone_number": "+14013059855",
  "email": "john.doe@example.com",
  "options": [
    "Order.Ofac",
    "Order.Pep",
    "Order.TinMatching",
    "Order.Liens",
    "Order.Litigations",
    "Order.Bankruptcy"
  ]
}

Required Fields

first_name → first name of the person (2–255 characters)
last_name → last name of the person (2–255 characters)
ssn → Social Security Number, either full 9-digit ("123456789") or last 4 ("6789")
options → at least one option from the available checks

Optional Fields

middle_name → middle name or initial
suffix → e.g., “Jr.”, “Sr.”
title → e.g., “Mr.”, “Mrs.”
date_of_birth → date of birth (format: "1990-01-15"; required for MLA checks)
gender → "M" or "F"
marital_status → e.g., "married", "single", "divorced"
address → the individual’s address; the state is used to scope lien searches if Order.Liens is selected
phone_number → E.164 format (e.g., "+14013059855")
email → email address

Recommendation: Submit as much information as available. Optional fields build richer person profiles in Baselayer and enable stronger matching over time.

Available Options

Order.Ofac → OFAC sanctions screening
Order.Pep → Politically Exposed Persons screening
Order.TinMatching → IRS TIN verification
Order.Liens → Personal lien records
Order.Litigations → Litigation and docket records
Order.Bankruptcy → Personal bankruptcy records
Order.Scra → Servicemembers Civil Relief Act status (requires full 9-digit SSN)
Order.Mla → Military Lending Act coverage (requires full 9-digit SSN and date_of_birth)

Note: If the required inputs for Order.Scra or Order.Mla are not included in the request, those checks will not run. Ensure your payload includes full SSN and, for MLA, date of birth before selecting these options.

Sample Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "state": "PENDING",
  "created_at": "2025-12-11T01:36:29.945076",
  "updated_at": null,
  "tin_matched": null,
  "person": {
    "id": "36e43bc6-c809-4fa4-958d-f09ff40b8156",
    "first_name": "John",
    "last_name": "Doe",
    "ssn": "XXXXX6789",
    "middle_name": "Michael",
    "date_of_birth": "1985-06-15",
    "gender": "M",
    "phone_number": "+14013059855",
    "email": "john.doe@example.com",
    "dockets": [],
    "liens": [],
    "watchlist_hits": []
  },
  "error": null,
  "warnings": []
}

Key Fields to Capture

id — the person search id (used for polling, retrieval, and portfolio monitoring)
person.id — the person id (persists across searches for the same individual)
state — PENDING at creation, EXECUTING while processing, then COMPLETED or FAILED (or CANCELLED if the request is cancelled before finishing)
tin_matched — null while pending, true/false once TIN verification completes (only present when Order.TinMatching is requested)

Step 2: Wait for Completion

Person Searches are asynchronous by default - please review our Synchronous & Asynchronous Request Execution guide for further details. You have two options for determining when results are ready: polling or webhooks.

Option A: Polling

Use the status endpoint to check search progress.

GET /person_searches/{id}/status

Sample Response (completed)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "state": "COMPLETED",
  "error": null,
  "warnings": [],
  "person": {
    "id": "36e43bc6-c809-4fa4-958d-f09ff40b8156",
    "first_name": "John",
    "last_name": "Doe",
    "ssn": "XXXXX6789"
  }
}

Poll until state is COMPLETED or FAILED. A reasonable polling interval is every 2–5 seconds.

Option B: Webhooks

Baselayer emits webhook events at each stage of the Person Search lifecycle. Configure your webhook endpoint in the Console under Settings → Webhooks. PersonSearch.submitted Emitted immediately when the search is created. Confirms receipt of the request. PersonSearch.completed Emitted when all requested checks have finished. The webhook payload includes the full person object with all results (dockets, liens, watchlist hits). PersonSearch.failed Emitted if the search could not be completed. The error field will describe the failure reason. PersonSearch.updated Emitted if a result changes later, for example when an IRS outage clears and tin_matched is filled in.

Webhook Payload Structure

All Person Search webhook events share the same structure:

{
  "__event__": {
    "type": "PersonSearch.completed",
    "origin": "api"
  },
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "state": "COMPLETED",
  "created_at": "2025-12-11T01:36:29.945076",
  "updated_at": "2025-12-11T01:36:35.123456",
  "person": {
    "id": "36e43bc6-c809-4fa4-958d-f09ff40b8156",
    "first_name": "John",
    "last_name": "Doe",
    "ssn": "XXXXX6789",
    "dockets": [...],
    "liens": [...],
    "watchlist_hits": [...]
  },
  "error": null,
  "warnings": []
}

Tip: Webhooks are the recommended approach for production integrations. They eliminate polling overhead and deliver results as soon as they are available.

Step 3: Retrieve Full Results

Once the search is complete, retrieve the full person record with all verification results.

Endpoint

GET /person_searches/{id}

Sample Response (completed with results)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "state": "COMPLETED",
  "created_at": "2025-12-11T01:36:29.945076",
  "updated_at": "2025-12-11T01:36:35.123456",
  "tin_matched": true,
  "person": {
    "id": "36e43bc6-c809-4fa4-958d-f09ff40b8156",
    "first_name": "John",
    "last_name": "Doe",
    "ssn": "XXXXX6789",
    "middle_name": "Michael",
    "suffix": null,
    "title": null,
    "date_of_birth": "1985-06-15",
    "gender": "M",
    "marital_status": null,
    "phone_number": "+14013059855",
    "email": "john.doe@example.com",
    "created_at": "2025-12-11T01:36:29.000000Z",
    "updated_at": "2025-12-11T01:36:35.000000Z",
    "dockets": [
      {
        "docket_number": "2024-CV-12345",
        "title": "Smith v. Doe",
        "risk_level": "medium",
        "match_level": "EXACT",
        "court": "Superior Court of California",
        "state": "CA",
        "date_filed": "2024-03-15"
      }
    ],
    "liens": [
      {
        "filing_type": "consensual.ucc",
        "state": "CA",
        "filing_date": "2023-06-20",
        "status": "Active"
      }
    ],
    "watchlist_hits": []
  },
  "error": null,
  "warnings": []
}

Interpreting Key Result Fields

tin_matched: IRS confirmation that the SSN is valid and belongs to the input name. true = confirmed, false = mismatch, null = pending (likely IRS outage). dockets — litigation and bankruptcy records. Use risk_level (high/medium/low) and match_level (EXACT/SIMILAR) to assess severity and relevance. For detailed evaluation guidance, see Litigation & Bankruptcy Search: Best Practices. liens — personal lien filings including tax liens, judgment liens, and UCC filings. Review status to determine whether liens are active or released. For detailed evaluation guidance, see Lien Search: Best Practices. watchlist_hits — matches against OFAC and PEP lists. Any positive match should be treated as a high-priority review item.

Step 4: Standalone Checks (Optional)

For lightweight, targeted verifications, use the standalone endpoints. These do not require creating a Person Search and return results directly.

TIN Verification

Verify an individual’s SSN against IRS records.

POST /tin_verifications
Content-Type: application/json

{
  "name": "John Doe",
  "tin": "123456789"
}

Note: An error will be raised if the IRS validation service is experiencing an outage. Check status.baselayer.com for service updates.

OFAC Screening

Search for OFAC matches by name.

POST /ofac/searches
Content-Type: application/json

{
  "name": "John Doe",
  "similarity_threshold": 0.9,
  "limit": 5
}

similarity_threshold → controls match sensitivity (0.0 to 1.0, default 0.9). Lower values return more potential matches; higher values return only close matches.
limit → number of results to return (default 1, max 50)

PEP Screening

Search for Politically Exposed Persons matches by name.

POST /pep/searches
Content-Type: application/json

{
  "name": "John Doe",
  "similarity_threshold": 0.9,
  "limit": 5
}

similarity_threshold → controls match sensitivity (0.0 to 1.0, default 0.9). Lower values return more potential matches; higher values return only close matches.
limit → number of results to return (default 1, max 50)

SCRA Status

Check Servicemembers Civil Relief Act coverage. Requires full 9-digit SSN and evaluates coverage as of the specified date_of_interest.

POST /scra/searches
Content-Type: application/json

{
  "first_name": "John",
  "last_name": "Doe",
  "ssn": "123456789",
  "birth_date": "1985-06-15",
  "date_of_interest": "2025-12-11"
}

MLA Coverage

Check Military Lending Act covered borrower status. Requires full 9-digit SSN and birth_date.

POST /mla/searches
Content-Type: application/json

{
  "first_name": "John",
  "last_name": "Doe",
  "ssn": "123456789",
  "birth_date": "1985-06-15"
}

Step 5: Add Individual to Portfolio Monitoring

After completing a Person Search, you can add the individual to your monitored portfolio for ongoing surveillance.

Endpoint

POST /portfolio/items
Content-Type: application/json

Request Body

{
  "person_search_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "group_id": "optional-group-uuid"
}

Note: person_search_id should be the id field from the Person Search response (Step 1). The group_id is optional and allows you to organize individuals into portfolio groups.

Once added, Baselayer monitors the individual on the same frequency and policy structure used for business items. Changes to watchlists, liens, litigations, and other monitored attributes will appear in your portfolio updates and notifications. For comprehensive guidance on portfolio monitoring configuration, see Portfolio Monitoring: Basics.

End-to-End Flow Summary

A typical integration to verify and monitor an individual with Baselayer looks like this:

Submit the Person Search
- Call POST /person_searches with identity details and desired options.
- Store the returned id (person search id) and person.id.
Wait for completion
- Poll GET /person_searches/{id}/status until state is COMPLETED or FAILED.
- Or listen for the PersonSearch.completed webhook.
Review results
- Retrieve full results via GET /person_searches/{id}.
- Evaluate dockets, liens, and watchlist_hits against your risk policy.
Add to portfolio monitoring (optional)
- Call POST /portfolio/items with person_search_id from step 1.
- Assign to a portfolio group if applicable.
Receive ongoing updates
- Portfolio monitoring detects changes at your configured frequency.
- Review updates in the Console or via GET /portfolio/updates.

This flow ensures that the individuals behind every business in your portfolio are verified at onboarding and continuously monitored for changes.

KEY CONCEPTS

PLAYBOOKS

PRODUCT GUIDES

Consumer Checks: API Quickstart

Overview

High-Level Flow

Base URL & Authentication

Base URL

Authentication

Step 1: Create a Person Search

Endpoint

Request Body Example

Required Fields

Optional Fields

Available Options

Sample Response

Key Fields to Capture

Step 2: Wait for Completion

Option A: Polling

Sample Response (completed)

Option B: Webhooks

Webhook Payload Structure

Step 3: Retrieve Full Results

Endpoint

Sample Response (completed with results)

Interpreting Key Result Fields

Step 4: Standalone Checks (Optional)

TIN Verification

OFAC Screening

PEP Screening

SCRA Status

MLA Coverage

Step 5: Add Individual to Portfolio Monitoring

Endpoint

Request Body

End-to-End Flow Summary

​Overview

​High-Level Flow

​Base URL & Authentication

​Base URL

​Authentication

​Step 1: Create a Person Search

​Endpoint

​Request Body Example

​Required Fields

​Optional Fields

​Available Options

​Sample Response

​Key Fields to Capture

​Step 2: Wait for Completion

​Option A: Polling

Sample Response (completed)

​Option B: Webhooks

Webhook Payload Structure

​Step 3: Retrieve Full Results

​Endpoint

​Sample Response (completed with results)

​Interpreting Key Result Fields

​Step 4: Standalone Checks (Optional)

​TIN Verification

​OFAC Screening

​PEP Screening

​SCRA Status

​MLA Coverage

​Step 5: Add Individual to Portfolio Monitoring

​Endpoint

​Request Body

​End-to-End Flow Summary

Overview

High-Level Flow

Base URL & Authentication

Base URL

Authentication

Step 1: Create a Person Search

Endpoint

Request Body Example

Required Fields

Optional Fields

Available Options

Sample Response

Key Fields to Capture

Step 2: Wait for Completion

Option A: Polling

Option B: Webhooks

Step 3: Retrieve Full Results

Endpoint

Sample Response (completed with results)

Interpreting Key Result Fields

Step 4: Standalone Checks (Optional)

TIN Verification

OFAC Screening

PEP Screening

SCRA Status

MLA Coverage

Step 5: Add Individual to Portfolio Monitoring

Endpoint

Request Body

End-to-End Flow Summary