PrivSource Menu

REST API

Buyer Lists API Reference

Beta

Complete reference for the Buyer Lists API. API IDs are resource-prefixed with bl_, blv_, and blr_.

Overview

Who can access

Available to sellers with a paid subscription.

A buyer list is an AI-generated list of potential acquirers for a business. You describe the business, review the extracted search criteria, generate the list, then iterate: rate results, refine into a new version, and request contact info for the buyers you like. Generating, refining, and requesting contact info are paid actions.

Workflow

  1. 1

    POST /v1/buyer-lists

    Create a buyer list with a description of the business. The new list starts in status analyzing while search criteria are extracted.

  2. 2

    GET /v1/buyer-lists/:id/current

    Poll until status is needs_review.

  3. 3

    PATCH /v1/buyer-lists/:id/criteria

    Review the extracted criteria and adjust them. sector, subsector, size_band, and geography are required before generating.

  4. 4

    POST /v1/buyer-lists/:id/generate

    Build the list. Status moves to processing; poll until ready.

  5. 5

    GET /v1/buyer-lists/:id/results

    Fetch results, then rate them with POST /v1/buyer-lists/:id/results/:result_id/feedback. At least 5 rated results are required before refining.

  6. 6

    POST /v1/buyer-lists/:id/refine

    Optionally build a new version that carries over positive-rated results.

  7. 7

    POST /v1/buyer-lists/:id/contact-info

    Optionally enrich results with leadership contact info. Status moves to processing_contacts; poll until ready_with_contacts.

  8. 8

    POST /v1/buyer-lists/:id/cancel

    Stop an in-flight build at any point while it is processing.

Status Flow

analyzing needs_review processing ready processing_contacts ready_with_contacts

A version can also end in errored or canceled; both allow editing criteria and generating again.

GET

List Buyer Lists

/v1/buyer-lists

Returns a paginated list of the seller's Buyer Lists, newest first. Archived Buyer Lists are excluded unless archived=true.

Query Parameters

Parameter Type Description
q string Search text matched against Buyer List names and descriptions.
archived boolean Set to true to list archived Buyer Lists instead of active ones.
page integer Page number.
per_page integer Results per page. Maximum 100.

Code Sample

curl "https://api.privsource.com/v1/buyer-lists?per_page=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "buyer_lists": [
    {
      "id": "bl_aB3dE9",
      "name": "HVAC services buyer list",
      "custom_name": "HVAC services buyer list",
      "status": "ready",
      "tier": "standard",
      "archived": false,
      "current_version_number": 1,
      "created_at": "2026-03-20T12:00:00Z",
      "updated_at": "2026-03-20T13:00:00Z",
      "current_version": {
        "id": "blv_xK7mP2",
        "version": 1,
        "current": true,
        "status": "ready",
        "results_count": 38,
        "positive_results_count": 5,
        "negative_results_count": 2,
        "created_at": "2026-03-20T12:00:00Z",
        "updated_at": "2026-03-20T13:00:00Z"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1,
    "per_page": 10
  }
}

Response Codes

200 A paginated list of Buyer Lists
401 Unauthorized
403 Buyer Lists are only available for seller API tokens
POST

Create a Buyer List

/v1/buyer-lists

Creates a new draft Buyer List and version 1, then starts analyzing target-company criteria asynchronously. Provide a description of the acquisition target company/business being sold, file attachments, or both. Revenue, size, sector, geography, business model, end-market, and customer criteria should describe the target company, not potential buyers/acquirers. Creating a draft is free; plan allowance or credits are only used at the generate step. Poll the current version until its status is needs_review, then review the criteria and call generate.

Request Body (application/json)

Field Type Description
name string Optional display name for the Buyer List.
description string Plain-language description of the target company/business being acquired. Optional if files are attached.

Example Request

{
  "name": "HVAC services buyer list",
  "description": "We are a $12M revenue commercial HVAC services company in Texas exploring a sale"
}

Request Body (multipart/form-data)

Field Type Description
name string Optional display name for the Buyer List.
description string Plain-language description of the target company/business being acquired. Optional if files are attached.
files string[] Optional file attachments, up to 3. Supported formats: PDF, DOCX, PNG, JPG, WebP.

Code Samples

curl (JSON)

curl "https://api.privsource.com/v1/buyer-lists" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"HVAC services buyer list","description":"We are a $12M revenue commercial HVAC services company in Texas exploring a sale"}'

curl (multipart with files)

curl "https://api.privsource.com/v1/buyer-lists" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "name=HVAC services buyer list" \
  -F "description=We are a $12M revenue commercial HVAC services company in Texas exploring a sale" \
  -F "files[][email protected]"

Example Response

{
  "buyer_list": {
    "id": "bl_aB3dE9",
    "name": "HVAC services buyer list",
    "custom_name": "HVAC services buyer list",
    "status": "analyzing",
    "tier": null,
    "archived": false,
    "current_version_number": 1,
    "created_at": "2026-03-20T12:00:00Z",
    "updated_at": "2026-03-20T12:00:00Z",
    "versions": [
      {
        "id": "blv_xK7mP2",
        "version": 1,
        "current": true,
        "status": "analyzing",
        "results_count": 0,
        "created_at": "2026-03-20T12:00:00Z",
        "updated_at": "2026-03-20T12:00:00Z",
        "positive_results_count": 0,
        "negative_results_count": 0
      }
    ],
    "current_version": {
      "id": "blv_xK7mP2",
      "version": 1,
      "current": true,
      "status": "analyzing",
      "results_count": 0,
      "created_at": "2026-03-20T12:00:00Z",
      "updated_at": "2026-03-20T12:00:00Z",
      "positive_results_count": 0,
      "negative_results_count": 0
    }
  },
  "version": {
    "id": "blv_xK7mP2",
    "version": 1,
    "current": true,
    "status": "analyzing",
    "results_count": 0,
    "created_at": "2026-03-20T12:00:00Z",
    "updated_at": "2026-03-20T12:00:00Z",
    "name": "HVAC services buyer list",
    "description": "We are a $12M revenue commercial HVAC services company in Texas exploring a sale",
    "refinement_instructions": "",
    "criteria": {
      "sector": "",
      "subsector": "",
      "size_band": "",
      "geography": "",
      "business_model": "",
      "end_markets": "",
      "customer_type": ""
    },
    "summary": "",
    "error": null,
    "contacts": {
      "status": "not_requested",
      "mode": "none",
      "requested_at": null,
      "completed_at": null
    }
  }
}

Response Codes

201 Buyer List created
401 Unauthorized
403 Buyer Lists are only available for seller API tokens
422 Validation error
GET

Get a Buyer List

/v1/buyer-lists/:id

Returns Buyer List metadata and summaries for all versions.

Path Parameters

Parameter Type Description
id required string Buyer List ID with a bl_ prefix.

Code Sample

curl "https://api.privsource.com/v1/buyer-lists/bl_aB3dE9" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "buyer_list": {
    "id": "bl_aB3dE9",
    "name": "HVAC services buyer list",
    "custom_name": "HVAC services buyer list",
    "status": "ready",
    "tier": "standard",
    "archived": false,
    "current_version_number": 2,
    "created_at": "2026-03-20T12:00:00Z",
    "updated_at": "2026-03-22T13:00:00Z",
    "versions": [
      {
        "id": "blv_xK7mP2",
        "version": 1,
        "current": false,
        "status": "ready",
        "results_count": 40,
        "created_at": "2026-03-20T12:00:00Z",
        "updated_at": "2026-03-20T13:00:00Z",
        "positive_results_count": 0,
        "negative_results_count": 0
      },
      {
        "id": "blv_yL8nQ3",
        "version": 2,
        "current": true,
        "status": "ready",
        "results_count": 40,
        "created_at": "2026-03-22T12:00:00Z",
        "updated_at": "2026-03-22T13:00:00Z",
        "positive_results_count": 0,
        "negative_results_count": 0
      }
    ],
    "current_version": {
      "id": "blv_yL8nQ3",
      "version": 2,
      "current": true,
      "status": "ready",
      "results_count": 40,
      "created_at": "2026-03-22T12:00:00Z",
      "updated_at": "2026-03-22T13:00:00Z",
      "positive_results_count": 0,
      "negative_results_count": 0
    }
  }
}

Response Codes

200 Buyer List details
401 Unauthorized
403 Buyer Lists are only available for seller API tokens
404 Buyer List not found
PATCH

Update a Buyer List

/v1/buyer-lists/:id

Updates the display name or archived state for an existing Buyer List.

Path Parameters

Parameter Type Description
id required string Buyer List ID with a bl_ prefix.

Request Body

Field Type Description
name string New display name.
archived boolean Set to true to archive the Buyer List or false to unarchive it.

Example Request

{
  "name": "New Buyer List Name",
  "archived": false
}

Code Sample

curl -X PATCH "https://api.privsource.com/v1/buyer-lists/bl_aB3dE9" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"New Buyer List Name"}'

Response Codes

200 Updated Buyer List
401 Unauthorized
403 Buyer Lists are only available for seller API tokens
404 Buyer List not found
422 Validation error
GET

Get the current Buyer List version

/v1/buyer-lists/:id/current

Returns the most recent Buyer List version, whether it is still analyzing, awaiting review, processing, or complete.

Path Parameters

Parameter Type Description
id required string Buyer List ID with a bl_ prefix.

Code Sample

curl "https://api.privsource.com/v1/buyer-lists/bl_aB3dE9/current" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response Codes

200 Current Buyer List version
401 Unauthorized
403 Buyer Lists are only available for seller API tokens
404 Buyer List not found
GET

Get a specific Buyer List version

/v1/buyer-lists/:id/:version_number

Returns one specific Buyer List version with its criteria, summary, and contact enrichment status.

Path Parameters

Parameter Type Description
id required string Buyer List ID with a bl_ prefix.
version_number required integer 1-based version number.

Code Sample

curl "https://api.privsource.com/v1/buyer-lists/bl_aB3dE9/1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "version": {
    "id": "blv_xK7mP2",
    "version": 1,
    "current": true,
    "status": "ready",
    "results_count": 40,
    "created_at": "2026-03-20T12:00:00Z",
    "updated_at": "2026-03-20T13:00:00Z",
    "name": "HVAC services buyer list",
    "description": "We are a $12M revenue commercial HVAC services company in Texas exploring a sale",
    "refinement_instructions": "",
    "criteria": {
      "sector": "Industrial Services",
      "subsector": "HVAC Services",
      "size_band": "$10M-$25M revenue",
      "geography": "Texas, United States",
      "business_model": "Recurring commercial service contracts",
      "end_markets": "Commercial real estate",
      "customer_type": "B2B"
    },
    "summary": "40 potential acquirers across strategics and PE-backed platforms active in commercial HVAC services.",
    "error": null,
    "contacts": {
      "status": "not_requested",
      "mode": "none",
      "requested_at": null,
      "completed_at": null
    }
  }
}

Response Codes

200 Buyer List version
401 Unauthorized
403 Buyer Lists are only available for seller API tokens
404 Buyer List or version not found
PATCH

Update Buyer List criteria

/v1/buyer-lists/:id/criteria

Updates the target-company criteria on the latest version while it is awaiting review (status needs_review; also allowed after a version errored or was canceled). Criteria describe the acquisition target company/business being sold, not potential buyers/acquirers. Returns 422 while criteria are still being analyzed or once a build is running or completed.

Path Parameters

Parameter Type Description
id required string Buyer List ID with a bl_ prefix.

Request Body

Field Type Description
description string Updated description of the target company/business being acquired.
sector string Primary sector of the target company being acquired. Required before generating.
subsector string Subsector of the target company being acquired. Required before generating.
size_band string Revenue/size band of the target company being acquired, not the acquirers' revenue or size. Required before generating.
geography string Geography of the target company being acquired, not acquirer headquarters or search radius. Required before generating.
business_model string Business model of the target company being acquired.
end_markets string End markets served by the target company being acquired.
customer_type string Customer type served by the target company being acquired.

Example Request

{
  "sector": "Industrial Services",
  "subsector": "HVAC Services",
  "size_band": "$10M-$25M revenue",
  "geography": "Texas, United States"
}

Code Sample

curl -X PATCH "https://api.privsource.com/v1/buyer-lists/bl_aB3dE9/criteria" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sector":"Industrial Services","subsector":"HVAC Services","size_band":"$10M-$25M revenue","geography":"Texas, United States"}'

Response Codes

200 Updated Buyer List version
401 Unauthorized
403 Buyer Lists are only available for seller API tokens
404 Buyer List not found
422 Criteria are still being analyzed or the version cannot be edited
POST

Generate a Buyer List

/v1/buyer-lists/:id/generate

Confirms the search criteria and starts building the latest version asynchronously. Requires sector, subsector, size_band, and geography to be present on the version. Requires a plan that produces a full list: an included monthly allowance or a paid one-off purchase on number-of-lists plans, or sufficient credits on legacy credit plans. Poll the current version until its status is ready.

Path Parameters

Parameter Type Description
id required string Buyer List ID with a bl_ prefix.

Code Sample

curl -X POST "https://api.privsource.com/v1/buyer-lists/bl_aB3dE9/generate" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response Codes

202 Build started
401 Unauthorized
402 Payment required - plan allowance exhausted or not enough credits
403 Buyer Lists are only available for seller API tokens
404 Buyer List not found
422 Criteria are still being analyzed, required criteria are missing, or a build is already running or completed
POST

Cancel a Buyer List build

/v1/buyer-lists/:id/cancel

Cancels an in-progress build of the latest version.

Path Parameters

Parameter Type Description
id required string Buyer List ID with a bl_ prefix.

Code Sample

curl -X POST "https://api.privsource.com/v1/buyer-lists/bl_aB3dE9/cancel" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response Codes

200 Build canceled
401 Unauthorized
403 Buyer Lists are only available for seller API tokens
404 Buyer List not found
422 No build is in progress
POST

Refine a Buyer List

/v1/buyer-lists/:id/refine

Creates a new version refined from feedback on a completed version and starts building it asynchronously. The parent version must be completed and at least 5 of its results must be rated positive or negative. Positive-rated results carry over to the new version.

Path Parameters

Parameter Type Description
id required string Buyer List ID with a bl_ prefix.

Request Body

Field Type Description
refinement_instructions string Plain-language instructions describing how to refine the list.
version_number integer Optional 1-based version number to refine from. Defaults to the latest version.

Example Request

{
  "refinement_instructions": "Focus on PE-backed platforms with existing Texas operations"
}

Code Sample

curl "https://api.privsource.com/v1/buyer-lists/bl_aB3dE9/refine" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"refinement_instructions":"Focus on PE-backed platforms with existing Texas operations"}'

Example Response

{
  "version": {
    "id": "blv_yL8nQ3",
    "version": 2,
    "current": true,
    "status": "processing",
    "results_count": 12,
    "created_at": "2026-03-22T12:00:00Z",
    "updated_at": "2026-03-22T12:00:00Z",
    "name": "HVAC services buyer list",
    "description": "We are a $12M revenue commercial HVAC services company in Texas exploring a sale",
    "refinement_instructions": "Focus on PE-backed platforms with existing Texas operations",
    "criteria": {
      "sector": "Industrial Services",
      "subsector": "HVAC Services",
      "size_band": "$10M-$25M revenue",
      "geography": "Texas, United States",
      "business_model": "Recurring commercial service contracts",
      "end_markets": "Commercial real estate",
      "customer_type": "B2B"
    },
    "summary": "",
    "error": null,
    "contacts": {
      "status": "not_requested",
      "mode": "none",
      "requested_at": null,
      "completed_at": null
    }
  }
}

Response Codes

201 New Buyer List version created and building
401 Unauthorized
402 Payment required - not enough credits
403 Buyer Lists are only available for seller API tokens
404 Buyer List or version not found
422 Parent version is not completed or has fewer than 5 rated results
GET

List Buyer List results

/v1/buyer-lists/:id/results

Returns paginated result rows for one Buyer List version. Defaults to the latest version when version_number is omitted. This endpoint can be called while status is processing to read rows as they are completed; keep polling until status is ready for the final result set.

Query Parameters

Parameter Type Description
version_number integer Optional 1-based version number. Defaults to the latest version.
page integer Page number.
per_page integer Results per page. Maximum 100.

Path Parameters

Parameter Type Description
id required string Buyer List ID with a bl_ prefix.

Code Sample

curl "https://api.privsource.com/v1/buyer-lists/bl_aB3dE9/results?per_page=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "version": {
    "id": "blv_xK7mP2",
    "version": 1,
    "current": true,
    "status": "ready",
    "results_count": 40,
    "created_at": "2026-03-20T12:00:00Z",
    "updated_at": "2026-03-20T13:00:00Z",
    "positive_results_count": 0,
    "negative_results_count": 0
  },
  "results": [
    {
      "id": "blr_qW8nT4",
      "company_name": "Lone Star Comfort Group",
      "company_description": "Multi-site provider of commercial HVAC installation and service across Texas.",
      "buyer_type": "PE Platform",
      "buyer_type_category": "Strategic Operator",
      "tier": "Proven Acquirer",
      "ownership": "PE-backed",
      "ownership_details": "Backed by Example Capital Partners",
      "website": "https://www.lonestarcomfortgroup.com",
      "domain": "lonestarcomfortgroup.com",
      "hq": {
        "city": "Dallas",
        "state": "TX",
        "country": "United States"
      },
      "size_fit": "Acquires companies in the $5M-$30M revenue range",
      "revenue_band": "$100M-$250M",
      "deals_last_24_months": 4,
      "total_deals": 11,
      "last_deal_date": "2026-01-15",
      "relevant_details": "Active roll-up of commercial HVAC service companies in Texas metros.",
      "description_bullets": [
        "Acquired three Texas HVAC service companies since 2024",
        "Focus on recurring commercial service contracts"
      ],
      "feedback": {
        "signal": null,
        "comment": ""
      },
      "contacts": {
        "status": "not_requested",
        "entries": []
      },
      "created_at": "2026-03-20T13:00:00Z",
      "updated_at": "2026-03-20T13:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 4,
    "total_count": 40,
    "per_page": 10
  }
}

Response Codes

200 A paginated list of Buyer List results
401 Unauthorized
403 Buyer Lists are only available for seller API tokens
404 Buyer List or version not found
POST

Update feedback on a Buyer List result

/v1/buyer-lists/:id/results/:result_id/feedback

Records a positive or negative signal and an optional comment on one result row. Use signal "none" to clear a previous rating. Rate at least 5 results before refining.

Path Parameters

Parameter Type Description
id required string Buyer List ID with a bl_ prefix.
result_id required string Buyer List result ID with a blr_ prefix.

Request Body

Field Type Description
signal enum Feedback signal. Use "none" to clear a previous rating.
comment string Optional feedback comment.

Example Request

{
  "signal": "positive",
  "comment": "Great fit, already active in our region"
}

Code Sample

curl "https://api.privsource.com/v1/buyer-lists/bl_aB3dE9/results/blr_qW8nT4/feedback" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"signal":"positive","comment":"Great fit, already active in our region"}'

Example Response

{
  "result": {
    "id": "blr_qW8nT4",
    "company_name": "Lone Star Comfort Group",
    "company_description": "Multi-site provider of commercial HVAC installation and service across Texas.",
    "buyer_type": "PE Platform",
    "buyer_type_category": "Strategic Operator",
    "tier": "Proven Acquirer",
    "ownership": "PE-backed",
    "ownership_details": "Backed by Example Capital Partners",
    "website": "https://www.lonestarcomfortgroup.com",
    "domain": "lonestarcomfortgroup.com",
    "hq": {
      "city": "Dallas",
      "state": "TX",
      "country": "United States"
    },
    "size_fit": "Acquires companies in the $5M-$30M revenue range",
    "revenue_band": "$100M-$250M",
    "deals_last_24_months": 4,
    "total_deals": 11,
    "last_deal_date": "2026-01-15",
    "relevant_details": "Active roll-up of commercial HVAC service companies in Texas metros.",
    "description_bullets": [
      "Acquired three Texas HVAC service companies since 2024",
      "Focus on recurring commercial service contracts"
    ],
    "feedback": {
      "signal": "positive",
      "comment": "Great fit, already active in our region"
    },
    "contacts": {
      "status": "not_requested",
      "entries": []
    },
    "created_at": "2026-03-20T13:00:00Z",
    "updated_at": "2026-03-21T09:00:00Z"
  }
}

Response Codes

200 Updated Buyer List result
401 Unauthorized
403 Buyer Lists are only available for seller API tokens
404 Buyer List or result not found
422 Invalid signal
POST

Request Buyer List contact info

/v1/buyer-lists/:id/contact-info

Requests M&A contact enrichment for the latest completed version. Runs asynchronously and consumes credits; returns 402 when the credit balance is insufficient. Use scope to limit enrichment to positive-rated results. Poll the current version until its status is ready_with_contacts.

Path Parameters

Parameter Type Description
id required string Buyer List ID with a bl_ prefix.

Request Body

Field Type Description
include_phone boolean Set to true to include phone lookups where available.
scope enum Which results to enrich: all results, or only results rated positive.

Example Request

{
  "include_phone": false,
  "scope": "all"
}

Code Sample

curl "https://api.privsource.com/v1/buyer-lists/bl_aB3dE9/contact-info" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"include_phone":false,"scope":"all"}'

Response Codes

202 Contact enrichment started
401 Unauthorized
402 Payment required - not enough credits
403 Buyer Lists are only available for seller API tokens
404 Buyer List not found
422 Build has not finished or a contact request is already in progress or complete

Schemas

BuyerList

Buyer list metadata and version summaries.

Field Type Description
id string Buyer List ID with a bl_ prefix.
name string Display title for the buyer list.
custom_name string User-provided title for the buyer list.
status enum Overall status derived from the latest version. "empty" when no versions exist.
tier enum Result tier decided at the generate step. Null until the first build starts. Lists generated via the API are standard tier.
archived boolean Whether the buyer list is archived.
current_version_number integer? Current version number when a version exists.
current_version object Summary of the current (latest) version, including result and feedback counts. Null when no versions exist.
created_at string Creation timestamp.
updated_at string Last update timestamp.
versions BuyerListVersionSummary[] Version summaries ordered by creation time.

BuyerListContactEntry

One enriched M&A contact.

Field Type Description
full_name string Full name.
first_name string First name.
last_name string Last name.
title string Job title.
email string Email address when available.
phone string Phone number when available and requested.
linkedin_url string LinkedIn profile URL when available.

BuyerListContacts

Contact enrichment status for a buyer list version.

Field Type Description
status enum Contact enrichment status.
mode enum Requested contact mode.
requested_at string? When contact enrichment was requested.
completed_at string? When contact enrichment finished.

BuyerListCreateResponse

Response returned when creating a buyer list.

Field Type Description
buyer_list BuyerList
version BuyerListVersion

BuyerListCriteria

Search criteria extracted from the description and files, editable while the version is in needs_review.

Field Type Description
sector string Primary sector. Required before generating.
subsector string Subsector. Required before generating.
size_band string Company size band. Required before generating.
geography string Geography. Required before generating.
business_model string Business model.
end_markets string End markets served.
customer_type string Customer type.

BuyerListListResponse

Paginated list response for the buyer lists index endpoint.

Field Type Description
buyer_lists BuyerListSummary[] Buyer List summaries for the current page.
meta PaginationMeta

BuyerListResponse

Response returned by buyer list metadata endpoints.

Field Type Description
buyer_list BuyerList

BuyerListResult

One potential acquirer row in a buyer list version.

Field Type Description
id string Buyer List result ID with a blr_ prefix.
company_name string Company name.
company_description string Company description.
buyer_type string Buyer type, for example Strategic, PE Platform, or PE Firm.
buyer_type_category string Buyer type category, for example Strategic Operator or Financial Sponsor.
tier string Tier label, for example Proven Acquirer or Strategic Candidate.
ownership string Ownership type.
ownership_details string Ownership details, for example the PE backer or parent company.
website string? Company website URL when available.
domain string Company website domain.
hq object Headquarters location.
size_fit string How this acquirer fits the requested size band.
revenue_band string Estimated revenue band.
deals_last_24_months integer? Acquisitions in the last 24 months when known.
total_deals integer? Total known acquisitions.
last_deal_date string? Date of the most recent known acquisition.
relevant_details string Why this company is a relevant potential acquirer.
description_bullets string[] Short bullet points describing the company.
feedback BuyerListResultFeedback
contacts BuyerListResultContacts
created_at string Creation timestamp.
updated_at string Last update timestamp.

BuyerListResultContacts

M&A contact enrichment for one buyer list result.

Field Type Description
status enum Contact enrichment status for this result.
entries BuyerListContactEntry[] Enriched contacts for this result.

BuyerListResultFeedback

Feedback recorded on a buyer list result.

Field Type Description
signal enum Feedback signal. Null when no feedback has been recorded.
comment string Feedback comment.

BuyerListResultFeedbackResponse

Response returned when updating feedback on a buyer list result.

Field Type Description
result BuyerListResult

BuyerListResultsResponse

Paginated result rows for one buyer list version.

Field Type Description
version BuyerListVersionSummary
results BuyerListResult[] Result rows for the current page.
meta PaginationMeta

BuyerListSummary

Buyer list metadata without version summaries.

Field Type Description
id string Buyer List ID with a bl_ prefix.
name string Display title for the buyer list.
custom_name string User-provided title for the buyer list.
status enum Overall status derived from the latest version. "empty" when no versions exist.
tier enum Result tier decided at the generate step. Null until the first build starts. Lists generated via the API are standard tier.
archived boolean Whether the buyer list is archived.
current_version_number integer? Current version number when a version exists.
current_version object Summary of the current (latest) version, including result and feedback counts. Null when no versions exist.
created_at string Creation timestamp.
updated_at string Last update timestamp.

BuyerListVersion

Full buyer list version shape.

Field Type Description
id string Buyer List version ID with a blv_ prefix.
version integer 1-based version number.
current boolean Whether this is the current version.
status enum Version status. Criteria are extracted while analyzing, reviewed and edited during needs_review, and the list is built while processing.
results_count integer Number of result rows currently visible.
positive_results_count integer Results rated with a positive feedback signal.
negative_results_count integer Results rated with a negative feedback signal.
created_at string Creation timestamp.
updated_at string Last update timestamp.
name string Display title for this version.
description string User-provided description used to create this version.
refinement_instructions string Refinement instructions when this version was created by a refine.
criteria BuyerListCriteria
summary string Generated summary of the completed buyer list.
error string? Public error message when the version errored.
contacts BuyerListContacts

BuyerListVersionResponse

Response returned by buyer list version endpoints.

Field Type Description
version BuyerListVersion

BuyerListVersionSummary

Summary fields shared across buyer list version responses.

Field Type Description
id string Buyer List version ID with a blv_ prefix.
version integer 1-based version number.
current boolean Whether this is the current version.
status enum Version status. Criteria are extracted while analyzing, reviewed and edited during needs_review, and the list is built while processing.
results_count integer Number of result rows currently visible.
positive_results_count integer Results rated with a positive feedback signal.
negative_results_count integer Results rated with a negative feedback signal.
created_at string Creation timestamp.
updated_at string Last update timestamp.

ErrorResponse

Error response returned by authenticated API endpoints.

Field Type Description
errors required string[] One or more human-readable error messages.

PaginationMeta

Pagination metadata returned by list endpoints.

Field Type Description
current_page integer Current page number.
total_pages integer Total number of pages.
total_count integer Total matching record count.
per_page integer Results returned per page.
filters object Applied filters. Only present when filters are active.