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

# Consumer Checks: API Quickstart

> Run a Person Search or a standalone check by API, read the results, and add the person to monitoring.

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](https://docs.baselayer.com/docs/consumer-checks-basics.md).

***

### 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:

```text theme={null}
{{baseUrl}}
```

#### Authentication

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

```http theme={null}
X-API-Key: {{apiKey}}
```

***

### Step 1: Create a Person Search

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

#### Endpoint

```http theme={null}
POST /person_searches
Content-Type: application/json
```

#### Request Body Example

```json theme={null}
{
  "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

```json theme={null}
{
  "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](https://docs.baselayer.com/docs/synchronous-asynchronous-request-execution.md) 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.

```http theme={null}
GET /person_searches/{id}/status
```

##### Sample Response (completed)

```json theme={null}
{
  "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:

```json theme={null}
{
  "__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

```http theme={null}
GET /person_searches/{id}
```

#### Sample Response (completed with results)

```json theme={null}
{
  "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](https://docs.baselayer.com/docs/litigation-bankruptcy-search-best-practices.md).

**`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](https://docs.baselayer.com/docs/lien-searching-best-practices.md).

**`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.

```http theme={null}
POST /tin_verifications
Content-Type: application/json
```

```json theme={null}
{
  "name": "John Doe",
  "tin": "123456789"
}
```

> **Note:** An error will be raised if the IRS validation service is experiencing an outage. Check [status.baselayer.com](https://status.baselayer.com) for service updates.

#### OFAC Screening

Search for OFAC matches by name.

```http theme={null}
POST /ofac/searches
Content-Type: application/json
```

```json theme={null}
{
  "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.

```http theme={null}
POST /pep/searches
Content-Type: application/json
```

```json theme={null}
{
  "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`.

```http theme={null}
POST /scra/searches
Content-Type: application/json
```

```json theme={null}
{
  "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`**.

```http theme={null}
POST /mla/searches
Content-Type: application/json
```

```json theme={null}
{
  "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

```http theme={null}
POST /portfolio/items
Content-Type: application/json
```

#### Request Body

```json theme={null}
{
  "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](https://docs.baselayer.com/docs/portfolio-monitoring.md).

***

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.