> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trywildcard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript

> JavaScript/Node.js examples for the Wildcard API

# JavaScript Examples

## Setup

```javascript theme={null}
const API_KEY = "mk_live_your_key_here";
const BASE_URL = "https://api-v1.maverickintelligence.co";

async function apiRequest(path, params = {}) {
  const url = new URL(`${BASE_URL}${path}`);
  Object.entries(params).forEach(([key, value]) => {
    if (value !== undefined) url.searchParams.set(key, value);
  });

  const response = await fetch(url, {
    headers: { "X-API-Key": API_KEY },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message || `HTTP ${response.status}`);
  }

  return response.json();
}
```

## List all people (with pagination)

```javascript theme={null}
async function getAllPeople() {
  const people = [];
  let cursor = undefined;

  while (true) {
    const data = await apiRequest("/v1/people", { limit: 100, cursor });
    people.push(...data.data);

    cursor = data.pagination.nextCursor;
    if (!cursor) break;
  }

  return people;
}

const people = await getAllPeople();
console.log(`Total people: ${people.length}`);
```

## Get hot leads

```javascript theme={null}
const { data: hotLeads } = await apiRequest("/v1/people", {
  hot_leads_only: "true",
  limit: 50,
});

hotLeads.forEach((lead) => {
  console.log(`${lead.firstName} ${lead.lastName} - ${lead.company}`);
});
```

## Get recent visitors

```javascript theme={null}
const yesterday = new Date(Date.now() - 86400000).toISOString();

const { data: recent } = await apiRequest("/v1/people", {
  since: yesterday,
});

console.log(`People seen since yesterday: ${recent.length}`);
```

## Who was identified in a time window

```javascript theme={null}
async function identifiedBetween(start, end) {
  const people = new Map(); // a person can appear on two pages
  let cursor = undefined;

  while (true) {
    const data = await apiRequest("/v1/people", {
      visited_since: start,
      visited_until: end,
      include_page_views: "true",
      limit: 250,
      cursor,
    });
    data.data.forEach((person) => people.set(person.id, person));

    cursor = data.pagination.nextCursor;
    if (!cursor) return [...people.values()];
  }
}

const identified = await identifiedBetween("2026-11-18T16:00:00Z", "2026-11-18T17:00:00Z");
identified.forEach((person) => {
  const pages = person.pageViews.map((view) => view.url).join(", ");
  console.log(`${person.firstName} ${person.lastName} (${person.company}): ${pages}`);
});
```

## Get a person's events

```javascript theme={null}
const personId = "abc123";
const result = await apiRequest(`/v1/people/${personId}/events`, {
  limit: 100,
});

// Person summary included — no second API call needed
const { person, data: events } = result;
console.log(`Events for ${person.firstName} ${person.lastName} (${person.company})`);

events.forEach((event) => {
  console.log(`  ${event.timestamp} - ${event.eventType} - ${event.url}`);
});
```

## Access classified emails, phone, and attribution

```javascript theme={null}
const { data: people } = await apiRequest("/v1/people", { limit: 50 });

people.forEach((person) => {
  // Classified emails
  console.log(`Business: ${person.businessEmail}`);
  console.log(`Personal: ${person.personalEmail}`);
  // Best phone (DNC-filtered, matches dashboard)
  console.log(`Phone: ${person.phone}`);
  // Traffic attribution
  console.log(`Source: ${person.trafficType}, Platform: ${person.adPlatform}`);
});
```

## Skip undeliverable emails

```javascript theme={null}
// Only people with a deliverable or catch-all address, with any address
// confirmed undeliverable blanked out.
const { data: people } = await apiRequest("/v1/people", {
  email_status: "valid,catch-all",
  exclude_bad_emails: "true",
});

people.forEach((person) => {
  // emailStatus summarises the address you would actually contact.
  console.log(`${person.email} -> ${person.emailStatus}`);

  // emailVerification has the per-address detail behind that summary.
  Object.entries(person.emailVerification).forEach(([address, check]) => {
    console.log(
      check.checkedAt === null
        ? `  ${address}: never verified`
        : `  ${address}: ${check.status} (checked ${check.checkedAt})`,
    );
  });
});
```

Statuses are read from the verification cache that verified exports populate —
calling the API never spends a ZeroBounce credit. An address that no export has
covered reports `status: "unknown"` with a null `checkedAt`, and is always kept
rather than filtered away.

## Get dashboard stats

```javascript theme={null}
const { data: stats } = await apiRequest("/v1/stats");

console.log(`Total people: ${stats.totalPeople}`);
console.log(`Total companies: ${stats.totalCompanies}`);
console.log(`Events (30d): ${stats.recentEvents}`);
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.