Milda API

Milda API Overview

Milda turns a company website into a detailed profile: what the company sells and to whom, where it operates, what it ships, patents, publishes, who works there, and what risk it carries. This page maps the endpoint groups and shows how they fit together. Each endpoint page covers its request, response, and credit cost in detail.

---

Getting Started

• Base URL — https://api.milda.ai
• Versioning — every endpoint is served under /v1. Breaking changes ship as a new version prefix, never inside /v1.
• Authentication — send your API token with every request, in one of two headers: token: YOUR_API_TOKEN, or the standard Authorization: Bearer YOUR_API_TOKEN (the word Bearer, a space, then your token). Use either one; you don't need both. There is no OAuth flow and no per-request signing.
• Check your token — GET /v1/credit-usage returns the token, its expiration date, and remaining credits.

curl -X POST https://api.milda.ai/v1/companies/lookup \
  -H "token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"website": "milda.ai"}'

The same request with the Authorization header:

curl -X POST https://api.milda.ai/v1/companies/lookup \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"website": "milda.ai"}'

Almost everything else is POST with a JSON body. Company IDs (e.g. C1ffe0198c4ca3a12) link the endpoints together: search and lookup endpoints return them, and every data and insight endpoint takes them as input.

---

The Typical Flow

1. Find companies — lookup when you already know the company; text-search to build a list from what companies do; status when you have URLs or emails.
2. Get their data — enrichment for companies Milda does not hold yet, profiles for firmographics, events for the raw news feed.
3. Go deep on one company — the insight endpoints (products, places-of-performance, growth-signals) and the specialised modules below (trade data, patents, publications, risk assessment).
4. Reach the people — people/search, then people/verified-email.

---

Company Search

• Find Company — POST /v1/companies/lookup
  Resolve one known company to its Milda ID by name, website, or registration number. Use this when you already know who you are looking for.

• Text Search — POST /v1/companies/text-search
  Free-text search over what companies actually do. Accepts a plain keyword (creative agency, private credit) or a full descriptive phrase (conversion of atmospheric CO₂ into carbonate minerals using steel slag). This is the endpoint for niche segments that industry codes cannot express.

• Text Search Insights — POST /v1/companies/text-search/insights
  Why a company from your search results matched: the passage tying it to your query and its market segments. Free, using the search's search_id.

---

Company Data

Firmographics with corrected NACE and US SIC classifications, plus company-level insight reports built from all the data Milda holds on each company.

• Submit Companies for Enrichment — POST /v1/companies/enrichment
  Queue companies Milda does not yet hold (status NOT_PROCESSED). Enrichment completes in 24–48 hours, after which they behave like any other company on the platform.

• Get Company Profiles — POST /v1/companies/profiles
  Full profile documents by company ID or URL: business description, activities, industries, country, size, age, and more.

• Get Company Statuses — POST /v1/companies/status
  Up to 1,000 IDs, 1,000 URLs and 1,000 emails per request. Returns each company's Milda ID and live status. It costs no credits, so use it to check what is already on the platform before spending credits on data.

• Get Events Data — POST /v1/companies/events
  The raw business-event feed: 11 event types (funding and investment, partnerships, contracts, prizes, and more) for up to 25 company IDs and 25 URLs per request, with exclude_event_ids to leave out events you already have.

• Growth Signals — POST /v1/companies/growth-signals
  The curated version of the same material: a de-duplicated, significance-rated timeline of notable developments plus a one-sentence read on the company's trajectory. Use this for sales triggers and briefings; use events when you want every underlying mention.

• Places of Performance — POST /v1/companies/places-of-performance
  The countries a company operates in, rather than where it is incorporated, and what it does in each: production sites, subsidiaries, offices, delivered projects.

• Products & Clients — POST /v1/companies/products
  The products and services a company sells, each with the kinds of companies that buy it. Pass a product's description or one of its client segments to text-search to find the company's competitors or potential clients.

---

Trade Data

Import/export activity from shipment-level customs records. A two-step flow: resolve the company to a trade-database candidate, then query that candidate.

1. Candidates — POST /v1/trade-data/candidates — matching companies in the trade database with their shipment counts. Free of charge.
2. Analytics — POST /v1/trade-data/analytics — aggregated import (imp) or export (exp) report for a candidate.
3. Shipping Records — POST /v1/trade-data/shipping-records — the individual shipments behind the analytics, paginated, with optional date filters.
4. Shipment Suppliers / Recipients — POST /v1/trade-data/shipment-suppliers and POST /v1/trade-data/shipment-recipients — who the company sources from and who it sells to, ranked by trade volume.

---

Patents

The company's IP position and its place in the citation graph. All endpoints take a company_id.

• Summary — POST /v1/patents/summary — headline KPIs: patent count, average family size, and more.
• Patent List — POST /v1/patents/list — paginated patents, filterable by family, publication number, and filing-date range.
• Inventors — POST /v1/patents/inventors — top inventors on the company's patents.
• Co-applicants — POST /v1/patents/co-applicants — entities that co-applied with it.
• Technology Users — POST /v1/patents/technology-users — organizations citing the company's patents: who builds on its technology.
• Technology Providers — POST /v1/patents/technology-providers — organizations whose patents it cites: what it builds on.
• Citations — POST /v1/patents/citations — patent-level incoming or outgoing citations, paginated.

---

Publications

Research output attributed to the company, useful for R&D-intensive and deep-tech segments. All endpoints take a company_id.

• Analytics — POST /v1/publications/analytics — total publications, share in the top 1% most-cited worldwide, and breakdowns by year and research topic.
• Authors — POST /v1/publications/authors — top authors publishing under the company, with h-index and publication counts.
• Funders — POST /v1/publications/funders — who funds the research.
• Collaborating Organizations — POST /v1/publications/collaborating-organizations — co-authoring institutions, ranked by shared publications.
• Top Cited Works — POST /v1/publications/top-cited-works — the company's most-cited publications, paginated.

---

Risk Assessment

Counterparty due diligence. Like trade data, a two-step flow.

1. Candidates — POST /v1/risk-assessment/candidates — resolves a company ID to the candidates used by the endpoints below. Free of charge.
2. Financials — POST /v1/risk-assessment/financials — year-by-year turnover, EBITDA, total assets, employee numbers, and other metrics.
3. Ownership — POST /v1/risk-assessment/ownership — shareholders and the hierarchical corporate ownership structure.
4. Risk Report — POST /v1/risk-assessment/report — per-category analysis with a low/medium/high rating for geopolitical exposure, sanctions & legal, financial health, regulatory & ethics, data privacy & cyber, and ownership & governance, returned alongside the company's registration details.

---

People Search

Account-specific contact data, SMTP-validated and GDPR compliant.

• People Search — POST /v1/people/search
  Employees at up to 25 company IDs and 25 URLs per request, filtered by seniority, department, the person's country, or job-title and experience keywords. Also refreshes existing person records.

• Get Verified Emails — POST /v1/people/verified-email
  A verified email for a person ID from People Search. Expected bounce rate under 3%.

---

Credits, Tiers, and Limits

• Credits — there are two balances: data credits for search, data, and insight endpoints, and enrichment credits for company enrichment. Cost varies per endpoint (flat, per returned result, or per page). Credits are charged only after the work succeeds, so an endpoint that returns 204 No Content costs nothing.
• Access tiers — your token carries one or more tiers. Company data and text search sit in the base tier; enrichment, trade data, patents, publications, and risk assessment require the higher tier.
• Rate limits — 10 requests/second per token on status, profiles, events, enrichment, people/search, people/verified-email, credit-usage and the trade-data and risk-assessment candidates endpoints; 1 request/second on every other endpoint. Exceeding a limit returns 429.
• Concurrent requests — at most 5 requests per token can run at the same time, across all endpoints. A 6th returns 429 with Retry-After: 1; send it again once one of the running requests finishes.

Errors

Every error response has a detail field. For most errors it is a message:

{ "detail": "Insufficient data credits: this request needs at least 10, your balance is 4. For an upgrade, contact us at api@milda.ai." }

Validation errors (422) return a list instead, one entry per problem, with the field's path in loc:

{ "detail": [{ "type": "missing", "loc": ["body", "company_id"], "msg": "Field required", "input": {} }] }

Status	Meaning
204	No data available for this input — nothing charged.
400	The request is valid JSON but cannot be served, e.g. a page_no out of range or a keyword with unbalanced brackets.
401	Token missing, unknown, disabled, or expired.
403	Your plan does not include the endpoint, or insufficient credits.
404	The company is not known to Milda.
422	Request body failed validation; detail lists the offending fields.
429	Rate limit or concurrent-request limit exceeded.
500	Something went wrong on our side. Retry; if it persists, contact support with the reference in detail.
502	Milda's data service could not complete the request. Retry in a moment.
504	Milda's data service took too long to answer. Retry in a moment.

Questions, upgrades, or a raised limit: api@milda.ai.