Required permissions: body.target equals people: people:read; body.target equals companies: accounts:read. Other or missing values: no additional scopes; request validation still applies.

Search for companies and people you do not already have. It never writes: you get candidates, and you import the ones you want.

For explicit criteria, use mode: direct with filters. Reads stored company and people records with no sentence interpretation or external search. query is rejected. Each call returns one page of at most 100 records; follow nextCursor to continue. Company records without websites are kept and can be read again by filters.companyIds. A direct companies search can combine company criteria with filters.title to return companies with a matching current employee, once per company. People results include their matching current company. A company reaching perCompany sets truncated: true with a note because additional matching people may exist. Omitting mode preserves the usual search behavior below.

Say what you want in one of two ways, or both.

• query — a sentence. Trayo interprets it and ranks results by relevance. interpreted in the response tells you what it read out of the sentence, in the same filters shape you can send back. One ranked page of at most 50; no cursor.
• filters — exact attributes: industry, headcount, headquarters, funding stage, founded year, technologies, legal form, and for people a title. Applied exactly as sent, never interpreted, never fail-open: a company with no value for a filtered attribute is excluded. Paginated. A companies search without a title can use only country, founded year, technology or company type: it checks a bounded set of the largest companies and reports led_by_headcount, so its matches are not exhaustive. A people search or a company search with a title needs named companies or industries, hq.cities, hq.states, fundingStages or a headcount band. A funding stage selects a set on its own. Read GET /v1/find/industries before your first industry filter, because the values are a closed taxonomy.
• both — the sentence ranks, the filters decide. Rows Trayo cannot check are dropped.

target: people returns people with their current company. "founders at seed-stage software companies" is {"target": "people", "filters": {"industries": ["software development"], "fundingStages": ["seed"], "title": {"any": ["founder"]}}}. Company filters describe the employer; title describes the person. With a query, a people search takes title only.

Searching inside companies you already know. Name them instead of describing them: filters.companyWebsites takes their websites (["stripe.com", "https://www.acme.example"]), the form you already have without asking this API for anything. It replaces every other company filter, and takes no query beside it. (filters.companyIds, which takes an id a previous search returned, is the older form of the same thing and replaces it in turn; websites are what to reach for.) Each website resolves to at most one company, and resolvedWebsites in the response says which: several company profiles can share a domain, so a website resolves only to a profile whose name matches the domain; check it before trusting the page. A website that does not resolve is left out of the search and listed in unresolvedWebsites, never dropped without saying so: the page covers only the websites in resolvedWebsites. reason: "not_found" means no company on that domain: fix the spelling, send the company's own domain, or describe that company with filters in a separate search. reason: "uncertain" means the domain carries several possible companies and none clearly owns it; its alternatives list them (id, name, headcount). Show them to the user, or search again with filters.companyIds set to the right alternative's id. When no website resolves at all, the answer is a 404 company_not_found naming them.

Reading the response. data holds one row shape per target. hasMore/nextCursor page a filters-only search. truncated means more matched than this search can show — narrow, do not page deeper. known: false on a company means the sentence search found something Trayo does not hold. state: alreadyAdded means it is in your workspace; for "find N new companies", send filters.excludeWorkspace: true and those rows are left out, so the page fills with companies you do not have.

Before re-running a thin search, read interpreted, truncated and degraded. They say whether your criteria were enforced, whether the set is larger than reachable, and whether the search was incomplete — and a search that ran counts against the quota whether or not it was useful. Outside direct mode, every company row carries a url: rows with no website are dropped before the page is filled and counted in droppedUnaddressable, because POST /v1/accounts could not import them.

Importing. Companies: POST /v1/accounts/batch with {name, url} from each row (url is ready to send). People: POST /v1/people/batch with {fullName, title, linkedinUrl}; the company links by website when known. Contact details are a separate step: POST /v1/contacts/lookup with the linkedinUrl.

target: companies needs the accounts:read scope, target: people needs people:read. A search with a query draws on the workspace's search quota when it runs; a filters-only search does not.

{
  "target": "people",
  "filters": {
    "industries": [
      "software development"
    ],
    "hq": {
      "regions": [
        "europe"
      ]
    },
    "headcount": {
      "min": 10,
      "max": 200
    },
    "fundingStages": [
      "seed",
      "series_a"
    ],
    "foundedYear": {
      "min": 2019
    },
    "title": {
      "any": [
        "founder",
        "cto"
      ],
      "exclude": [
        "assistant"
      ]
    }
  },
  "perCompany": 2,
  "limit": 25
}