Company enrichment

POST https://tools.yukai.uk/api/v1/company/enrich

Enrich a company from its domain. Returns the company profile built from its website and public DNS / RDAP records. No AI: industry is a deterministic guess (schema.org type, government domains, keywords) with its signals. Pages read: the home page plus about, contact and careers pages (maxPages, default 4), decoded with the site's real charset; a real browser only when the site blocks bots or needs JavaScript. DNS, RDAP and one public ATS job feed are read in parallel. Every fact carries the page it came from (evidence). Results are cached for 12 hours.

Cost

Credits: 54 ($0.0054) per successful call. Failed calls are free. Source price: company-website-enrichment/company-enriched.

Input

Send a JSON body (POST) or the same fields as a query string (GET).

Required: domain or url or website or name.

Field	Type	Default	Description
`domain`	string		Company domain or website URL (`stripe.com`, `https://www.acme.de/en`). An e-mail address works too (its domain is used). Aliases: `url`, `website`. Required unless `name` is sent. Private and local addresses are refused.
`name`	string		Company name, used only when no `domain` is sent: candidate domains are built from the name (+ `country`), resolved over DNS, and a site counts only when its own name (schema.org, og:site_name or title) is this name. Otherwise `422 company_not_found`: send the domain.
`country`	string		With `name`: 2-letter ISO country code; its domain endings (e.g. `.de`, `.co.uk`, `.co.jp`) are tried before `.com`.
`maxPages`	integer	`4`	Pages of the site to read, home page included: about, contact and careers pages first, then imprint, team and locations.
`render`	string	`"auto"`	`auto` (default): plain HTTP, and a real Chrome browser for the home page only when the site blocks plain requests or needs JavaScript. `never`: HTTP only.
`includeJobs`	boolean	`true`	Look for the company's ATS job board and count open jobs (`companySize`).
`includeDns`	boolean	`true`	Return the DNS findings (`dns`: MX provider, SPF includes, verification records, DNS host).
`includeRdap`	boolean	`true`	Look up the domain's registration (`domainRegistration`: creation date, age, registrar).
`includeEvidence`	boolean	`true`	Return `evidence` (source and page URL per field) and `foundedYearText`.
`ai`	boolean	`false`	Only `false` is accepted here: the AI classification is the `/api/v1/company/enrich/ai` endpoint (billed separately).
`url`
`website`

Examples

Replace tt_live_XXXX with your key from the pricing page.

curl

curl -i -X POST "https://tools.yukai.uk/api/v1/company/enrich" \
  -H "Authorization: Bearer tt_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"domain":"stripe.com"}'

JavaScript (fetch)

const res = await fetch("https://tools.yukai.uk/api/v1/company/enrich", {
  method: "POST",
  headers: { "Authorization": "Bearer tt_live_XXXX", "Content-Type": "application/json" },
  body: JSON.stringify({"domain":"stripe.com"}),
});
console.log(res.status, res.headers.get("x-credits-charged"), res.headers.get("x-credits-balance"));
console.log(await res.json());

Python (requests)

import requests

r = requests.post(
    "https://tools.yukai.uk/api/v1/company/enrich",
    headers={"Authorization": "Bearer tt_live_XXXX"},
    json={"domain": "stripe.com"},
    timeout=120,
)
print(r.status_code, r.headers.get("x-credits-charged"), r.headers.get("x-credits-balance"))
print(r.json())

Enrich a CSV file

Download company-enrichment-csv.py, a small Python script (3.8 or newer, nothing else to install) that sends a CSV of companies to this route one row at a time and writes every row back with the results.

The script reads your key from the environment variable TIDYTOOLS_API_KEY; it is never written to the output or the log.

curl -O "https://tools.yukai.uk/downloads/company-enrichment-csv.py"
export TIDYTOOLS_API_KEY=tt_live_XXXX    # PowerShell: $env:TIDYTOOLS_API_KEY = "tt_live_XXXX"
python company-enrichment-csv.py --input companies.csv --output enriched.csv \
  --name-column name --domain-column domain --country-column country --id-column id

Give --name-column, --domain-column or both; --country-column and --id-column are optional. A row with a domain sends only the domain; otherwise it sends the name and its two-letter country. A non-Latin name usually cannot be turned into a domain to check, so fill in the domain for those companies. Rows with neither, or with a country that is not two letters, are skipped. The input is read as UTF-8.

The output keeps all your columns and rows in their order, then adds enrich_domain, enrich_name, enrich_primaryEmail, enrich_primaryPhone, enrich_status and enrich_errorType. enrich_status is success, error, skipped (the row has nothing valid to send) or not_sent (the row could be sent, but the run had stopped, for example when the balance ran out). A company that cannot be found stays in the file with enrich_status error and enrich_errorType company_not_found from the API's error.code.

When the run stops on the key or the balance, the row that got that answer is error with that code. Later rows that could be sent are not_sent with the same reason; rows with nothing valid to send stay skipped. To finish, send the not_sent rows and the row with that code again.

Each row sent is one call to this route, at the price in Cost and on the pricing page: charged when it succeeds, free on any non-2xx answer such as company_not_found.

Response

JSON with "success": true and the result fields; on failure {"success": false, "error": {"code", "message", "retryable"}} and no credits are used. Every answer carries x-credits-charged (credits used) and x-credits-balance (balance after the call); check the balance any time with GET https://tools.yukai.uk/v1/billing/balance.

Full field list and response schema: OpenAPI spec company-enrichment (its servers entry is the marketplace gateway; call https://tools.yukai.uk with your key).

← All routes · Pricing