Guides
API Reference
Start typing to search…

Business Search: Batch Searches

Batch Search: How to Run Bulk Searches in Baselayer

Batch Search allows you to process hundreds or thousands of Business Searches at once via CSV upload. It's the fastest way to onboard large customer lists, refresh existing portfolios, or prepare businesses for Portfolio Monitoring at scale.

This guide covers how to run batch searches through both the Console and API. For understanding individual Business Search results, see Business Search: Basics. For adding businesses to monitoring after verification, see Portfolio Monitoring.

Prerequisites

Before running a batch search, ensure you have:

1. What Batch Search Does

When you run a Batch Search, Baselayer:

  • Processes each business in your CSV file as an individual search
  • Applies any selected add-ons (Enhanced Search, Industry, Website Analysis, PEP)
  • Optionally adds all results to Portfolio Monitoring
  • Returns results asynchronously as searches complete
  • Stores the full batch record for later review

Batch Search is ideal for:

  • Migrating an existing book of business
  • Periodic refreshes of a vendor or customer list
  • Running KYB on large lead pipelines
  • Preparing large sets of customers for Portfolio Monitoring

2. Running a Batch Search in the Console

Navigate to:
Console → Batch Search → Upload CSV

You will be asked to:

  • Upload a CSV file (up to 100MB)
  • Provide a batch name
  • (Optional) Add all businesses to your Portfolio
  • (Optional) Monitor all businesses
  • (Optional) Add results to a specific Portfolio Group
  • (Optional) Enable Enhanced Search, Industry, Website Analysis, or PEP checks

Your selections apply to every row in the CSV.

Important: Batch searches are asynchronous.
Baselayer provisions additional backend resources to handle large jobs.
This means:

  • Most batches begin running within ~3 minutes
  • Larger batches may take up to 10 minutes to start

3. Running a Batch Search via API

Use the POST /searches/batches endpoint with a multipart form-data request:

curl --request POST \
  --url https://api.baselayer.com/searches/batches \
  --header 'X-API-Key: <API_KEY>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=@/path/to/your/batch.csv' \
  --form 'batch={
    "name": "December Onboarding Batch",
    "portfolio": {
      "add_to_portfolio": true,
      "monitor": true,
      "group_id": "optional-group-uuid"
    }
  }' \
  --form 'options=["Order.NaicsPrediction", "Order.WebsiteAnalysis"]'

Request parameters:

  • file - Your CSV file (required, max 100MB)
  • batch.name - Descriptive name for this batch (required)
  • batch.portfolio.add_to_portfolio - Add all businesses to portfolio (optional, default: false)
  • batch.portfolio.monitor - Enable monitoring for all businesses (optional, default: false)
  • batch.portfolio.group_id - Portfolio group to add businesses to (optional)
  • options - Array of order options to apply to all searches (optional)

Available options:

  • Order.Enhanced - Most comprehensive search with web scraping
  • Order.NaicsPrediction - Industry classification
  • Order.WebsiteAnalysis - Website discovery and analysis
  • Order.Pep - Politically exposed persons screening

Response:

{
  "id": "batch-uuid-here",
  "name": "December Onboarding Batch",
  "state": "PENDING",
  "created_at": "2025-12-30T10:00:00Z",
  "total_items": 1500
}

Store the batch id to query progress and retrieve results.

Retrieving Batch Status

Query batch progress:

GET /searches/batches/{batch_id}

Retrieve individual search results:

GET /searches/batches/{batch_id}/items

Each item represents one Business Search from the batch with the full search response.

4. CSV Format Requirements

Your CSV must follow the official Baselayer schema exactly.
The example CSV provided in the Console shows all allowed columns and formatting rules.

Required columns:

  • name - Business legal name
  • address - Full business address (or separate street, city, state, zip columns)

Optional columns:

  • tin - Business EIN/TIN (enables IRS verification)
  • website - Business website URL
  • officer_names - Comma-separated list of officers
  • phone_number - Business phone number
  • email - Business email
  • reference_id - Your internal ID for this business

Critical formatting rules:

  • Do not change column headers
  • Do not add or remove columns
  • Do not reorder columns
  • Follow exact address formatting from the template
  • Use UTF-8 encoding
  • Maximum file size: 100MB

If a row's input is malformed, that item will be marked as failed in the batch results. You can review failed items and resubmit them with corrected data.

5. Understanding Batch Execution Timing

Batch processing is a timed, asynchronous workflow.

Baselayer automatically provisions compute resources for the batch. As a result:

  • Most batches start processing within 3 minutes
  • Very large uploads may take up to 10 minutes before processing begins
  • Execution time varies by number of rows and selected add-ons

You may safely close the Console or disconnect from the API - the batch will continue running.

6. Reviewing Batch Results

Batch results appear in the Console under Batch Search → History, or through the API endpoints.

For each business in the batch, you will see:

  • Search status (completed, failed, pending)
  • Match level and verification outcome
  • KYB and Risk ratings
  • Any add-ons applied (Industry, Website Analysis, PEP)
  • Whether it was added to your Portfolio
  • Whether monitoring was enabled

If monitoring was enabled, each business will automatically enter your Portfolio and be included in the next monitoring cadence.


Batch results are available through three methods:

Console Review

Navigate to Batch Search → History in the Console to view:

  • Search status (completed, failed, pending)
  • Any add-ons applied (Industry, Website Analysis, PEP)
  • Basic results (number of searches and number of failed searches)

You'll also find the option to download a CSV file with the results of the batch search.

Export to CSV

Download all batch results as a single CSV file for spreadsheet analysis:

GET /searches/batch/{batch_id}/export

What you get:

  • JSONL format (one complete Business Search JSON object per line)
  • Served as CSV file (text/csv mime-type) for easy import into Excel, Google Sheets, or data analysis tools
  • Each row represents one business search with all fields
  • Complex objects (addresses, registrations, officers) are JSON-encoded in single columns

7. Best Practices

Before Running Your Batch

✅ Test with a small sample first - Upload 5-10 rows to verify formatting before submitting your full file

✅ Clean your data - Remove duplicates, standardize address formats, validate TINs before upload

✅ Use the exact template - Download fresh from Console for each batch to ensure you have the latest schema

During Batch Execution

✅ Don't modify the batch - Once submitted, you cannot edit or cancel. Let it complete.

✅ Use Groups for segmentation - Upload different customer segments to different Portfolio Groups for cleaner monitoring

✅ Consider costs - Each row in your batch is billed as an individual Business Search, plus any add-ons selected

After Batch Completion

✅ Review failed items - Identify patterns in failures (common: address or TIN formatting issues)

✅ Store business_id - Map batch results to your internal systems for future reference

✅ Use batch monitoring to initialize portfolio - Enable monitoring during batch upload rather than adding businesses individually later

Automation

✅ Use the API for recurring batches - Automate periodic portfolio refreshes or customer onboarding

✅ Integrate with your CRM - Export customer lists directly to Baselayer's batch format

8. Next Steps

Understand batch results:

Enable monitoring for batches:

Process batch results:

9. Summary

Batch Search enables large-scale Business Search execution through a single CSV upload. Use it to process thousands of businesses efficiently, add them to Portfolio Monitoring, and maintain consistent verification across your customer base.

Key capabilities:

  • Console or API submission
  • Automatic portfolio addition
  • Monitoring enablement at scale
  • Add-on enrichments (Enhanced, Industry, Website, PEP)
  • Asynchronous processing with status tracking

For questions about batch limits, pricing, or optimization, contact your Baselayer account manager.

Updated about 1 month ago