> ## 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.

# Python

> Python examples for the Wildcard API

# Python Examples

## Setup

```python theme={null}
import requests

API_KEY = "mk_live_your_key_here"
BASE_URL = "https://api-v1.maverickintelligence.co"
HEADERS = {"X-API-Key": API_KEY}
```

## List all people (with pagination)

```python theme={null}
def get_all_people():
    """Fetch all people by paginating through all pages."""
    people = []
    cursor = None

    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor

        response = requests.get(
            f"{BASE_URL}/v1/people",
            headers=HEADERS,
            params=params,
        )
        response.raise_for_status()
        data = response.json()

        people.extend(data["data"])

        cursor = data["pagination"].get("nextCursor")
        if not cursor:
            break

    return people

people = get_all_people()
print(f"Total people: {len(people)}")
```

## Get hot leads only

```python theme={null}
response = requests.get(
    f"{BASE_URL}/v1/people",
    headers=HEADERS,
    params={"hot_leads_only": "true", "limit": 50},
)
hot_leads = response.json()["data"]

for lead in hot_leads:
    print(f"{lead['firstName']} {lead['lastName']} - {lead['company']}")
```

## Get people seen since yesterday

```python theme={null}
from datetime import datetime, timedelta

yesterday = (datetime.utcnow() - timedelta(days=1)).isoformat() + "Z"

response = requests.get(
    f"{BASE_URL}/v1/people",
    headers=HEADERS,
    params={"since": yesterday},
)
recent = response.json()["data"]
print(f"People seen since yesterday: {len(recent)}")
```

## Who was identified in a time window

```python theme={null}
def identified_between(start, end):
    """People identified between start and end (ISO 8601, with timezone),
    each with the pages they viewed in that window."""
    people = {}
    params = {"visited_since": start, "visited_until": end,
              "include_page_views": "true", "limit": 250}
    while True:
        response = requests.get(f"{BASE_URL}/v1/people", headers=HEADERS, params=params)
        response.raise_for_status()
        data = response.json()
        for person in data["data"]:
            people[person["id"]] = person  # a person can appear on two pages
        cursor = data["pagination"].get("nextCursor")
        if not cursor:
            return list(people.values())
        params["cursor"] = cursor

for person in identified_between("2026-11-18T16:00:00Z", "2026-11-18T17:00:00Z"):
    pages = ", ".join(view["url"] for view in person["pageViews"])
    print(f"{person['firstName']} {person['lastName']} ({person['company']}): {pages}")
```

## Get a person's events

```python theme={null}
person_id = "abc123"
response = requests.get(
    f"{BASE_URL}/v1/people/{person_id}/events",
    headers=HEADERS,
    params={"limit": 100},
)
result = response.json()

# Person summary is included at the top level
person = result["person"]
print(f"Events for {person['firstName']} {person['lastName']}")

for event in result["data"]:
    print(f"  {event['timestamp']} - {event['eventType']} - {event['url']}")
```

## Access classified emails and phone

```python theme={null}
people = get_all_people()

for person in people:
    # Best business email (company-domain match preferred)
    biz = person.get("businessEmail")
    # Best personal email (gmail > outlook > yahoo)
    personal = person.get("personalEmail")
    # Best phone number (DNC-filtered, matches dashboard display)
    phone = person.get("phone")
    # Traffic attribution
    source = person.get("trafficType")  # organic, paid, direct, referral
    platform = person.get("adPlatform")  # google, facebook, linkedin (if paid)

    print(f"{person['firstName']} {person['lastName']}")
    print(f"  Business: {biz}, Personal: {personal}, Phone: {phone}")
    if source == "paid":
        print(f"  Came from {platform} ad")
```

## Skip undeliverable emails

```python theme={null}
# Ask the API to do the filtering: only people with a deliverable or
# catch-all address, and blank any address confirmed undeliverable.
response = requests.get(
    "https://api-v1.maverickintelligence.co/v1/people",
    headers={"X-API-Key": API_KEY},
    params={"email_status": "valid,catch-all", "exclude_bad_emails": "true"},
)

for person in response.json()["data"]:
    # emailStatus summarises the address you would actually contact.
    print(f"{person['email']} -> {person['emailStatus']}")

    # emailVerification has the per-address detail behind that summary.
    for address, check in person["emailVerification"].items():
        if check["checkedAt"] is None:
            print(f"  {address}: never verified")
        else:
            print(f"  {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 person events with context

```python theme={null}
person_id = "abc123"
response = requests.get(
    f"{BASE_URL}/v1/people/{person_id}/events",
    headers=HEADERS,
    params={"limit": 100},
)
result = response.json()

# Person summary included — no second API call needed
person = result["person"]
print(f"Events for {person['firstName']} {person['lastName']} ({person['company']})")

for event in result["data"]:
    print(f"  {event['timestamp']} - {event['eventType']} - {event['url']}")
```

## Get dashboard stats

```python theme={null}
response = requests.get(f"{BASE_URL}/v1/stats", headers=HEADERS)
stats = response.json()["data"]

print(f"Total people: {stats['totalPeople']}")
print(f"Total companies: {stats['totalCompanies']}")
print(f"Events (30d): {stats['recentEvents']}")
```


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