Docs · API reference

Search companies

Search for companies by industry, headcount and country, and get back each one's name, domain, industry and size. To look up one company, use GET /companies/lookup with its domain, name or url.

Preview: may change before launch · Updated 1 November 2026

Preview

This is how the API is planned to work. Names and fields may change before launch. The APIs are in early access: join early access to get a key when they're ready.

POST https://api.magpie-cloud.com/v1/companies/search. What it's for, and how it works: Company search API.

Request

A JSON body, with your API key in the Authorization header (see Authentication).

Field	Type	Required	What it is
`industries`	string[]	No	Industry names, from `GET /reference/industries`. Give this or `headcount`.
`headcount`	object	No	`min` and `max` employees. Give this or `industries`.
`countries`	string[]	No	Two-letter codes, such as `GB`, from `GET /reference/countries`.
`limit`	integer	No	Companies a page, from 1 to 100. 25 if left out.
`cursor`	string	No	The `next` value from the page before. Leave it out for the first page.

Example

Request · POST /companies/search

curl https://api.magpie-cloud.com/v1/companies/search \
  -H "Authorization: Bearer $MAGPIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "industries": ["Truck Transportation"],
    "headcount": { "min": 50, "max": 500 },
    "countries": ["GB"],
    "limit": 25
  }'

const res = await fetch("https://api.magpie-cloud.com/v1/companies/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAGPIE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    industries: ["Truck Transportation"],
    headcount: { min: 50, max: 500 },
    countries: ["GB"],
    limit: 25,
  }),
});
const data = await res.json();

import os
import requests

res = requests.post(
    "https://api.magpie-cloud.com/v1/companies/search",
    json={
        "industries": ["Truck Transportation"],
        "headcount": {"min": 50, "max": 500},
        "countries": ["GB"],
        "limit": 25,
    },
    headers={"Authorization": f"Bearer {os.environ['MAGPIE_API_KEY']}"},
    timeout=90,
)
data = res.json()

Response · 200

{
  "companies": [
    {
      "name": "Example Freight Ltd",
      "domain": "examplefreight.example",
      "company_url": "https://profiles.example/company/example-freight",
      "industry": "Truck Transportation",
      "headcount": "51-200",
      "employees": 140,
      "hq": "Leeds",
      "country": "GB"
    }
  ],
  "next": "cur_25",
  "total": 240,
  "coverage": "full"
}

Response

Field	Type	What it is
`companies[].name`	string	The company's name.
`companies[].domain`	string or null	Its website domain.
`companies[].company_url`	string or null	Its public company page.
`companies[].industry`	string or null	Its industry.
`companies[].headcount`	string or null	Its headcount band, such as `51-200`.
`companies[].employees`	integer or null	Its exact headcount, when known.
`companies[].hq`	string or null	Where its head office is.
`companies[].country`	string or null	Two-letter code.
`next`	string or null	Send it back as `cursor` for the next page; `null` on the last page.
`total`	integer	How many companies match.
`coverage`	string	`full`, or `partial` when we hold few companies for this filter and are finding more.

Errors

Errors come back as JSON with a code and a message. See Errors for the shape, and when to try again.

Status	Code	When
`400`	`invalid_request`	Neither `industries` nor `headcount` was given, or a filter isn't valid.
`401`	`unauthorized`	The API key is missing, wrong or revoked.
`402`	`out_of_credits`	Your credits have run out.
`429`	`rate_limited`	Too many requests. Wait the number of seconds in the `Retry-After` header, then try again.
`5xx`	Varies	Something went wrong on our side. Safe to try again after a short wait.

Billing

The planned price is 1 credit (£0.004$0.006) for each company returned. It may change before launch.

See Credits and prices for how credits work.

Notes

There's no keyword search: the filters above are what we can search by.
The country filter goes by what a company's page says about its head office, so it's close rather than exact.
Companies come back without people or emails.

Questions about the APIs? Email pele@magpiecrm.com.