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

# Data API

> Authenticate, retrieve visitor data, pass pixel attribution, and query qualified visitors

Use the Data API from your backend to retrieve identified visitors and their activity.

## Authentication and endpoints

Authenticate every request with your organization API key:

```http theme={null}
X-API-Key: sk_your_api_key
```

The base URL is:

```text theme={null}
https://api.aws53.cloud/v1/data
```

| Endpoint                              | Purpose                                               |
| ------------------------------------- | ----------------------------------------------------- |
| `GET /v1/data`                        | List identified visitors                              |
| `GET /v1/data?email=user@example.com` | Retrieve one visitor and their journey                |
| `POST /v1/data/query`                 | Retrieve only visitors that match qualification rules |

<Warning>
  Do not put an API key in a browser, pixel URL, or client-side JavaScript. Partner platforms should call the Data API from their backend.
</Warning>

## Visitor payload

The Data API returns the same canonical visitor data fields used by webhook deliveries, inside API-specific list, qualification, and journey response structures.

<Info>
  Data API responses are not byte-for-byte copies of webhook payloads. Webhooks include an event envelope with fields such as `event`, `timestamp`, `trigger`, `organizationId`, and `segment`. The Data API uses pagination, filtering, and journey response structures instead.
</Info>

Important visitor fields include:

| Category           | Fields                                                                            |
| ------------------ | --------------------------------------------------------------------------------- |
| Primary identity   | `email`, `emailHash`, `emailHashes.sha256`, `emailHashes.sha1`, `emailHashes.md5` |
| Contact data       | `emails`, `businessEmails`, `personalEmails`, `phones`, `phonesDnc`               |
| Custom attribution | `customAttribution`                                                               |
| Company            | `companyName`, `companyEmployeeCount`, `companyTotalRevenue`, `industry`          |
| Role               | `jobTitle`, `seniority`, `department`                                             |
| Activity           | `sessions`, `pageviews`, `pricingPageViews`, `demoPageViews`                      |
| Timing             | `firstSeenAt`, `lastSeenAt`                                                       |
| Journey            | `landingPage`, `visitedPages`, `referrer`, `referrerDomain`                       |
| UTM attribution    | `utmSource`, `utmMedium`, `utmCampaign`, `utmTerm`, `utmContent`                  |
| Ad click IDs       | `gclid`, `fbclid`, `bingClickId`, `linkedinClickId`                               |

Canonical arrays are returned as empty arrays when no values are available. Nullable scalar fields are returned as `null`.

Email hashes apply to the normalized primary email in `email`. They are not hashes for every address in `emails`. `emailHash` and `emailHashes.sha256` both contain the SHA-256 value.

Phone numbers are returned in `phones`. Phone hashes are not currently generated. `phonesDnc` is a boolean do-not-call status, or `null` when the status is unavailable.

Use the generated endpoint pages under **Visitors** for the complete response schema.

## Passing partner-specific data through the pixel

Append custom query parameters to the existing pixel script URL when you need to associate visitors with a partner customer, campaign, or another internal label.

```html theme={null}
<script
  src="https://leadpipe.aws53.cloud/p/YOUR-PIXEL-ID.js?partnerCustomerId=customer_123&campaign=spring-2026"
  async
></script>
```

If the pixel URL already contains query parameters, append additional values with `&` instead of starting another query string with `?`.

Leadpipe captures the parameters with the visitor session and returns them in `customAttribution`:

```json theme={null}
{
  "customAttribution": {
    "partnerCustomerId": "customer_123",
    "campaign": "spring-2026"
  }
}
```

Custom attribution is available in visitor lists, qualification queries, and the visitor journey endpoint. The same values are also included in webhook payloads.

<Warning>
  Do not put secrets, API keys, passwords, or sensitive personal information in pixel query parameters.
</Warning>

See [Add attribution to a pixel](/guides/manage-pixels#add-attribution-to-a-pixel) for more script examples and parameter rules.

## Query qualified visitors

Use `POST /v1/data/query` to eliminate low-fit traffic before it reaches your workflow. The following rule returns visitors who:

1. Viewed a pricing page or a URL containing `/book-a-call`.
2. Have director-level seniority or a job title containing `founder`.

```bash theme={null}
curl -X POST "https://api.aws53.cloud/v1/data/query" \
  -H "X-API-Key: $LEADPIPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ruleAst": {
      "version": 1,
      "window": "30d",
      "rule": {
        "all": [
          {
            "any": [
              {
                "field": "behavior.pricing_page_views",
                "op": "gte",
                "value": 1
              },
              {
                "field": "behavior.visited_paths",
                "op": "any_contains",
                "value": "/book-a-call"
              }
            ]
          },
          {
            "any": [
              {
                "field": "company.seniority",
                "op": "contains",
                "value": "director"
              },
              {
                "field": "company.job_title",
                "op": "contains",
                "value": "founder"
              }
            ]
          }
        ]
      }
    },
    "page": 1,
    "limit": 50
  }'
```

Replace `/book-a-call` with the customer's actual call-booking path, such as `/schedule`, `/contact-sales`, or `/demo`.

The endpoint also accepts a saved segment:

```json theme={null}
{
  "segmentId": "saved-segment-uuid",
  "page": 1,
  "limit": 50
}
```

Provide exactly one of `segmentId` or `ruleAst`. A saved segment must belong to the organization associated with the API key. Cross-organization segment IDs return `404`.

Qualification queries accept at most `25` predicates with a maximum rule depth of `8`.

## Pagination and rate limits

| Endpoint              | Page size                      | Rate limit               |
| --------------------- | ------------------------------ | ------------------------ |
| `GET /v1/data`        | `50` visitors per page         | `60` requests per minute |
| `POST /v1/data/query` | `1` to `100`; defaults to `50` | `30` requests per minute |

Use `meta.hasMore` and increment `meta.page` until `meta.hasMore` becomes `false`.

## Backward compatibility

Existing Data API aliases remain available, but new integrations should use the canonical names.

| Legacy field      | Canonical field        |
| ----------------- | ---------------------- |
| `allEmails`       | `emails`               |
| `primaryPhone`    | `phones`               |
| `allPhones`       | `phones`               |
| `phonesDNC`       | `phonesDnc`            |
| `company`         | `companyName`          |
| `companyZip`      | `companyZipCode`       |
| `companySize`     | `companyEmployeeCount` |
| `companyRevenue`  | `companyTotalRevenue`  |
| `companyIndustry` | `industry`             |
| `firstSeen`       | `firstSeenAt`          |
| `lastSeen`        | `lastSeenAt`           |
| `msclkid`         | `bingClickId`          |
| `liFatId`         | `linkedinClickId`      |
| `gbraid`          | `googleGbraid`         |
| `wbraid`          | `googleWbraid`         |

Use `phonesDnc` instead of `phonesDNC`. The canonical field is a boolean or `null`; the legacy field retains its older array-or-`null` shape.

Use `companyEmployeeCount` instead of the ambiguous `companySize`. Both fields contain a numeric employee count for backward compatibility.

## Next steps

* Open [Query visitor data](/api-reference/visitors/query-visitor-data-via-api-key) for the complete list and journey schema.
* Open [Query qualified visitor data](/api-reference/visitors/query-qualified-visitor-data-via-api-key) for the generated qualification endpoint reference.
* Read [Manage pixels](/guides/manage-pixels) to install pixels and pass custom attribution.
* Read [Visitor suppression](/api-reference/visitor-suppression) to exclude unwanted traffic from credits and automations.