Business Pre.Fill: API Quickstart

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 Pre.Fill: Basics.

Overview

This quickstart covers:

Making a Pre.Fill request
Understanding the response structure
Selecting which registrations to display
Presenting options to applicants
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:

X-API-Key: your_api_key_here

Step 1: Make a Pre.Fill Request

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

Basic Request

import httpx
import json

async def get_business_prefill(
    officer_name: str,
    business_name: str = None,
    api_key: str = None
) -> dict:
    """
    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:
    dict: Pre.Fill response with business registrations
    """
    url = "https://api.baselayer.com/prefill"
    
    # 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 a JSON object containing the request details and an array of matching business registrations.

Response Structure

{
  "_request": {
    "officer_name": "LYNN VU",
    "business_name": "ALMA OASIS MED SPA",
    "similarity_threshold": null,
    "limit": null
  },
  "results": [
    {
      "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 deliverability indicators
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:

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

Prioritize registrations with:

business_name_match = "EXACT" first
business_name_match = "SIMILAR" second
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: Use the primary_address object
- 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:

{
  "name": "Alma Oasis Med Spa & IV Hydration, PC",
  "address": {
    "street": "1183 E Foothill Blvd Ste 135",
    "city": "Upland",
    "state": "CA",
    "zip": "91786"
  },
  "tin": "12-3456789"
}

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 Pre.Fill: Best Practices 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:

Fetch: GET request with officer name
Filter: Apply similarity thresholds (≥0.9 recommended)
Display: Show 1-3 top matches with manual fallback
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.