Prospects research

Research Prospects

curl --request POST \
  --url https://api.explorium.ai/v2/prospects/research/enrich \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "parameters": {
    "query": "<string>",
    "prompt_template": "<string>"
  },
  "prospects": [
    {
      "prospect_id": "<string>",
      "custom_fields": {}
    }
  ],
  "request_context": null
}
'

import requests

url = "https://api.explorium.ai/v2/prospects/research/enrich"

payload = {
    "parameters": {
        "query": "<string>",
        "prompt_template": "<string>"
    },
    "prospects": [
        {
            "prospect_id": "<string>",
            "custom_fields": {}
        }
    ],
    "request_context": None
}
headers = {
    "api_key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {api_key: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    parameters: {query: '<string>', prompt_template: '<string>'},
    prospects: [{prospect_id: '<string>', custom_fields: {}}],
    request_context: null
  })
};

fetch('https://api.explorium.ai/v2/prospects/research/enrich', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.explorium.ai/v2/prospects/research/enrich",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'parameters' => [
        'query' => '<string>',
        'prompt_template' => '<string>'
    ],
    'prospects' => [
        [
                'prospect_id' => '<string>',
                'custom_fields' => [
                                
                ]
        ]
    ],
    'request_context' => null
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "api_key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.explorium.ai/v2/prospects/research/enrich"

	payload := strings.NewReader("{\n  \"parameters\": {\n    \"query\": \"<string>\",\n    \"prompt_template\": \"<string>\"\n  },\n  \"prospects\": [\n    {\n      \"prospect_id\": \"<string>\",\n      \"custom_fields\": {}\n    }\n  ],\n  \"request_context\": null\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api_key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.explorium.ai/v2/prospects/research/enrich")
  .header("api_key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"parameters\": {\n    \"query\": \"<string>\",\n    \"prompt_template\": \"<string>\"\n  },\n  \"prospects\": [\n    {\n      \"prospect_id\": \"<string>\",\n      \"custom_fields\": {}\n    }\n  ],\n  \"request_context\": null\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.explorium.ai/v2/prospects/research/enrich")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api_key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"parameters\": {\n    \"query\": \"<string>\",\n    \"prompt_template\": \"<string>\"\n  },\n  \"prospects\": [\n    {\n      \"prospect_id\": \"<string>\",\n      \"custom_fields\": {}\n    }\n  ],\n  \"request_context\": null\n}"

response = http.request(request)
puts response.read_body

{
  "response_context": {
    "correlation_id": "<string>",
    "request_status": "success",
    "time_taken_in_seconds": 123
  },
  "data": [
    {
      "prospect_id": "<string>",
      "data": {
        "research_result": "<unknown>"
      }
    }
  ],
  "total_results": 123,
  "generated_prompt": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

POST

prospects

research

enrich

Research Prospects

curl --request POST \
  --url https://api.explorium.ai/v2/prospects/research/enrich \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "parameters": {
    "query": "<string>",
    "prompt_template": "<string>"
  },
  "prospects": [
    {
      "prospect_id": "<string>",
      "custom_fields": {}
    }
  ],
  "request_context": null
}
'

import requests

url = "https://api.explorium.ai/v2/prospects/research/enrich"

payload = {
    "parameters": {
        "query": "<string>",
        "prompt_template": "<string>"
    },
    "prospects": [
        {
            "prospect_id": "<string>",
            "custom_fields": {}
        }
    ],
    "request_context": None
}
headers = {
    "api_key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {api_key: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    parameters: {query: '<string>', prompt_template: '<string>'},
    prospects: [{prospect_id: '<string>', custom_fields: {}}],
    request_context: null
  })
};

fetch('https://api.explorium.ai/v2/prospects/research/enrich', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.explorium.ai/v2/prospects/research/enrich",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'parameters' => [
        'query' => '<string>',
        'prompt_template' => '<string>'
    ],
    'prospects' => [
        [
                'prospect_id' => '<string>',
                'custom_fields' => [
                                
                ]
        ]
    ],
    'request_context' => null
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "api_key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.explorium.ai/v2/prospects/research/enrich"

	payload := strings.NewReader("{\n  \"parameters\": {\n    \"query\": \"<string>\",\n    \"prompt_template\": \"<string>\"\n  },\n  \"prospects\": [\n    {\n      \"prospect_id\": \"<string>\",\n      \"custom_fields\": {}\n    }\n  ],\n  \"request_context\": null\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api_key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.explorium.ai/v2/prospects/research/enrich")
  .header("api_key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"parameters\": {\n    \"query\": \"<string>\",\n    \"prompt_template\": \"<string>\"\n  },\n  \"prospects\": [\n    {\n      \"prospect_id\": \"<string>\",\n      \"custom_fields\": {}\n    }\n  ],\n  \"request_context\": null\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.explorium.ai/v2/prospects/research/enrich")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api_key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"parameters\": {\n    \"query\": \"<string>\",\n    \"prompt_template\": \"<string>\"\n  },\n  \"prospects\": [\n    {\n      \"prospect_id\": \"<string>\",\n      \"custom_fields\": {}\n    }\n  ],\n  \"request_context\": null\n}"

response = http.request(request)
puts response.read_body

{
  "response_context": {
    "correlation_id": "<string>",
    "request_status": "success",
    "time_taken_in_seconds": 123
  },
  "data": [
    {
      "prospect_id": "<string>",
      "data": {
        "research_result": "<unknown>"
      }
    }
  ],
  "total_results": 123,
  "generated_prompt": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Run a custom, AI-powered research task over a list of prospects. Describe the task as a natural-language query or a prompt_template, define the result shape with an output_schema, and the engine returns structured JSON for each person.

How Research works — query vs prompt_template, the record context, real-time web research and its functions, credit usage, and error handling — is documented once on the Research (GenAI) overview. This page covers what is specific to the prospects endpoint.

Record fields

Reference any of these with {{ record['field_name'] }} in a prompt_template. When you pass a query instead, the same fields are made available to the prompt generator as the entity’s context.

Field	Description
`full_name`	The prospect’s full name.
`job_title`	The prospect’s current job title.
`job_title_level`	The seniority level of the prospect’s role (e.g. Manager, Director, VP, C-Suite).
`job_department`	The department or function the prospect works in (e.g. Sales, Engineering).
`summary`	A short professional summary or bio for the prospect. Truncated at 1,000 characters.
`organization_name`	The name of the company the prospect currently works at.
`url`	The website URL of the prospect’s current company.
`job_company_industry`	The industry of the prospect’s current company.
`job_company_size`	The employee-size range of the prospect’s current company.
`job_company_description`	A description of the prospect’s current company. Truncated at 500 characters.
`location_name`	The prospect’s location — city, region, and/or country.
`linkedin_url`	The URL of the prospect’s LinkedIn profile.
`skills`	The prospect’s listed skills.
`education`	The prospect’s education history. Truncated at 1,000 characters.
`experience`	The prospect’s work experience history. Truncated at 1,000 characters.

Custom fields

Any key you attach in custom_fields is merged into the same record object and can be referenced exactly like a profile field — for example {{ record['campaign_name'] }}. There is no fixed list: use whatever keys you send per entity. Values are treated as strings.

Record fields are populated from the entity’s resolved Explorium profile, so a given field may be empty when that attribute isn’t available for the entity. Write prompts that degrade gracefully when a field is missing, and instruct the model to use web research to fill gaps where appropriate.

Request

The request body has two top-level keys:

prospects — the list of entities to research. Each item has a prospect_id and may include an optional custom_fields object.
parameters — controls how the analysis is generated and what shape the result takes. Identical on both endpoints; see the overview.

object[]

required

The list of entities to research. Each entity is processed independently, and results are returned in the same order.

Show entity object

string

required

The Explorium identifier to research. Obtain IDs from Match Prospects or Fetch Prospects.

object

Optional key–value pairs to attach to this entity. Each key is merged into the record context and can be referenced from a prompt_template (e.g. {{ record['campaign_name'] }}).

object

required

Provide either query or prompt_template, never both and never neither — see query vs prompt_template. output_schema is required with prompt_template and optional with query.

Examples

{
  "prospects": [
    {
      "prospect_id": "ee936e451b50c70e068e1b54e106cb89173198c4",
      "custom_fields": { "campaign_name": "Q1 enterprise push" }
    }
  ],
  "parameters": {
    "prompt_template": "Write a one-line personalized opener for {{ record['full_name'] }}, {{ record['job_title'] }} at {{ record['organization_name'] }}, for campaign {{ record['campaign_name'] }}.",
    "output_schema": {
      "type": "object",
      "properties": {
        "opener": { "type": "string", "description": "One-line personalized outreach opener" },
        "angle": { "type": "string", "description": "The hook or angle the opener leans on" }
      },
      "required": ["opener", "angle"]
    }
  }
}

{
  "prospects": [
    { "prospect_id": "ee936e451b50c70e068e1b54e106cb89173198c4" }
  ],
  "parameters": {
    "query": "Based on this person's role and company, assess whether they are likely a decision-maker for purchasing sales software. Explain your reasoning.",
    "output_schema": {
      "type": "object",
      "properties": {
        "decision_maker": { "type": "string", "enum": ["Yes", "No", "Influencer"], "description": "Whether the prospect is a decision-maker, a non-decision-maker, or an influencer" },
        "reasoning": { "type": "string", "description": "Brief explanation for the assessment" }
      },
      "required": ["decision_maker", "reasoning"]
    }
  }
}

Example request (cURL)

curl --request POST \
  --url https://api.explorium.ai/v2/prospects/research/enrich \
  --header 'accept: application/json' \
  --header 'api_key: your_api_key_here' \
  --header 'content-type: application/json' \
  --data '{
    "prospects": [
      { "prospect_id": "ee936e451b50c70e068e1b54e106cb89173198c4" }
    ],
    "parameters": {
      "query": "Assess whether this person is likely a decision-maker for purchasing sales software. Explain your reasoning.",
      "output_schema": {
        "type": "object",
        "properties": {
          "decision_maker": { "type": "string", "enum": ["Yes", "No", "Influencer"], "description": "Whether the prospect is a decision-maker, a non-decision-maker, or an influencer" },
          "reasoning": { "type": "string", "description": "Brief explanation for the assessment" }
        },
        "required": ["decision_maker", "reasoning"]
      }
    }
  }'

Response

A successful request returns a 200 with a data array — one entry per input entity, in input order — plus a total_results count. Each successful result contains the prospect_id and the generated fields defined by the output_schema. Rows that fail carry an _error field instead of the generated fields, rather than being dropped.

object[]

One result per input entity, in input order.

Show result object

string

The identifier this result corresponds to.

varies

The generated fields, conforming to the output_schema — the one supplied in the request, or the auto-generated one when using query without a schema.

string

Present only when the row failed. Describes the failure; the generated fields are omitted for this row.

integer

The total number of results returned in data.

Example response

{
  "data": [
    {
      "prospect_id": "ee936e451b50c70e068e1b54e106cb89173198c4",
      "decision_maker": "Yes",
      "reasoning": "Their title indicates ownership of the sales function, with budget authority over tooling."
    }
  ],
  "total_results": 1
}

Example failed row

{
  "prospect_id": "f12c9a77b0e34d51a9c0b8e2d7f4a6c3",
  "_error": "Unable to resolve a profile for this identifier."
}

Researching businesses instead

This endpoint researches prospects and exposes the prospect record fields above. To research businesses — with businesse fields such as organization_name, revenue_range, and full_tech_stack — use Businesses research. For lists larger than a single request, use the asynchronous variant.

Authorizations

api_key

string

header

required

Body

application/json

parameters

GenAIResearchParams · object

required

Show child attributes

prospects

V2ProspectResearchInput · object

required

V2ProspectResearchInput · object[]
V2ProspectResearchInput · object

Show child attributes

request_context

Request Context · object | null

Example:

null

Response

Successful Response

This is base response model for all responses in partner service.

response_context

V2ResponseContext · object

required

Show child attributes

data

V2ProspectEnrichRow[GenAIResearchOutputSchema] · object[]

required

Show child attributes

total_results

integer

required

generated_prompt

string

Getting started

Businesses

Business enrichments

Prospects

Prospect enrichments

Research (GenAI)

Async jobs

Autocomplete

Credits

Events & Webhooks

Record fields

Custom fields

Request

Examples

Example request (cURL)

Response

Example response

Example failed row

Researching businesses instead

Authorizations

Body

Response

​Record fields

​Custom fields

​Request

​Examples

​Example request (cURL)

​Response

​Example response

​Example failed row

​Researching businesses instead

Authorizations

Body

Response

Record fields

Custom fields

Request

Examples

Example request (cURL)

Response

Example response

Example failed row

Researching businesses instead