{"openapi":"3.1.0","info":{"title":"PrivSource Agents API","version":"1.0.0","description":"An API built for AI agents. Search live lower middle market M\u0026A deal listings and generate seller Buyer Lists from PrivSource. Deals endpoints are available to all buyers with a paid subscription. Buyer Lists endpoints (beta) are available to sellers with a paid subscription. Call GET /whoami to see which APIs your token can access."},"tags":[{"name":"Whoami","description":"Check the current API token identity and which APIs the token can access."},{"name":"Deals","description":"Search and retrieve live deals from the buyer perspective. Access: all buyers with a paid subscription."},{"name":"Buyer Lists","description":"Beta: Create and manage AI-generated lists of potential acquirers (buyer lists) for sellers. Access: sellers with a paid subscription. Generating, refining, and requesting contact info are paid actions. Buyer List criteria describe the acquisition target company/business being sold, not the potential buyers/acquirers.\n\nTypical workflow:\n1. POST /buyer-lists with a description of the target company being acquired. The new list starts in status `analyzing` while target-company criteria are extracted from your description.\n2. Poll GET /buyer-lists/{id}/current until status is `needs_review`.\n3. Review the extracted target-company criteria and adjust them with PATCH /buyer-lists/{id}/criteria. `sector`, `subsector`, `size_band`, and `geography` are required before generating.\n4. POST /buyer-lists/{id}/generate. Status moves to `processing` while the list builds.\n5. While status is `processing`, poll GET /buyer-lists/{id}/current for counts and call GET /buyer-lists/{id}/results to read completed rows incrementally. Continue polling until status is `ready` for the final result set.\n6. Rate results with POST /buyer-lists/{id}/results/{result_id}/feedback (signal: positive, negative, or none). At least 5 rated results are required before refining.\n7. Optionally POST /buyer-lists/{id}/refine to build a new version that carries over positive-rated results.\n8. Optionally POST /buyer-lists/{id}/contact-info after the list is ready to enrich results with leadership contact info. Status moves to `processing_contacts`; poll until `ready_with_contacts`.\n9. POST /buyer-lists/{id}/cancel stops an in-flight build (status `processing` or `processing_contacts`).\n\nStatus flow: analyzing -\u003e needs_review -\u003e processing -\u003e ready -\u003e processing_contacts -\u003e ready_with_contacts. A version can also end up `errored` or `canceled`."}],"servers":[{"url":"https://api.privsource.com/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"paths":{"/whoami":{"get":{"tags":["Whoami"],"x-privsource-docs-page":"whoami","x-privsource-order":10,"summary":"Get current account context","description":"Returns the current API token's account (buyer_account or seller_account) and the list of APIs the token can access.","operationId":"getWhoAmI","x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://api.privsource.com/v1/whoami\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\""}],"responses":{"200":{"description":"Current account context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhoAmIResponse"},"example":{"seller_account":{"company_name":"Globex"},"apis":["buyer-lists"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["Unauthorized"]}}}},"402":{"description":"Payment required - no active subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["No active subscription"]}}}}}}},"/buyer/deals":{"get":{"tags":["Deals"],"x-privsource-docs-page":"deals","x-privsource-order":10,"summary":"List deals","description":"Returns a paginated list of live deals from the buyer perspective. Supports natural language filtering by industry and location, plus financial filters and sorting.","operationId":"listDeals","parameters":[{"name":"industry","in":"query","schema":{"type":"string"},"description":"Natural language industry filter. Example: \"healthcare\" or \"SaaS\"."},{"name":"location","in":"query","schema":{"type":"string"},"description":"Natural language location filter. Example: \"Northeast\" or \"Texas\"."},{"name":"revenue_min","in":"query","schema":{"type":"integer"},"description":"Minimum annual revenue in dollars."},{"name":"revenue_max","in":"query","schema":{"type":"integer"},"description":"Maximum annual revenue in dollars."},{"name":"ebitda_min","in":"query","schema":{"type":"integer"},"description":"Minimum EBITDA in dollars."},{"name":"ebitda_max","in":"query","schema":{"type":"integer"},"description":"Maximum EBITDA in dollars."},{"name":"margin_percent_min","in":"query","schema":{"type":"integer"},"description":"Minimum margin percentage from 0 to 100."},{"name":"margin_percent_max","in":"query","schema":{"type":"integer"},"description":"Maximum margin percentage from 0 to 100."},{"name":"deal_type","in":"query","schema":{"type":"string","enum":["buyout","capital_raise"]},"description":"Deal type filter. Defaults to both."},{"name":"sort","in":"query","schema":{"type":"string","enum":["date_added_desc","date_added_asc","revenue_desc","revenue_asc","ebitda_desc","ebitda_asc","margin_percent_desc","margin_percent_asc"]},"description":"Sort order. Default: date_added_desc."},{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number."},{"name":"per_page","in":"query","schema":{"type":"integer","default":25,"maximum":100},"description":"Results per page. Maximum 100."}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://api.privsource.com/v1/buyer/deals?industry=healthcare\u0026revenue_min=1000000\u0026sort=revenue_desc\u0026per_page=10\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\""}],"responses":{"200":{"description":"A paginated list of deals","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DealListResponse"},"example":{"deals":[{"id":"dl_gkqMKZ9x","name":"Healthcare Services Company","privsource_link":"https://privsource.com/buyer/deals/dl_gkqMKZ9x","teaser_link":"https://privsource.com/buyer/deals/dl_gkqMKZ9x/view","date_added":"2025-01-15","revenue":5000000,"ebitda":1200000,"margin_percent":24,"deal_type":"buyout","outreach_available":true,"primary_industry":"Healthcare","sub_industry":"Outpatient Services","secondary_industry":"Business Services","industries":["Healthcare","Business Services"],"location":"Northeast"}],"meta":{"current_page":1,"total_pages":5,"total_count":47,"per_page":10,"filters":{"industries":["Healthcare"],"revenue_min":1000000}}}}}},"400":{"description":"Bad request - invalid or unknown query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["Invalid parameter: sort. Must be one of: date_added_desc, date_added_asc, revenue_desc, revenue_asc, ebitda_desc, ebitda_asc, margin_percent_desc, margin_percent_asc"]}}}},"401":{"description":"Unauthorized - invalid or missing API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["Unauthorized"]}}}},"402":{"description":"Payment required - no active subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["No active subscription"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["Rate limit exceeded"]}}}}}}},"/buyer/deals/{id}":{"get":{"tags":["Deals"],"x-privsource-docs-page":"deals","x-privsource-order":20,"summary":"Get a deal","description":"Returns full details for a single live deal from the buyer perspective.","operationId":"getDeal","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Deal ID with a dl_ prefix."}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://api.privsource.com/v1/buyer/deals/dl_gkqMKZ9x\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\""}],"responses":{"200":{"description":"Deal details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DealDetailResponse"},"example":{"deal":{"id":"dl_gkqMKZ9x","name":"Healthcare Services Company","privsource_link":"https://privsource.com/buyer/deals/dl_gkqMKZ9x","teaser_link":"https://privsource.com/buyer/deals/dl_gkqMKZ9x/view","date_added":"2025-01-15","revenue":5000000,"ebitda":1200000,"margin_percent":24,"deal_type":"buyout","outreach_available":true,"primary_industry":"Healthcare","sub_industry":"Outpatient Services","secondary_industry":"Business Services","industries":["Healthcare","Business Services"],"location":"Northeast","description":"Full-service healthcare company specializing in outpatient care.","reason_for_sale":"Owner retirement","growth_opportunities":"Expand into adjacent markets and acquire smaller clinics.","deal_link":"https://example.com/deal-profile","nda_link":"https://example.com/nda","contacts":[{"name":"John Smith","email":"john@example.com","phone":"555-123-4567","title":"Managing Director"}]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required - no active subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Deal not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["Not found"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/buyer-lists":{"get":{"tags":["Buyer Lists"],"x-privsource-docs-page":"buyer-lists","x-privsource-order":10,"summary":"List Buyer Lists","description":"Returns a paginated list of the seller's Buyer Lists, newest first. Archived Buyer Lists are excluded unless archived=true.","operationId":"listBuyerLists","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search text matched against Buyer List names and descriptions."},{"name":"archived","in":"query","schema":{"type":"boolean","default":false},"description":"Set to true to list archived Buyer Lists instead of active ones."},{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number."},{"name":"per_page","in":"query","schema":{"type":"integer","default":25,"maximum":100},"description":"Results per page. Maximum 100."}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://api.privsource.com/v1/buyer-lists?per_page=10\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\""}],"responses":{"200":{"description":"A paginated list of Buyer Lists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerListListResponse"},"example":{"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}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Buyer Lists are only available for seller API tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Buyer Lists"],"x-privsource-docs-page":"buyer-lists","x-privsource-order":20,"summary":"Create a Buyer List","description":"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.","operationId":"createBuyerList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Optional display name for the Buyer List."},"description":{"type":"string","description":"Plain-language description of the target company/business being acquired. Optional if files are attached."}}},"example":{"name":"HVAC services buyer list","description":"We are a $12M revenue commercial HVAC services company in Texas exploring a sale"}},"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Optional display name for the Buyer List."},"description":{"type":"string","description":"Plain-language description of the target company/business being acquired. Optional if files are attached."},"files":{"type":"array","items":{"type":"string","format":"binary"},"description":"Optional file attachments, up to 3. Supported formats: PDF, DOCX, PNG, JPG, WebP."}}}}}},"x-codeSamples":[{"lang":"bash","label":"curl (JSON)","source":"curl \"https://api.privsource.com/v1/buyer-lists\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"HVAC services buyer list\",\"description\":\"We are a $12M revenue commercial HVAC services company in Texas exploring a sale\"}'"},{"lang":"bash","label":"curl (multipart with files)","source":"curl \"https://api.privsource.com/v1/buyer-lists\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n  -F \"name=HVAC services buyer list\" \\\n  -F \"description=We are a $12M revenue commercial HVAC services company in Texas exploring a sale\" \\\n  -F \"files[]=@teaser.pdf\""}],"responses":{"201":{"description":"Buyer List created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerListCreateResponse"},"example":{"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}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Buyer Lists are only available for seller API tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["Description or at least one file is required"]}}}}}}},"/buyer-lists/{id}":{"get":{"tags":["Buyer Lists"],"x-privsource-docs-page":"buyer-lists","x-privsource-order":30,"summary":"Get a Buyer List","description":"Returns Buyer List metadata and summaries for all versions.","operationId":"getBuyerList","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Buyer List ID with a bl_ prefix."}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://api.privsource.com/v1/buyer-lists/bl_aB3dE9\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\""}],"responses":{"200":{"description":"Buyer List details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerListResponse"},"example":{"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}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Buyer Lists are only available for seller API tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Buyer List not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Buyer Lists"],"x-privsource-docs-page":"buyer-lists","x-privsource-order":40,"summary":"Update a Buyer List","description":"Updates the display name or archived state for an existing Buyer List.","operationId":"updateBuyerList","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Buyer List ID with a bl_ prefix."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"New display name."},"archived":{"type":"boolean","description":"Set to true to archive the Buyer List or false to unarchive it."}}},"example":{"name":"New Buyer List Name","archived":false}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://api.privsource.com/v1/buyer-lists/bl_aB3dE9\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"New Buyer List Name\"}'"}],"responses":{"200":{"description":"Updated Buyer List","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Buyer Lists are only available for seller API tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Buyer List not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/buyer-lists/{id}/current":{"get":{"tags":["Buyer Lists"],"x-privsource-docs-page":"buyer-lists","x-privsource-order":50,"summary":"Get the current Buyer List version","description":"Returns the most recent Buyer List version, whether it is still analyzing, awaiting review, processing, or complete.","operationId":"getCurrentBuyerListVersion","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Buyer List ID with a bl_ prefix."}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://api.privsource.com/v1/buyer-lists/bl_aB3dE9/current\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\""}],"responses":{"200":{"description":"Current Buyer List version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerListVersionResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Buyer Lists are only available for seller API tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Buyer List not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/buyer-lists/{id}/{version_number}":{"get":{"tags":["Buyer Lists"],"x-privsource-docs-page":"buyer-lists","x-privsource-order":60,"summary":"Get a specific Buyer List version","description":"Returns one specific Buyer List version with its criteria, summary, and contact enrichment status.","operationId":"getBuyerListVersion","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Buyer List ID with a bl_ prefix."},{"name":"version_number","in":"path","required":true,"schema":{"type":"integer"},"description":"1-based version number."}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://api.privsource.com/v1/buyer-lists/bl_aB3dE9/1\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\""}],"responses":{"200":{"description":"Buyer List version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerListVersionResponse"},"example":{"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}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Buyer Lists are only available for seller API tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Buyer List or version not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/buyer-lists/{id}/criteria":{"patch":{"tags":["Buyer Lists"],"x-privsource-docs-page":"buyer-lists","x-privsource-order":70,"summary":"Update Buyer List criteria","description":"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.","operationId":"updateBuyerListCriteria","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Buyer List ID with a bl_ prefix."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","description":"Updated description of the target company/business being acquired."},"sector":{"type":"string","description":"Primary sector of the target company being acquired. Required before generating."},"subsector":{"type":"string","description":"Subsector of the target company being acquired. Required before generating."},"size_band":{"type":"string","description":"Revenue/size band of the target company being acquired, not the acquirers' revenue or size. Required before generating."},"geography":{"type":"string","description":"Geography of the target company being acquired, not acquirer headquarters or search radius. Required before generating."},"business_model":{"type":"string","description":"Business model of the target company being acquired."},"end_markets":{"type":"string","description":"End markets served by the target company being acquired."},"customer_type":{"type":"string","description":"Customer type served by the target company being acquired."}}},"example":{"sector":"Industrial Services","subsector":"HVAC Services","size_band":"$10M-$25M revenue","geography":"Texas, United States"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://api.privsource.com/v1/buyer-lists/bl_aB3dE9/criteria\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"sector\":\"Industrial Services\",\"subsector\":\"HVAC Services\",\"size_band\":\"$10M-$25M revenue\",\"geography\":\"Texas, United States\"}'"}],"responses":{"200":{"description":"Updated Buyer List version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerListVersionResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Buyer Lists are only available for seller API tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Buyer List not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Criteria are still being analyzed or the version cannot be edited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["Search criteria are still being analyzed. Wait for status needs_review before updating criteria"]}}}}}}},"/buyer-lists/{id}/generate":{"post":{"tags":["Buyer Lists"],"x-privsource-docs-page":"buyer-lists","x-privsource-order":80,"summary":"Generate a Buyer List","description":"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.","operationId":"generateBuyerList","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Buyer List ID with a bl_ prefix."}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://api.privsource.com/v1/buyer-lists/bl_aB3dE9/generate\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\""}],"responses":{"202":{"description":"Build started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerListVersionResponse"},"example":{"version":{"id":"blv_xK7mP2","version":1,"current":true,"status":"processing","results_count":0,"created_at":"2026-03-20T12:00:00Z","updated_at":"2026-03-20T12:10: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":"","error":null,"contacts":{"status":"not_requested","mode":"none","requested_at":null,"completed_at":null}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required - plan allowance exhausted or not enough credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["You've exhausted your plan's included buyer lists for this period. Purchase a one-off buyer list or upgrade your plan to generate more."]}}}},"403":{"description":"Buyer Lists are only available for seller API tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Buyer List not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Criteria are still being analyzed, required criteria are missing, or a build is already running or completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["Build is already running or completed for this version"]}}}}}}},"/buyer-lists/{id}/cancel":{"post":{"tags":["Buyer Lists"],"x-privsource-docs-page":"buyer-lists","x-privsource-order":90,"summary":"Cancel a Buyer List build","description":"Cancels an in-progress build of the latest version.","operationId":"cancelBuyerList","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Buyer List ID with a bl_ prefix."}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://api.privsource.com/v1/buyer-lists/bl_aB3dE9/cancel\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\""}],"responses":{"200":{"description":"Build canceled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerListVersionResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Buyer Lists are only available for seller API tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Buyer List not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"No build is in progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["This buyer list is not in progress and can't be canceled"]}}}}}}},"/buyer-lists/{id}/refine":{"post":{"tags":["Buyer Lists"],"x-privsource-docs-page":"buyer-lists","x-privsource-order":100,"summary":"Refine a Buyer List","description":"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.","operationId":"refineBuyerList","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Buyer List ID with a bl_ prefix."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"refinement_instructions":{"type":"string","description":"Plain-language instructions describing how to refine the list."},"version_number":{"type":"integer","description":"Optional 1-based version number to refine from. Defaults to the latest version."}}},"example":{"refinement_instructions":"Focus on PE-backed platforms with existing Texas operations"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://api.privsource.com/v1/buyer-lists/bl_aB3dE9/refine\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"refinement_instructions\":\"Focus on PE-backed platforms with existing Texas operations\"}'"}],"responses":{"201":{"description":"New Buyer List version created and building","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerListVersionResponse"},"example":{"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}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required - not enough credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Buyer Lists are only available for seller API tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Buyer List or version not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Parent version is not completed or has fewer than 5 rated results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["At least 5 results must be rated positive or negative before refining"]}}}}}}},"/buyer-lists/{id}/results":{"get":{"tags":["Buyer Lists"],"x-privsource-docs-page":"buyer-lists","x-privsource-order":110,"summary":"List Buyer List results","description":"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.","operationId":"listBuyerListResults","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Buyer List ID with a bl_ prefix."},{"name":"version_number","in":"query","schema":{"type":"integer"},"description":"Optional 1-based version number. Defaults to the latest version."},{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number."},{"name":"per_page","in":"query","schema":{"type":"integer","default":25,"maximum":100},"description":"Results per page. Maximum 100."}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://api.privsource.com/v1/buyer-lists/bl_aB3dE9/results?per_page=10\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\""}],"responses":{"200":{"description":"A paginated list of Buyer List results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerListResultsResponse"},"example":{"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}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Buyer Lists are only available for seller API tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Buyer List or version not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/buyer-lists/{id}/results/{result_id}/feedback":{"post":{"tags":["Buyer Lists"],"x-privsource-docs-page":"buyer-lists","x-privsource-order":120,"summary":"Update feedback on a Buyer List result","description":"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.","operationId":"updateBuyerListResultFeedback","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Buyer List ID with a bl_ prefix."},{"name":"result_id","in":"path","required":true,"schema":{"type":"string"},"description":"Buyer List result ID with a blr_ prefix."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"signal":{"type":"string","enum":["positive","negative","none"],"description":"Feedback signal. Use \"none\" to clear a previous rating."},"comment":{"type":"string","description":"Optional feedback comment."}}},"example":{"signal":"positive","comment":"Great fit, already active in our region"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://api.privsource.com/v1/buyer-lists/bl_aB3dE9/results/blr_qW8nT4/feedback\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"signal\":\"positive\",\"comment\":\"Great fit, already active in our region\"}'"}],"responses":{"200":{"description":"Updated Buyer List result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerListResultFeedbackResponse"},"example":{"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"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Buyer Lists are only available for seller API tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Buyer List or result not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Invalid signal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["Signal must be one of: positive, negative, none"]}}}}}}},"/buyer-lists/{id}/contact-info":{"post":{"tags":["Buyer Lists"],"x-privsource-docs-page":"buyer-lists","x-privsource-order":130,"summary":"Request Buyer List contact info","description":"Requests M\u0026A 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.","operationId":"requestBuyerListContactInfo","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Buyer List ID with a bl_ prefix."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"include_phone":{"type":"boolean","default":false,"description":"Set to true to include phone lookups where available."},"scope":{"type":"string","enum":["all","positive"],"default":"all","description":"Which results to enrich: all results, or only results rated positive."}}},"example":{"include_phone":false,"scope":"all"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://api.privsource.com/v1/buyer-lists/bl_aB3dE9/contact-info\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"include_phone\":false,\"scope\":\"all\"}'"}],"responses":{"202":{"description":"Contact enrichment started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerListVersionResponse"},"example":{"version":{"id":"blv_xK7mP2","version":1,"current":true,"status":"processing_contacts","results_count":40,"created_at":"2026-03-20T12:00:00Z","updated_at":"2026-03-21T10: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":"requested","mode":"basic","requested_at":"2026-03-21T10:00:00Z","completed_at":null}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required - not enough credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["Not enough credits"]}}}},"403":{"description":"Buyer Lists are only available for seller API tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Buyer List not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Build has not finished or a contact request is already in progress or complete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["Buyer list must finish building before contact info can be added"]}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API token provided by PrivSource."}},"schemas":{"DealListResponse":{"type":"object","description":"Paginated list response for the deals index endpoint.","properties":{"deals":{"type":"array","description":"Deal summaries for the current page.","items":{"$ref":"#/components/schemas/DealSummary"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"DealDetailResponse":{"type":"object","description":"Single-deal response for the deal detail endpoint.","properties":{"deal":{"$ref":"#/components/schemas/DealFull"}}},"WhoAmIResponse":{"type":"object","description":"Identity and API access for the current API token.","properties":{"buyer_account":{"type":"object","description":"Present when the token belongs to a buyer account.","properties":{"company_name":{"type":"string","description":"Company name for the current API token."}}},"seller_account":{"type":"object","description":"Present when the token belongs to a seller account.","properties":{"company_name":{"type":"string","description":"Company name for the current API token."}}},"apis":{"type":"array","items":{"type":"string","enum":["deals","buyer-lists"]},"description":"APIs this token can access. Deals requires a buyer account with a paid subscription; buyer-lists requires a seller account with API access enabled."}}},"ErrorResponse":{"type":"object","description":"Error response returned by authenticated API endpoints.","properties":{"errors":{"type":"array","description":"One or more human-readable error messages.","items":{"type":"string"}}},"required":["errors"]},"DealSummary":{"type":"object","description":"Summary shape returned in the deals index response.","properties":{"id":{"type":"string","description":"Deal ID with a dl_ prefix.","example":"dl_gkqMKZ9x"},"name":{"type":"string","description":"Deal name."},"privsource_link":{"type":"string","description":"Authenticated PrivSource buyer deal URL using the deal hashid.","example":"https://privsource.com/buyer/deals/dl_gkqMKZ9x"},"teaser_link":{"type":"string","nullable":true,"description":"Authenticated PrivSource buyer teaser URL using the deal hashid. Redirects to the teaser document or external material when available and visible.","example":"https://privsource.com/buyer/deals/dl_gkqMKZ9x/view"},"date_added":{"type":"string","format":"date","description":"Date the deal was added."},"revenue":{"type":"integer","nullable":true,"description":"Annual revenue in dollars when available."},"ebitda":{"type":"integer","nullable":true,"description":"EBITDA in dollars when available."},"margin_percent":{"type":"integer","nullable":true,"description":"Margin percentage from 0 to 100 when available."},"deal_type":{"type":"string","enum":["buyout","capital_raise",""],"description":"Deal type."},"outreach_available":{"type":"boolean","description":"Whether this deal currently has recipients available for buyer outreach."},"primary_industry":{"type":"string","nullable":true,"description":"Primary industry label when available."},"sub_industry":{"type":"string","nullable":true,"description":"Sub-industry label when available."},"secondary_industry":{"type":"string","nullable":true,"description":"Secondary industry label when available."},"industries":{"type":"array","description":"Matched industry labels for the deal.","items":{"type":"string"}},"location":{"type":"string","nullable":true,"description":"Location label when available."}}},"DealFull":{"type":"object","description":"Full deal shape returned by the deal detail endpoint.","allOf":[{"$ref":"#/components/schemas/DealSummary"},{"type":"object","properties":{"description":{"type":"string","description":"Long-form deal description."},"reason_for_sale":{"type":"string","description":"Seller's reason for sale when available."},"growth_opportunities":{"type":"string","description":"Growth opportunities when available."},"deal_link":{"type":"string","nullable":true,"description":"URL to the teaser or external deal material when available and visible."},"nda_link":{"type":"string","nullable":true,"description":"URL to the NDA document when available."},"contacts":{"type":"array","description":"Deal contacts. Empty array if contacts are not available for this deal.","items":{"$ref":"#/components/schemas/Contact"}}}}]},"Contact":{"type":"object","description":"Deal contact details.","properties":{"name":{"type":"string","description":"Contact name."},"email":{"type":"string","description":"Contact email."},"phone":{"type":"string","description":"Phone number when available."},"title":{"type":"string","description":"Job title when available."}},"required":["name","email"]},"PaginationMeta":{"type":"object","description":"Pagination metadata returned by list endpoints.","properties":{"current_page":{"type":"integer","description":"Current page number."},"total_pages":{"type":"integer","description":"Total number of pages."},"total_count":{"type":"integer","description":"Total matching record count."},"per_page":{"type":"integer","description":"Results returned per page."},"filters":{"type":"object","description":"Applied filters. Only present when filters are active.","properties":{"industries":{"type":"array","description":"Matched industry names from the natural language query.","items":{"type":"string"}},"locations":{"type":"array","description":"Matched location names from the natural language query.","items":{"type":"string"}},"revenue_min":{"type":"integer","description":"Minimum revenue filter."},"revenue_max":{"type":"integer","description":"Maximum revenue filter."},"ebitda_min":{"type":"integer","description":"Minimum EBITDA filter."},"ebitda_max":{"type":"integer","description":"Maximum EBITDA filter."},"margin_percent_min":{"type":"integer","description":"Minimum margin percentage filter."},"margin_percent_max":{"type":"integer","description":"Maximum margin percentage filter."},"deal_type":{"type":"string","description":"Applied deal type filter."}}}}},"DataColumnExamplesResponse":{"type":"object","description":"Response returned by the data column examples endpoint.","properties":{"data_column_examples":{"type":"array","description":"Built-in and account-specific data column examples.","items":{"$ref":"#/components/schemas/DataColumnExample"}}}},"DataColumnExample":{"type":"object","description":"Example data column returned by the examples endpoint.","properties":{"title":{"type":"string","description":"Column title."},"description":{"type":"string","description":"Column description."},"format":{"type":"string","enum":["text","number","date","url","options"],"description":"Column output format."},"source":{"type":"string","enum":["default","custom"],"description":"Whether the example is built-in or account-specific."}}},"BuyerListListResponse":{"type":"object","description":"Paginated list response for the buyer lists index endpoint.","properties":{"buyer_lists":{"type":"array","description":"Buyer List summaries for the current page.","items":{"$ref":"#/components/schemas/BuyerListSummary"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"BuyerListCreateResponse":{"type":"object","description":"Response returned when creating a buyer list.","properties":{"buyer_list":{"$ref":"#/components/schemas/BuyerList"},"version":{"$ref":"#/components/schemas/BuyerListVersion"}}},"BuyerListResponse":{"type":"object","description":"Response returned by buyer list metadata endpoints.","properties":{"buyer_list":{"$ref":"#/components/schemas/BuyerList"}}},"BuyerListVersionResponse":{"type":"object","description":"Response returned by buyer list version endpoints.","properties":{"version":{"$ref":"#/components/schemas/BuyerListVersion"}}},"BuyerListResultsResponse":{"type":"object","description":"Paginated result rows for one buyer list version.","properties":{"version":{"$ref":"#/components/schemas/BuyerListVersionSummary"},"results":{"type":"array","description":"Result rows for the current page.","items":{"$ref":"#/components/schemas/BuyerListResult"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"BuyerListResultFeedbackResponse":{"type":"object","description":"Response returned when updating feedback on a buyer list result.","properties":{"result":{"$ref":"#/components/schemas/BuyerListResult"}}},"BuyerListSummary":{"type":"object","description":"Buyer list metadata without version summaries.","properties":{"id":{"type":"string","description":"Buyer List ID with a bl_ prefix.","example":"bl_aB3dE9"},"name":{"type":"string","description":"Display title for the buyer list."},"custom_name":{"type":"string","description":"User-provided title for the buyer list."},"status":{"type":"string","enum":["empty","analyzing","needs_review","processing","ready","processing_contacts","ready_with_contacts","errored","canceled"],"description":"Overall status derived from the latest version. \"empty\" when no versions exist."},"tier":{"type":"string","nullable":true,"enum":["standard","demo","freemium"],"description":"Result tier decided at the generate step. Null until the first build starts. Lists generated via the API are standard tier."},"archived":{"type":"boolean","description":"Whether the buyer list is archived."},"current_version_number":{"type":"integer","nullable":true,"description":"Current version number when a version exists."},"current_version":{"nullable":true,"description":"Summary of the current (latest) version, including result and feedback counts. Null when no versions exist.","allOf":[{"$ref":"#/components/schemas/BuyerListVersionSummary"}]},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp."},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp."}}},"BuyerList":{"type":"object","description":"Buyer list metadata and version summaries.","allOf":[{"$ref":"#/components/schemas/BuyerListSummary"},{"type":"object","properties":{"versions":{"type":"array","description":"Version summaries ordered by creation time.","items":{"$ref":"#/components/schemas/BuyerListVersionSummary"}}}}]},"BuyerListVersionSummary":{"type":"object","description":"Summary fields shared across buyer list version responses.","properties":{"id":{"type":"string","description":"Buyer List version ID with a blv_ prefix.","example":"blv_xK7mP2"},"version":{"type":"integer","description":"1-based version number."},"current":{"type":"boolean","description":"Whether this is the current version."},"status":{"type":"string","enum":["analyzing","needs_review","processing","ready","processing_contacts","ready_with_contacts","errored","canceled"],"description":"Version status. Criteria are extracted while analyzing, reviewed and edited during needs_review, and the list is built while processing."},"results_count":{"type":"integer","description":"Number of result rows currently visible."},"positive_results_count":{"type":"integer","description":"Results rated with a positive feedback signal."},"negative_results_count":{"type":"integer","description":"Results rated with a negative feedback signal."},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp."},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp."}}},"BuyerListVersion":{"type":"object","description":"Full buyer list version shape.","allOf":[{"$ref":"#/components/schemas/BuyerListVersionSummary"},{"type":"object","properties":{"name":{"type":"string","description":"Display title for this version."},"description":{"type":"string","description":"User-provided description used to create this version."},"refinement_instructions":{"type":"string","description":"Refinement instructions when this version was created by a refine."},"criteria":{"$ref":"#/components/schemas/BuyerListCriteria"},"summary":{"type":"string","description":"Generated summary of the completed buyer list."},"error":{"type":"string","nullable":true,"description":"Public error message when the version errored."},"contacts":{"$ref":"#/components/schemas/BuyerListContacts"}}}]},"BuyerListCriteria":{"type":"object","description":"Search criteria extracted from the description and files, editable while the version is in needs_review.","properties":{"sector":{"type":"string","description":"Primary sector. Required before generating."},"subsector":{"type":"string","description":"Subsector. Required before generating."},"size_band":{"type":"string","description":"Company size band. Required before generating."},"geography":{"type":"string","description":"Geography. Required before generating."},"business_model":{"type":"string","description":"Business model."},"end_markets":{"type":"string","description":"End markets served."},"customer_type":{"type":"string","description":"Customer type."}}},"BuyerListContacts":{"type":"object","description":"Contact enrichment status for a buyer list version.","properties":{"status":{"type":"string","enum":["not_requested","requested","processing","completed","errored"],"description":"Contact enrichment status."},"mode":{"type":"string","enum":["none","basic","basic,phone"],"description":"Requested contact mode."},"requested_at":{"type":"string","format":"date-time","nullable":true,"description":"When contact enrichment was requested."},"completed_at":{"type":"string","format":"date-time","nullable":true,"description":"When contact enrichment finished."}}},"BuyerListResult":{"type":"object","description":"One potential acquirer row in a buyer list version.","properties":{"id":{"type":"string","description":"Buyer List result ID with a blr_ prefix.","example":"blr_qW8nT4"},"company_name":{"type":"string","description":"Company name."},"company_description":{"type":"string","description":"Company description."},"buyer_type":{"type":"string","description":"Buyer type, for example Strategic, PE Platform, or PE Firm."},"buyer_type_category":{"type":"string","description":"Buyer type category, for example Strategic Operator or Financial Sponsor."},"tier":{"type":"string","description":"Tier label, for example Proven Acquirer or Strategic Candidate."},"ownership":{"type":"string","description":"Ownership type."},"ownership_details":{"type":"string","description":"Ownership details, for example the PE backer or parent company."},"website":{"type":"string","nullable":true,"description":"Company website URL when available."},"domain":{"type":"string","description":"Company website domain."},"hq":{"type":"object","description":"Headquarters location.","properties":{"city":{"type":"string","description":"HQ city."},"state":{"type":"string","description":"HQ state or region."},"country":{"type":"string","description":"HQ country."}}},"size_fit":{"type":"string","description":"How this acquirer fits the requested size band."},"revenue_band":{"type":"string","description":"Estimated revenue band."},"deals_last_24_months":{"type":"integer","nullable":true,"description":"Acquisitions in the last 24 months when known."},"total_deals":{"type":"integer","nullable":true,"description":"Total known acquisitions."},"last_deal_date":{"type":"string","format":"date","nullable":true,"description":"Date of the most recent known acquisition."},"relevant_details":{"type":"string","description":"Why this company is a relevant potential acquirer."},"description_bullets":{"type":"array","description":"Short bullet points describing the company.","items":{"type":"string"}},"feedback":{"$ref":"#/components/schemas/BuyerListResultFeedback"},"contacts":{"$ref":"#/components/schemas/BuyerListResultContacts"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp."},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp."}}},"BuyerListResultFeedback":{"type":"object","description":"Feedback recorded on a buyer list result.","properties":{"signal":{"type":"string","enum":["positive","negative"],"nullable":true,"description":"Feedback signal. Null when no feedback has been recorded."},"comment":{"type":"string","description":"Feedback comment."}}},"BuyerListResultContacts":{"type":"object","description":"M\u0026A contact enrichment for one buyer list result.","properties":{"status":{"type":"string","enum":["not_requested","queued","running","completed","failed"],"description":"Contact enrichment status for this result."},"entries":{"type":"array","description":"Enriched contacts for this result.","items":{"$ref":"#/components/schemas/BuyerListContactEntry"}}}},"BuyerListContactEntry":{"type":"object","description":"One enriched M\u0026A contact.","properties":{"full_name":{"type":"string","description":"Full name."},"first_name":{"type":"string","description":"First name."},"last_name":{"type":"string","description":"Last name."},"title":{"type":"string","description":"Job title."},"email":{"type":"string","description":"Email address when available."},"phone":{"type":"string","description":"Phone number when available and requested."},"linkedin_url":{"type":"string","description":"LinkedIn profile URL when available."}}}}}}