API reference / Research

Start a research brief

Written and maintained by The ProspectAPIs team

POST/v1/research

POST /v1/research is the ProspectAPIs operation submitResearch, in the Research group of the REST API. Start a cited research brief on one prospect. Accepts exactly one identifier (domain, website_url, company_name, company_linkedin_url, a work email or linkedin_url), or person_name with company_name. Returns 202 with a research_id at once; poll GET /v1/research/{id} until status is completed or failed. Charged at the research price only when the brief completes, and refunded if it fails. Answers 503 while research is not priced. Cost: $0.15 per completed brief, refunded on failure. Send your API key as a Bearer token in the Authorization header.

How this fits with the rest of the research API, with worked examples, is in the prospect research guide.

Parameters

This operation takes no path or query parameters.

Request body

JSON (ResearchRequest). Exactly one prospect identifier, or person_name with company_name. Unknown fields are refused. An email must be a work address (a free-mail domain is refused); URLs must be http(s) on a public host.

{
  "domain": "acme.com",
  "purpose": "pre_call",
  "context": "We sell route planning software for 3PLs"
}

Responses

Every error answers with the same JSON body, an error string and sometimes a code; the errors page lists each status and when it happens. A per-key 429 carries Retry-After; see rate limits.

202 response fields

The brief was accepted and is running. The body is a ResearchAccepted.

Code samples

Each sample sends the same request. Set PROSPECTAPIS_KEY in your environment first. Values come from the spec's examples; replace them with your own.

curl -X POST https://api.prospectapis.com/v1/research \
  -H "Authorization: Bearer $PROSPECTAPIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "acme.com", "purpose": "pre_call", "context": "We sell route planning software for 3PLs" }'

const res = await fetch("https://api.prospectapis.com/v1/research", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PROSPECTAPIS_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "domain": "acme.com",
    "purpose": "pre_call",
    "context": "We sell route planning software for 3PLs"
  }),
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json().catch(() => ({}))).error ?? res.statusText}`);
const data = await res.json();
console.log(data);

import os, requests

res = requests.post(
    "https://api.prospectapis.com/v1/research",
    headers={"Authorization": f"Bearer {os.environ['PROSPECTAPIS_KEY']}"},
    json={
        "domain": "acme.com",
        "purpose": "pre_call",
        "context": "We sell route planning software for 3PLs",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()
print(data)

Billing

A brief is held at the research price when you submit it, charged when it completes and refunded in full if it fails, so a failed brief costs nothing. Polling it with GET /v1/research/:id is free. The 202 response reports your balance after the hold in X-Credits-Remaining.

Related

The prospect research guide covers this area end to end. Previous operation: Read one funding round. Next operation: Poll a research brief. Every operation, grouped by area, is on the API reference index.

Create a free account to get a key, then run the samples above with your own values (this call acts for real, so use real inputs).