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

# cURL

> cURL examples for the Wildcard API

# cURL Examples

Replace `mk_live_your_key_here` with your actual API key in all examples.

## Health check (no auth needed)

```bash theme={null}
curl https://api-v1.maverickintelligence.co/v1/health
```

## List people

```bash theme={null}
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people?limit=10"
```

## Paginate through people

```bash theme={null}
# First page
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people?limit=50"

# Next page (use nextCursor from previous response)
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people?limit=50&cursor=eyJQSy..."
```

## Get hot leads only

```bash theme={null}
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people?hot_leads_only=true"
```

## Filter by date

```bash theme={null}
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people?since=2026-03-01"
```

## Who was identified in a time window

```bash theme={null}
# People identified on your sites between 16:00 and 17:00 UTC, with the pages they viewed
curl -G -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people" \
  --data-urlencode "visited_since=2026-11-18T16:00:00Z" \
  --data-urlencode "visited_until=2026-11-18T17:00:00Z" \
  --data-urlencode "include_page_views=true" \
  --data-urlencode "limit=250"
```

Follow `pagination.nextCursor` until it is absent, and deduplicate people by `id`.

## Filter by email deliverability

```bash theme={null}
# Only people with a verified-deliverable address
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people?email_status=valid"

# Deliverable or catch-all, with confirmed-bad addresses blanked out
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people?email_status=valid,catch-all&exclude_bad_emails=true"
```

Statuses come from the verification cache filled by verified exports. An address
no export has covered reads as `unknown` — reading the API never spends a
verification credit.

## Get a single person

```bash theme={null}
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people/abc123"
```

## Get person events (includes person summary)

```bash theme={null}
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people/abc123/events?limit=100"
```

The response includes a `person` object at the top level with the person's name, email, and company — no second API call needed.

## List companies

```bash theme={null}
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/companies?limit=50"
```

## Get a single company

```bash theme={null}
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/companies/xyz789"
```

## Get statistics

```bash theme={null}
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/stats"
```

## Check rate limit headers

```bash theme={null}
curl -v -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people?limit=1" 2>&1 | grep -i "x-ratelimit\|retry-after\|x-request-id"
```


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