Buyer Screening - Wokelo Docs

1. Overview

The Buyer Screening API identifies and scores potential acquirers for a defined target company. Given a target and a set of strategic criteria, Wokelo’s AI pipeline searches its coverage universe, evaluates each candidate buyer against the target, and returns a ranked list with AI-generated deal scores, synergy commentary, and full financial profiles. This is an asynchronous API — submitting a request returns a request_id immediately, and you must poll for status and then retrieve results once the job is complete. Read more about the async pattern in How Async APIs work. Each buyer in the result set is evaluated across four dimensions:

Overall Score — composite strategic fit rating (1–10)
Deal Feasibility Score — likelihood the buyer can financially execute the acquisition
Product Synergy Score — degree of product and capability overlap
Deal Precedent Score — alignment with the buyer’s historical M&A pattern
Synergy Potential Score — quantified revenue and cost synergy opportunity

Each score is accompanied by an AI-written rationale and an overall commentary paragraph synthesising the deal thesis. Common use cases:

Sell-side M&A advisory — Generate a scored buyer universe for board-level presentations and process initiation
Corporate development — Identify strategic acquirers for portfolio companies or subsidiaries
Investment banking — Rapidly populate a buyer list for pitch books or CIM preparation
Private equity exits — Screen strategic and financial buyers for portfolio company sale processes

This API is asynchronous. You submit a job, receive a request_id, poll until status is "COMPLETED", and then read results from the same response. See How Async APIs work.

2. Quick Start

Step 1 — Submit the job

curl --location 'https://api.wokelo.ai/api/enterprise/buyer-screening/enrich/' \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "company": "acme-security",
    "parameters": {
      "detailed_query": "Looking for strategic acquirers in enterprise software",
      "buyer_type": ["strategic"],
      "company_type": "public",
      "geography": ["United States"]
    }
  }'

Step 2 — Poll for completion

import time

while True:
    status_resp = requests.get(
        f"https://api.wokelo.ai/api/enterprise/request/{request_id}/status/",
        headers={"Authorization": "Bearer <YOUR_API_TOKEN>"}
    )
    status = status_resp.json()["status"]
    if status == "COMPLETED":
        break
    elif status == "FAILED":
        raise Exception("Job failed")
    print(f"Status: {status} — waiting...")
    time.sleep(5)

Step 3 — Read results

result_resp = requests.get(
    f"https://api.wokelo.ai/api/enterprise/request/{request_id}/result/",
    headers={"Authorization": "Bearer <YOUR_API_TOKEN>"}
)
buyers = result_resp.json()["result"]
for buyer in buyers:
    print(buyer["Name"], "— Overall Score:", buyer.get("Overall Score"))

3. Authentication

All requests must include a Bearer token in the Authorization HTTP header. No other authentication method is supported.

Authorization: Bearer <YOUR_API_TOKEN>

API tokens are issued from your Wokelo account. Navigate to Account Details → API Credentials in the Wokelo dashboard to get your client id and client secret. Contact support@wokelo.ai if you do not yet have API access.

Never expose your token in client-side code, browser requests, or public repositories. A missing or invalid token returns 401 Unauthorized. A valid token without sufficient plan permissions returns 403 Forbidden.

4. Request Reference

Endpoint

POST https://api.wokelo.ai/api/enterprise/buyer-screening/enrich/

The request body is JSON. Only company is required; all parameters fields are optional refinements.

Parameter	Type	Required	Description
`company`	string	Required	Permalink (e.g. `"brex"`) or full URL of the target company being acquired. Use the Company Search API to resolve a permalink if needed.
`parameters.detailed_query`	string	Optional	A natural-language description of the ideal acquirer profile, strategic rationale, or deal criteria. The more specific, the more targeted the buyer universe. Example: `"Looking for companies in spend management, corporate cards, and CFO workflow software with mid-market and enterprise distribution"`.
`parameters.buyer_type`	string or string[]	Optional	Type of buyer to screen for. Accepted values: `"strategic"`, `"financial"`, or both as an array `["strategic", "financial"]`. Defaults to all types if omitted.
`parameters.company_type`	string	Optional	Limits results to a specific company ownership type. Accepted values: `"public"`, `"private"`, or `"all"`. Defaults to `"all"` if omitted.
`parameters.geography`	string[]	Optional	Geographic scope for the buyer search. Pass country names or ISO codes (e.g. `["United States"]`, `["USA", "GBR"]`). Defaults to global if omitted.

Full request example:

curl --location 'https://api.wokelo.ai/api/enterprise/buyer-screening/enrich/' \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "company": "brex",
    "parameters": {
      "detailed_query": "Looking for companies in spend management, corporate cards, and CFO workflow software with mid-market and enterprise distribution",
      "buyer_type": "strategic",
      "company_type": "public",
      "geography": ["USA"]
    }
  }'

5. Response

Job submission response

When you submit the job, you receive a response immediately with a request_id and an initial status.

{
  "request_id": "c685171e-ce46-474b-b0de-f17123b3085a",
  "status": "PROCESSING"
}

Field	Type	Description
`request_id`	string	Unique identifier for this job. Use it to poll status and retrieve results.
`status`	string	Initial job state. One of `"PENDING"`, `"PROCESSING"`, `"COMPLETED"`, `"FAILED"`.

Completed result response

Once status is "COMPLETED", the result contains a result array of buyer objects.

{
  "request_id": "c685171e-ce46-474b-b0de-f17123b3085a",
  "status": "COMPLETED",
  "result": [ ...buyer objects... ]
}

Buyer object fields

Each object in the result array contains the following fields: Identity & firmographics

Field	Type	Description
`Permalink`	string	Wokelo company identifier for the buyer (e.g. `"visa"`, `"intuit"`).
`Name`	string	Display name of the buyer company.
`Website`	string	Buyer’s primary domain (e.g. `"visa.com"`).
`HQ City`	string	Headquarters city.
`HQ Country`	string	Headquarters country.
`HQ Continent`	string	Headquarters continent.
`Founded`	string	Year the company was founded.
`Type`	string	Ownership type: `"Public"` or `"Private"`.
`Operating Status`	string	Current operational status (e.g. `"IPO"`, `"Acquired"`).
`Buyer Type`	string	Classification of the buyer: `"Strategic"`, `"Financial"`, or `"Institutional"`.

Product & business

Field	Type	Description
`Product Category`	string	High-level category describing the buyer’s primary product (e.g. `"Payment Processing Network"`).
`Core Offering`	string	AI-generated paragraph describing the buyer’s core business.
`Product Catalog`	string	Comma-separated list of key products and services offered.

People & funding

Field	Type	Description
`Employees (Crunchbase)`	string	Employee count range from Crunchbase (e.g. `"10000+"`).
`Employees (LinkedIn)`	integer or empty	Employee count from LinkedIn. May be empty.
`Funding Stage`	string	Most recent funding stage. May be empty for public companies.
`Total Funding`	string	Total disclosed funding raised. May be empty.
`Last Funding Date`	string	Date of the most recent funding round. May be empty.
`Key Investors`	string[] or empty	Array of notable investors.

Financials (public companies)

Field	Type	Description
`Revenue`	float	Annual revenue in USD.
`EBITDA`	float	Earnings before interest, taxes, depreciation, and amortisation.
`Net Income`	float	Net income in USD.
`EBITDA Margin (%)`	float	EBITDA as a percentage of revenue.
`Net Income Margin (%)`	float	Net income as a percentage of revenue.
`EPS Diluted`	float	Diluted earnings per share.
`ROA (%)`	float	Return on assets.
`Unlevered FCF`	float	Unlevered free cash flow in USD.
`D/E`	float	Debt-to-equity ratio.
`Market Cap`	float	Market capitalisation in USD.
`Enterprise Value`	float	Enterprise value in USD.
`EV/Revenue (LTM)`	float	Enterprise value to last-twelve-months revenue multiple.
`EV/EBITDA (LTM)`	float	Enterprise value to LTM EBITDA multiple.
`P/E (LTM)`	float	Price-to-earnings ratio on LTM basis.
`Ticker`	string	Exchange and ticker symbol (e.g. `"NYSE:V"`).

M&A history

Field	Type	Description
`Acquisitions`	string	Comma-separated list of past acquisitions with year (e.g. `"Pismo (2023), Tink (2021)"`).
`Investments`	string	Notable investments made by the buyer. May be empty.

AI scoring (present on high-relevance buyers)

Field	Type	Description
`Overall Score`	float	Composite strategic fit score from 1–10. Higher is a stronger acquirer candidate.
`Overall Score Rationale`	string	One-sentence explanation of the Overall Score.
`Commentary`	string	Full AI-written deal thesis paragraph evaluating the strategic rationale, synergies, and risks.
`Deal Feasibility Score`	float	Score (1–10) assessing whether the buyer can financially execute the acquisition given its size, balance sheet, and deal history.
`Deal Feasibility Rationale`	string	One-sentence rationale for the Deal Feasibility Score.
`Product Synergy Score`	float	Score (1–10) measuring product and capability overlap between buyer and target.
`Product Synergy Rationale`	string	One-sentence rationale for the Product Synergy Score.
`Deal Precedent Score`	float	Score (1–10) measuring how closely this deal aligns with the buyer’s historical M&A pattern and deal size.
`Deal Precedent Rationale`	string	One-sentence rationale for the Deal Precedent Score.
`Synergy Potential Score`	float	Score (1–10) estimating the revenue and cost synergies achievable post-acquisition.
`Synergy Potential Rationale`	string	One-sentence rationale for the Synergy Potential Score.

AI scoring fields (Overall Score, Commentary, and the four sub-scores) are only present on buyers where Wokelo’s AI has sufficient data to generate a reliable assessment. Buyers without scores are still returned with full firmographic and financial data.

6. Examples

Sell-side M&A: board-level buyer universe

Find strategic acquirers for Brex — public companies in spend management, corporate cards, and CFO workflow software with US distribution. Filter results to the highest-scored buyers for a board presentation.

curl --location 'https://api.wokelo.ai/api/enterprise/buyer-screening/enrich/' \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "company": "brex",
    "parameters": {
      "detailed_query": "Looking for companies in spend management, corporate cards, and CFO workflow software with mid-market and enterprise distribution",
      "buyer_type": "strategic",
      "company_type": "public",
      "geography": ["USA"]
    }
  }'

Financial buyer screening

Screen for private equity and institutional buyers for a B2B SaaS company, globally.

import requests

response = requests.post(
    "https://api.wokelo.ai/api/enterprise/buyer-screening/enrich/",
    headers={
        "Authorization": "Bearer <YOUR_API_TOKEN>",
        "Content-Type": "application/json"
    },
    json={
        "company": "acme-saas",
        "parameters": {
            "detailed_query": "Financial sponsors and PE firms with B2B SaaS and fintech portfolio experience",
            "buyer_type": ["financial"],
            "company_type": "all"
        }
    }
)
print(response.json()["request_id"])

7. Error Handling

The API uses standard HTTP status codes. All error responses include a JSON body with a detail or message field.

Status	Meaning	Cause & Resolution
`200 OK`	Success	Job submitted or result retrieved successfully.
`400 Bad Request`	Invalid parameters	A required field is missing or a parameter value is invalid — e.g. unrecognised `buyer_type`. Check the `detail` field in the response body.
`401 Unauthorized`	Auth failed	The `Authorization` header is missing, malformed, or contains an invalid token. Verify your key in Settings → API Keys.
`403 Forbidden`	Insufficient access	Your plan does not include access to this endpoint. Contact support@wokelo.ai to review your plan.
`404 Not Found`	Company or job not found	The `company` permalink could not be resolved, or the `request_id` does not exist. Use the Company Search API to verify the company permalink.
`429 Too Many Requests`	Rate limit exceeded	Implement exponential back-off. The response includes a `Retry-After` header.
`500 Internal Server Error`	Server error	Retry after a brief delay. If the issue persists, contact support@wokelo.ai with your `request_id`.

Error response example:

{
  "status": "error",
  "detail": "Company permalink 'unknown-co' could not be resolved."
}

Job failure handling:

import requests, time

def poll_until_done(request_id, headers, interval=5, timeout=300):
    elapsed = 0
    while elapsed < timeout:
        resp = requests.get(
            f"https://api.wokelo.ai/api/enterprise/request/{request_id}/status/",
            headers=headers
        ).json()
        status = resp["status"]
        if status == "COMPLETED":
            return True
        elif status == "FAILED":
            raise Exception(f"Job {request_id} failed: {resp.get('detail', 'unknown error')}")
        time.sleep(interval)
        elapsed += interval
    raise TimeoutError(f"Job {request_id} did not complete within {timeout}s")

8. Best Practices

Write a specific detailed_query for better results The detailed_query parameter is the single most impactful way to sharpen the buyer universe. Generic queries like "strategic acquirers" return broad results. Specific queries that name product categories, distribution models, customer segments, and deal rationale return a more focused and relevant set. For example:

“Looking for companies in spend management, corporate cards, and CFO workflow software with mid-market and enterprise distribution”

is far more targeted than:

“Looking for technology companies”

Combine buyer_type and company_type to bound the universe If your process targets only strategic acquirers capable of an all-cash deal, set buyer_type: "strategic" and company_type: "public" to limit results to entities with public-market capital access. For financial sponsor processes, set buyer_type: "financial". Sort and tier by Overall Score before review The Overall Score is Wokelo’s composite fit metric. Sort the result set descending by Overall Score and segment into tiers (e.g. 8–10: Priority, 5–7: Secondary, below 5: Monitor) before reviewing individual rationales. This dramatically reduces time spent reviewing low-fit candidates. Use Deal Feasibility Score to screen out financially constrained buyers A high Overall Score paired with a low Deal Feasibility Score indicates a strategically attractive but financially constrained buyer. Filter out buyers with Deal Feasibility Score < 5 early in the process unless you are exploring merger-of-equals structures. Read Commentary for the full deal narrative The Commentary field contains Wokelo’s most detailed AI output — a full paragraph synthesising the strategic rationale, synergy thesis, and key risks for each buyer. Use this field to draft the strategic rationale section of pitch books or CIMs, or to brief deal teams before outreach. Store the request_id for auditability Buyer screening jobs are associated with your account and a specific point in time. Store the request_id alongside the target company and run date so you can re-retrieve results later, track how the universe evolves across multiple runs, and audit which buyer list was used for a given process. Re-run with different parameters to stress-test the universe Run the same target with different buyer_type, company_type, and geography parameters to discover buyers that might be missed by a single query. Comparing results across runs helps identify edge-case buyers worth adding to a long list.

Target Screening

Identify and score acquisition targets for a defined acquirer — the inverse of Buyer Screening.

Market Map

Discover and map all companies competing in a specific market or product category.

Competitor List

Generate a structured list of direct and indirect competitors for any company.

Company Deep Intelligence

Generate deep AI intelligence on any buyer — business model, financials, strategy, and M&A history.

M&A Activity

Retrieve historical acquisition data for any company to validate Deal Precedent scores.

Company Instant Enrichment

Synchronously enrich firmographic and financial data for any buyer in the screened list.

Documentation Index

​1. Overview

​2. Quick Start

​3. Authentication

​4. Request Reference

​5. Response

​Job submission response

​Completed result response

​Buyer object fields

​6. Examples

​Sell-side M&A: board-level buyer universe

​Financial buyer screening

​7. Error Handling

​8. Best Practices

​9. Related APIs

Target Screening

Market Map

Competitor List

Company Deep Intelligence

M&A Activity

Company Instant Enrichment

1. Overview

2. Quick Start

3. Authentication

4. Request Reference

5. Response

Job submission response

Completed result response

Buyer object fields

6. Examples

Sell-side M&A: board-level buyer universe

Financial buyer screening

7. Error Handling

8. Best Practices

9. Related APIs