1. Input: Provide filters such as job level, department, or industry to refine prospect search.
2. Processing: The system scans and retrieves relevant prospect records.
3. Output: A structured response containing matched prospect data.

Data Fetching: Pagination, Filtering & Modes

The API supports flexible data fetching through pagination, filtering, and optional modes to customize the amount and structure of the returned data.

Pagination

To efficiently retrieve large datasets, use the following parameters to paginate the results:

Behavior Notes:

• If size is smaller than page_size * page, the last page may contain fewer records or be empty.
• If pagination parameters are omitted, the API may return a default page size (implementation-specific).

Filtering

Filters allow you to narrow down results based on specific field values.
All filters must be included in the request body under the "filters" key, as a JSON object.

Each filter field accepts:

• value: for a single filter value (e.g. "value": "true")
• values: for multiple possible matches (e.g. "values": ["director", "manager"])

Example Request Body:

{
  "filters": {
    "job_level": {
      "values": ["director", "manager"]
    },
    "has_email": {
      "value": "true"
    }
  }
}

Filter Matching Logic:

• Fields using value are matched exactly.
• Fields using values are matched using an OR condition.
• Filters are combined using an AND across different fields.

Mode Parameter

The optional mode parameter defines the level of detail in the returned data.

Best Practices

• Always use page_size to control payload size for better performance.
• Use size to set an upper limit and avoid unintentionally requesting large datasets.
• Apply filters whenever possible to reduce response size and processing time.
• Avoid using mode=full unless full object data is necessary—especially in high-volume requests.

Prospects Filter Reference

🎯 Prospecting HR Directors at Healthcare Companies in Texas for Payroll Software

🔍 Use Case:

A payroll software provider wants to sell to HR directors at mid-sized healthcare organizations in Texas who handle payroll compliance and workforce management.

📌 Filters:

• Company Country Code: ["us"]
• Company Region (State Code): ["us-tx"]
• Company Size: ["501-1000"]
• Company Revenue: ["75M-200M"]
• NAICS Category: ["62"] (Healthcare & Social Assistance)
• Job Level: ["director", "manager", "vp"]
• Job Department: ["human resources"]
• Has Email: ["True"]

🎯 Targeting CFOs of Investment Banks in New York for Financial Compliance Software

🔍 Use Case:

A regulatory compliance software provider wants to reach out to CFOs at mid-sized investment banks in New York who have been in their role for over two years and are likely leading compliance initiatives.

📌 Filters:

• Company Country Code: ["us"]
• Company Region (State Code): ["us-ny"]
• Company Size: ["1001-5000"]
• Company Revenue: ["500M-1B"]
• LinkedIn Category: ["investment banking"]
• Job Department: ["finance"]
• Job Level: ["CXO"]
• Has Email: ["True"]
• Has Phone Number: ["True"]

curl -X POST \
  "https://api.explorium.ai/v1/prospects" \
  -H "API_KEY: <your api key>" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "full",
  "size": 100,
  "page_size": 100,
  "page": 1,
  "filters": {
    "business_id": {
      "values": [
        "8adce3ca1cef0c986b22310e369a0793"
      ]
    },
    "job_level": {
      "values": [
        "director",
        "manager"
      ]
    },
    "has_email": {
      "value": true
    },
    "total_experience_months": {
      "gte": 3,
      "lte": 6
    }
  }
}'

📌 Mode full: Returns additional attributes such as job history, social links, and experience.

{
  "response_context": {
    "correlation_id": "d46aa78f3da148e7846fa94492f8f80a",
    "request_status": "success",
    "time_took_in_seconds": 1.252
  },
  "data": [
    {
      "prospect_id": "ba32fc15ccaccac027f9f9f1c3116a3333469443",
      "full_name": "Brandon Kuchta",
      "country_name": "united states",
      "region_name": "california",
      "city": "alamo",
      "linkedin": "linkedin.com/in/bkuchta",
      "experience": "Acd, design manager, product art direction",
      "skills": "3d animation, 3d rendering, After effects, Art direction, Color correction, Color grading, Color management, Compositing, Concept design, Content marketing, Creative direction, Davinci resolve, Digital compositing, Digital marketing, Ec2, Hdr, Image compositing, Image manipulation, Interactive advertising, Interactive media, Leadership, Lighting, Live action, Look development, Matte painting, Mobile design, Modeling, Modo, Motion design, Motion graphics, Nuke, Photographic lighting, Photography, Photoshop, Post production, Pre press, Product development, Product management, Rendering, Responsive design, Retouching, Team leadership, User experience, Vfx supervision, Visual effects",
      "interests": "Home improvement, Home decoration, Electronics",
      "company_name": "Apple",
      "company_website": "apple.com",
      "company_linkedin": "linkedin.com/company/apple",
      "job_department": "Marketing",
      "job_seniority_level": [
        "director"
      ],
      "job_title": "Art director"
    },
    ...
  ],
  "total_results": 5,
  "page": 1,
  "total_pages": 1
}

Best Practices

• Use refined filters to retrieve the most relevant prospects.
• Batch requests efficiently to optimize API performance.
• Monitor pagination settings to avoid missing data.
• Ensure data freshness by running regular queries to keep prospect information up-to-date.
• Be mindful of filter coverage – some filters may return fewer results due to lower data availability, while broader filters may yield larger result sets.