### Get API Statistics

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/curl.mdx

Retrieve general statistics about the API usage.

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

--------------------------------

### Python API Setup

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/python.mdx

Initializes the requests library, API key, base URL, and headers for making authenticated requests to the Maverick Intelligence API.

```python
import requests

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

--------------------------------

### Get a Single Company by ID

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/curl.mdx

Retrieve details for a specific company using its unique ID.

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

--------------------------------

### Get a Single Person by ID

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/curl.mdx

Retrieve details for a specific person using their unique ID.

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

--------------------------------

### Paginate Through API Results

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/introduction.mdx

Continue fetching subsequent pages of results by including the 'nextCursor' from the previous response in your request. This example shows how to use the cursor parameter.

```bash
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people?limit=10&cursor=eyJQSy..."
```

--------------------------------

### Debugging with X-Request-Id

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/errors.mdx

Include the X-Request-Id header in your support requests to help trace specific API calls. This example shows how to retrieve it from response headers.

```bash
curl -v -H "X-API-Key: mk_live_..." https://api-v1.maverickintelligence.co/v1/people

# Response headers:
# X-Request-Id: 550e8400-e29b-41d4-a716-446655440000
```

--------------------------------

### Paginate Through People Results

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/curl.mdx

Fetch paginated results for people. Use the 'cursor' parameter from the previous response to get the next page of results.

```bash
# 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 Person Events with Summary

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/curl.mdx

Retrieve events associated with a specific person. The response includes a 'person' object with their summary details.

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

--------------------------------

### Maverick Intelligence API Key Format

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/authentication.mdx

API keys start with 'mk_live_' followed by 40 hexadecimal characters. This is the standard format for all generated keys.

```text
mk_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0
```

--------------------------------

### GET /v1/companies/{id}

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/api-reference/get-company.mdx

Retrieves detailed information for a specific company by its ID.

```APIDOC
## GET /v1/companies/{id}

### Description
Returns details for a single identified company

### Method
GET

### Endpoint
/v1/companies/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the company.
```

--------------------------------

### GET /v1/health

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/api-reference/health.mdx

Check if the API is operational. No authentication required.

```APIDOC
## GET /v1/health

### Description
Check if the API is operational. No authentication required.

### Method
GET

### Endpoint
/v1/health
```

--------------------------------

### Get Statistics

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/api-reference/stats.mdx

Returns aggregate dashboard analytics

```APIDOC
## GET /v1/stats

### Description
Returns aggregate dashboard analytics

### Method
GET

### Endpoint
/v1/stats
```

--------------------------------

### Get Dashboard Statistics

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/python.mdx

Fetches key performance indicators from the dashboard, including total people, total companies, and recent events.

```python
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']}")
```

--------------------------------

### Setup API Request Function

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/javascript.mdx

Defines an asynchronous function to make authenticated requests to the Maverick Intelligence API. It handles URL construction, parameter encoding, and error handling for non-successful HTTP responses. Ensure your API key and base URL are correctly configured.

```javascript
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();
}
```

--------------------------------

### Get Person by ID

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/api-reference/get-person.mdx

Retrieves comprehensive details for a person identified by their unique ID.

```APIDOC
## GET /v1/people/{id}

### Description
Returns details for a single identified person.

### Method
GET

### Endpoint
/v1/people/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the person.
```

--------------------------------

### Get Hot Leads Only

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/python.mdx

Retrieves a list of people records filtered to include only 'hot leads'. Limits the results to 50 records.

```python
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 Person Events with Context

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/python.mdx

Retrieves events for a specific person, including their summary details in the same response. Avoids a separate API call for person information.

```python
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 a Person's Events

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/javascript.mdx

Fetches all events associated with a specific person, identified by their ID. It retrieves a limited number of events (100) and logs details about the person and each event, including timestamp, type, and URL. The person's summary is included in the response.

```javascript
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}`);
});
```

--------------------------------

### Get a Person's Events

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/python.mdx

Retrieves all events associated with a specific person ID, paginating up to 100 events per request. Includes person summary data.

```python
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']}")
```

--------------------------------

### Get Recent Visitors

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/javascript.mdx

Retrieves a list of people who have visited or interacted with your platform since yesterday. It calculates the timestamp for 24 hours ago and uses it as a filter. The result shows the count of recent visitors.

```javascript
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}`);
```

--------------------------------

### Get Dashboard Statistics

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/javascript.mdx

Fetches key performance indicators (KPIs) from the dashboard API endpoint. It retrieves and logs the total number of people, total companies, and recent events within a specified period. This provides a high-level overview of your data.

```javascript
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}`);
```

--------------------------------

### Get Hot Leads

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/javascript.mdx

Fetches a list of people identified as 'hot leads' from the API. This snippet filters results to show only high-priority contacts. It limits the number of results to 50.

```javascript
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 People Seen Since Yesterday

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/python.mdx

Fetches people records that have been seen or updated within the last 24 hours. Uses ISO 8601 format for the timestamp.

```python
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)}")
```

--------------------------------

### Make First API Request

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/introduction.mdx

Use this cURL command to fetch the first 10 identified people. Ensure you replace 'mk_live_your_key_here' with your actual API key.

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

--------------------------------

### List All People with Pagination

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/javascript.mdx

Demonstrates how to fetch all people records from the API using pagination. It repeatedly calls the API, collecting data until no more pages are available. This is useful for retrieving large datasets.

```javascript
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}`);
```

--------------------------------

### List All People with Pagination

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/python.mdx

Fetches all people records by iterating through paginated results using a cursor. Useful for retrieving large datasets.

```python
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)}")
```

--------------------------------

### Authenticate API Request with cURL

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/authentication.mdx

Use this command to make an authenticated request to the API by including your API key in the X-API-Key header.

```bash
curl -H "X-API-Key: mk_live_a1b2c3d4e5f6..." \
  https://api-v1.maverickintelligence.co/v1/people
```

--------------------------------

### List People with cURL

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/curl.mdx

Retrieve a list of people from the API. Ensure you include your API key in the request header.

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

--------------------------------

### List People

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/api-reference/list-people.mdx

Returns a paginated list of identified website visitors.

```APIDOC
## GET /v1/people

### Description
Returns a paginated list of identified website visitors

### Method
GET

### Endpoint
/v1/people
```

--------------------------------

### List Companies with cURL

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/curl.mdx

Retrieve a list of companies from the API. Ensure your API key is included in the request header.

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

--------------------------------

### Perform a Health Check

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/curl.mdx

Use this endpoint to verify API connectivity. No authentication is required.

```bash
curl https://api-v1.maverickintelligence.co/v1/health
```

--------------------------------

### Check Rate Limit Headers

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/curl.mdx

Use verbose mode (-v) to inspect rate limit headers in the API response. The output is filtered to show relevant headers.

```bash
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"
```

--------------------------------

### Handle Rate Limits in Python

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/rate-limits.mdx

This Python function demonstrates how to handle API rate limits using exponential backoff. It retries requests when a 429 status code is received, respecting the 'Retry-After' header.

```python
import time
import requests

def api_request(url, api_key, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers={"X-API-Key": api_key})

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            print(f"Rate limited. Waiting {retry_after}s...")
            time.sleep(retry_after)
            continue

        return response.json()

    raise Exception("Max retries exceeded")
```

--------------------------------

### List Companies

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/api-reference/list-companies.mdx

Returns a paginated list of identified companies.

```APIDOC
## GET /v1/companies

### Description
Returns a paginated list of identified companies

### Method
GET

### Endpoint
/v1/companies
```

--------------------------------

### List People Response Format

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/introduction.mdx

This is the standard JSON structure for list endpoints, including an array of 'data' objects and 'pagination' details. The 'nextCursor' field is used for pagination.

```json
{
  "data": [
    {
      "id": "abc123",
      "email": "jane@acme.com",
      "businessEmail": "jane@acme.com",
      "personalEmail": "jane.doe@gmail.com",
      "firstName": "Jane",
      "lastName": "Doe",
      "title": "VP Engineering",
      "company": "Acme Corp",
      "phone": "+1 (555) 012-3456",
      "profileImageUrl": "https://...",
      "trafficType": "organic",
      "isHotLead": true,
      "visitCount": 7
    }
  ],
  "pagination": {
    "limit": 50,
    "count": 50,
    "nextCursor": "eyJQSy..."
  }
}
```

--------------------------------

### List Person Events

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/api-reference/list-person-events.mdx

Retrieves page views, clicks, and scroll events for a specific person.

```APIDOC
## GET /v1/people/{id}/events

### Description
Returns page views, clicks, and scroll events for a specific person

### Method
GET

### Endpoint
/v1/people/{id}/events

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the person.
```

--------------------------------

### Filter People for Hot Leads

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/curl.mdx

Retrieve only 'hot leads' by setting the 'hot_leads_only' parameter to true.

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

--------------------------------

### Filter People by Date

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/curl.mdx

Retrieve people data that has been updated since a specific date using the 'since' parameter.

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

--------------------------------

### Browse Events

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/introduction.mdx

Retrieves a list of behavioral events (page views, clicks, scrolls) associated with a specific person.

```APIDOC
## GET /v1/events

### Description
Retrieves behavioral events such as page views, clicks, and scrolls per person.

### Method
GET

### Endpoint
/v1/events

### Parameters
#### Query Parameters
- **personId** (string) - Required - The ID of the person whose events you want to retrieve.
- **limit** (integer) - Optional - The maximum number of results to return per page.
- **cursor** (string) - Optional - A cursor for fetching the next page of results.

### Response
#### Success Response (200)
- **person** (object) - A summary of the person associated with the events.
- **data** (array) - An array of event objects.
- **pagination** (object) - Contains pagination details.

#### Response Example
{
  "person": {
    "id": "abc123",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@acme.com",
    "company": "Acme Corp"
  },
  "data": [...events...],
  "pagination": { ... }
}
```

--------------------------------

### Access Classified Contact and Traffic Data

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/javascript.mdx

Retrieves a list of people and accesses their classified contact information (business/personal emails, phone number) and traffic attribution data (source, ad platform). This snippet demonstrates how to access detailed contact and engagement metrics.

```javascript
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}`);
});
```

--------------------------------

### Access Classified Emails and Phone Numbers

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/examples/python.mdx

Iterates through a list of people to extract their best business email, personal email, and phone number. Also identifies traffic source and ad platform if applicable.

```python
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")
```

--------------------------------

### Events Endpoint Response Format

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/introduction.mdx

The events endpoint response includes a 'person' object for context, along with the event data and pagination information. This helps identify the person associated with the events.

```json
{
  "person": {
    "id": "abc123",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@acme.com",
    "company": "Acme Corp"
  },
  "data": [...events...],
  "pagination": { ... }
}
```

--------------------------------

### Standard API Error Format

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/errors.mdx

This is the JSON structure returned for API errors. It includes a code, a human-readable message, and the HTTP status.

```json
{
  "error": {
    "code": "not_found",
    "message": "Person 'abc123' not found",
    "status": 404
  }
}
```

--------------------------------

### Rate Limit Exceeded Response

Source: https://github.com/vm20381/maverick-intelligence-docs/blob/main/rate-limits.mdx

This JSON structure is returned when the API rate limit is exceeded. It includes an error code, a message, and the HTTP status code.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Limit: 1000 requests/hour.",
    "status": 429
  }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.