Fetch

Endpoint: `POST /prospects`

Purpose:

Retrieves a list of prospect records based on filtering criteria such as job level, department, or geography.

Modes: full.

Request Schema:

Field	Type	Description
mode	String	`full`
size	Number	Max number of returned results - up to 1000
page_size	Number	Max number of records per page - up to 100
page	Number	Page number to retrieve
filters	Object	Filter object (see Filters Object below)

Filters Object

Filters are provided in the request body inside the "filters" key. Each filter has:

type: the filter type (e.g., includes, exists, range, any_match).
values or value: the value(s) to filter by.

Example:

"filters": {
  "country_code": {
    "type": "includes",
    "values": ["us", "ca"]
  },
  "company_size": {
    "type": "includes",
    "values": ["11-50", "51-200"]
  }
}

Pagination Parameters:

Data fetching supports pagination.
Use the following parameters to control pagination:

Field	Type	Description
`size`	Number	Maximum number of results to return (up to 1000)
`page_size`	Number	Maximum number of records per page (up to 100)
`page`	Number	Page number to retrieve

Mode Parameter:

The fetch endpoints support a mode to define how much data to return:

Value	Description
`full`	Returns all available data for businesses

Example Request (Python):

"filters": {
  "country_code": {
    "type": "includes",
    "values": ["us", "ca"]
  },
  "company_size": {
    "type": "includes",
    "values": ["11-50", "51-200"]
  }
}

Prospect Filters:

Parameter	Description
`has_email`	Filters only prospects that have an email.
`has_phone_number`	Filters only prospects that have a phone number.
`job_level`	Filters by job level. Options: `director`, `manager`, `vp`, `partner`, `cxo`, `non-managerial`, `senior`, `entry`, `training`, `unpaid`.
`job_department`	Filters by job department. Options: `customer service`, `design`, `education`, `engineering`, `finance`, `general`, `health`, `human resources`, `legal`, `marketing`, `media`, `operations`, `public relations`, `real estate`, `sales`, `trades`, `unknown`.
`explorium_id`	Filters prospects from specified businesses.
`total_experience_months`	Selects a range of experience months (range filter).
`current_role_months`	Filters by experience in the current role (range filter).

Example Request (cURL):

curl -X POST \
  "https://api.explorium.ai/v1/prospects" \
  -H "API_KEY: 3cfe2c5554576ea5e31a902191a8dd02" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "full",
    "size": 10000,	
    "page_size": 1,
    "filters": {
      "job_level": {
        "type": "includes",
        "values": ["director", "manager"]
      },
      "has_email": {
        "type": "exists",
        "value": true
      }
    }
  }'

Example Examples : Mode = full:

{
  "response_context": {
    "correlation_id": "d598bda5cb12403180079bcfd32a2cdc",
    "request_status": "success",
    "time_took_in_seconds": 1.208
  },
  "total_results": 1,
  "data": [
    {
      "prospect_id": "4bab3da2f81d8e2e9f9b393313358be70dee1d5e",
      "full_name": "Wajid Mehmood",
      "country_name": "pakistan",
      "region_name": "punjab",
      "city": "rawalpindi",
      "linkedin": "linkedin.com/in/wajid-mehmood-1599017b",
      "experience": "Assistant manager human resources",
      "skills": null,
      "interests": null,
      "company_name": "Kohinoor textile mills kohinoor maple leaf group",
      "company_website": "kmlg.com",
      "company_linkedin": "linkedin.com/company/kohinoor-textile-mills-ltd-",
      "job_department": "Human resources",
      "job_seniority_level": [
        "manager"
      ],
      "job_title": "Assistant manager human resources"
    }
  ]
}

Mode = full: Returns additional attributes such as job history, social links, etc.

Endpoint: POST /prospects