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

# Business Pre.Fill: API Quickstart

> Call Pre.Fill, show the results to applicants, and pass their choice into Business Search.

This guide walks through implementing Pre.Fill in your application, from making your first API request to presenting results to applicants and feeding data into Business Search.

For background on Pre.Fill concepts and use cases, see [Business Pre.Fill: Basics](https://docs.baselayer.com/docs/business-prefill-basics.md).

***

### Overview

This quickstart covers:

1. Making a Pre.Fill request
2. Understanding the response structure
3. Selecting which registrations to display
4. Presenting options to applicants
5. Using Pre.Fill results with Business Search

***

### Base URL & Authentication

#### Base URL

Use the appropriate base URL in your integration:

* `https://api.baselayer.com`

In examples below, we use `{{baseUrl}}` as a placeholder.

#### Authentication

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

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

***

### Step 1: Make a Pre.Fill Request

Pre.Fill uses a simple `GET` request to `/prefill/businesses` with the officer name as a required query parameter.

#### Basic Request

```python theme={null}
import httpx
import json

async def get_business_prefill(
    officer_name: str,
    business_name: str = None,
    api_key: str = None
) -> list:
    """
    Get business registrations for an officer
    
    Parameters:
    officer_name (str): The officer's full name
    business_name (str): Optional business name to match against
    api_key (str): Your Baselayer API key
    
    Returns:
    list: Pre.Fill response with business registrations
    """
    url = "https://api.baselayer.com/prefill/businesses"
    
    # Build query parameters
    params = {
        "officer_name": officer_name
    }
    
    if business_name:
        params["business_name"] = business_name
    
    headers = {
        "X-API-Key": api_key
    }
    
    try:
        async with httpx.AsyncClient() as client:
            response = await client.get(
                url,
                params=params,
                headers=headers
            )
            response.raise_for_status()
            return response.json()
    
    except Exception as e:
        print(f"Error fetching pre-fill data: {str(e)}")
        raise
```

***

### Step 2: Understanding the Response

Pre.Fill returns an array of matching business registrations.

#### Response Structure

```json theme={null}
[
    {
      "name": "Alma Oasis Med Spa & IV Hydration, PC",
      "issue_date": "2024-03-14",
      "state": "CA",
      "file_number": "6129643",
      "primary_address": {
        "id": "ddfed766-8315-4187-9632-7d3054f21cd9",
        "street": "1183 E Foothill Blvd Ste 135",
        "city": "Upland",
        "state": "CA",
        "zip": "91786",
        "latitude": 34.10714,
        "longitude": -117.63544,
        "rdi": "Commercial",
        "deliverable": true,
        "cmra": false,
        "url": "https://api.baselayer.com/addresses/ddfed766-...",
        "delivery_type": "HIGH_RISE"
      },
      "officers": [
        "Lynn Vu",
        "Lynn T Vu",
        "Maher Danhash"
      ],
      "alternative_names": [],
      "similarity_score": 1.0,
      "business_name_match": "SIMILAR"
    },
    // ... additional results
]
```

#### Key Response Fields

##### Per Registration

* **`name`**: Legal business name from SOS registration
* **`state`**: State of registration (e.g., "CA", "TX")
* **`issue_date`**: When the business was registered
* **`file_number`**: State filing number
* **`primary_address`**: Full address object with USPS validation indicators (`rdi`, `cmra`, `deliverable`, `delivery_type` — these may be `null` for some addresses)
* **`officers`**: Array of all officers listed on the registration
* **`similarity_score`**: Match quality between search name and officer (0-1)
* **`business_name_match`**: How well business name matches (EXACT, SIMILAR, NO\_MATCH)
* **`alternative_names`**: DBAs or previous names

***

### Step 3: Filtering and Prioritizing Results

Not all results should be presented to applicants. Use the match indicators to filter and prioritize.

#### Decision Framework

**Show a registration if:**

1. `similarity_score >= 0.9` (very close or exact name match)
2. `business_name_match` is "EXACT" or "SIMILAR" (if business name provided)
3. `primary_address` exists and is in the expected state/region

**Prioritize registrations with:**

1. `business_name_match = "EXACT"` first
2. `business_name_match = "SIMILAR"` second
3. Highest `similarity_score` values

**Typical display**: 1-3 most relevant registrations

***

### Step 4: Presenting Results to Applicants

Present filtered results as selectable options, always including a manual entry fallback.

#### UI Best Practices

**For each registration, display:**

* Business legal name (prominent)
* Business address (city, state)
* Formation state
* Officer list
* "Select" action button

#### Manual Entry Fallback

**Always provide a manual entry option** for cases where:

* Pre.Fill returns no results (sole props)
* None of the results are the correct business
* The applicant's business isn't recorded with officer names (NJ, WY)

***

### Step 5: Using Results with Business Search

Once an applicant selects a business from Pre.Fill results, use that information as input for a full Business Search to complete your KYB verification.

#### The Complete Workflow

##### 1. Call Pre.Fill with the verified officer name

* Use the name from your ID verification process
* Optionally include business name if you collected it

##### 2. Filter and display results to the applicant

* Show 1-3 top matches based on similarity scores
* Always include an "Enter manually" option

##### 3. Applicant selects their business

* They choose from the presented options, or
* They opt to enter details manually

##### 4. Extract data from the selected registration

* Business legal name: Use the `name` field
* Business address: Join the `primary_address` fields into one address string
  * Street: `primary_address.street`
  * City: `primary_address.city`
  * State: `primary_address.state`
  * ZIP: `primary_address.zip`

##### 5. Request the EIN from the applicant

* Show the pre-filled name and address
* Ask applicant to enter their Tax ID (EIN)
* This confirms they're actually an officer of the business

##### 6. Run Business Search with the combined data

* **Endpoint:** `POST /searches`
* **From Pre.Fill:** business name and address
* **From applicant:** EIN/Tax ID
* **Result:** Full KYB verification with registration standings, officers, sanctions, etc.

#### Business Search Request Format

When calling Business Search with Pre.Fill data, structure your request like this:

```json theme={null}
{
  "name": "Alma Oasis Med Spa & IV Hydration, PC",
  "address": "1183 E Foothill Blvd Ste 135, Upland, CA 91786",
  "tin": "123456789"
}
```

#### Key points:

* The `name` and `address` come directly from Pre.Fill
* The `tin` (EIN) comes from the applicant
* Business Search will verify all this information and return comprehensive KYB data

#### Why This Flow Works

This workflow gives you the best of both worlds:

✅ **Faster UX:** Applicants don't manually type business details
✅ **Accurate data:** Name and address come from official SOS records
✅ **Fraud prevention:** EIN requirement confirms legitimate ownership
✅ **Complete KYB:** Full verification through Business Search

The Pre.Fill data sets up Business Search for success by ensuring the name and address are accurate, while the EIN requirement maintains security.

***

### What's Next

After implementing Pre.Fill, see [Business Pre.Fill: Best Practices](https://docs.baselayer.com/docs/business-prefill-best-practices.md) for guidance on:

* Running KYC/ID verification before Pre.Fill
* Optimizing match thresholds for your use case
* Handling edge cases (sole props, NJ, large orgs)
* Requesting EIN after selection
* Fraud prevention strategies

***

### Summary

Pre.Fill implementation follows a simple pattern:

1. **Fetch**: GET request with officer name
2. **Filter**: Apply similarity thresholds (≥0.9 recommended)
3. **Display**: Show 1-3 top matches with manual fallback
4. **Verify**: Use selected data for Business Search

This creates a seamless auto-fill experience that reduces onboarding time while maintaining data accuracy and enabling full KYB verification.


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