Guides
API Reference

Consumer Checks: API Quickstart

This guide explains how to use the Baselayer API to:

  1. Create a Person Search with multiple verification options
  2. Poll for completion or listen for webhook events
  3. Interpret the person verification results
  4. Run standalone checks (OFAC, PEP, TIN, SCRA, MLA)
  5. 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

  1. Submit a Person Search

    POST /person_searches

  2. Wait for completion (poll or webhook)

    GET /person_searches/{id}/status or listen for PersonSearch.completed

  3. Retrieve results

    GET /person_searches/{id}

  4. 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": "[email protected]",
  "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 and SCRA 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": "SUBMITTED",
  "created_at": "2025-12-11T01:36:29.945076",
  "updated_at": null,
  "tin_matched": null,
  "tin_match_type": null,
  "person": {
    "id": "36e43bc6-c809-4fa4-958d-f09ff40b8156",
    "first_name": "John",
    "last_name": "Doe",
    "padded_last_four_ssn": "XXXXX6789",
    "middle_name": "Michael",
    "date_of_birth": "1985-06-15",
    "gender": "M",
    "phone_number": "+14013059855",
    "email": "[email protected]",
    "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 — SUBMITTED at creation, transitions to COMPLETED or FAILED
  • tin_matched — null while pending, true/false once TIN verification completes (only present when Order.TinMatching is requested)
  • tin_match_type — SSN, EIN, or UNKNOWN; indicates the type of TIN matched against IRS records

Step 2: Wait for Completion

Person Searches are asynchronous by default - please review our Synchronous vs. Asynchronous 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",
    "padded_last_four_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.

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",
    "padded_last_four_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,
  "tin_match_type": "SSN",
  "person": {
    "id": "36e43bc6-c809-4fa4-958d-f09ff40b8156",
    "first_name": "John",
    "last_name": "Doe",
    "padded_last_four_ssn": "XXXXX6789",
    "middle_name": "Michael",
    "suffix": null,
    "title": null,
    "date_of_birth": "1985-06-15",
    "gender": "M",
    "marital_status": null,
    "phone_number": "+14013059855",
    "email": "[email protected]",
    "created_at": "2025-12-11T01:36:29.000000Z",
    "updated_at": "2025-12-11T01:36:35.000000Z",
    "dockets": [
      {
        "case_number": "2024-CV-12345",
        "case_title": "Smith v. Doe",
        "risk_level": "medium",
        "match_level": "EXACT",
        "court": "Superior Court of California",
        "state": "CA",
        "filing_date": "2024-03-15"
      }
    ],
    "liens": [
      {
        "type": "UCC.CONSENSUAL",
        "filing_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). tin_match_type indicates the type of TIN matched (SSN, EIN, or UNKNOWN).

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:

  1. Submit the Person Search

    • Call POST /person_searches with identity details and desired options.
    • Store the returned id (person search id) and person.id.

  2. Wait for completion

    • Poll GET /person_searches/{id}/status until state is COMPLETED or FAILED.
    • Or listen for the PersonSearch.completed webhook.

  3. Review results

    • Retrieve full results via GET /person_searches/{id}.
    • Evaluate dockets, liens, and watchlist_hits against your risk policy.

  4. Add to portfolio monitoring (optional)

    • Call POST /portfolio/items with person_search_id from step 1.
    • Assign to a portfolio group if applicable.

  5. 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.

Updated 13 days ago