Retrieve visitor data

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:

X-API-Key: sk_your_api_key

The base URL is https://api.aws53.cloud; visitor endpoints begin with /v1/data. Start with Make your first API request for an account check and a visitor-list request.

Endpoint	Purpose
`GET /v1/data`	List identified visitors
`GET /v1/data?email=user@example.com`	Retrieve one visitor and their journey
`GET /v1/data/visitors/{visitorId}/sessions`	Retrieve privacy-bounded session summaries
`POST /v1/data/query`	Retrieve only visitors that match qualification rules

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.

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.

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.

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.

Retrieve session summaries

Use GET /v1/data/visitors/{visitorId}/sessions when you need stable, bounded facts about a visitor’s sessions without receiving detailed browsing activity. Set {visitorId} to the visitor’s lowercase SHA-256 emailHash. You can retrieve emailHash from the visitor list or qualification endpoint.

curl "https://api.aws53.cloud/v1/data/visitors/VISITOR_EMAIL_HASH/sessions?timeframe=30d&limit=50" \
  -H "X-API-Key: $LEADPIPE_API_KEY"

The response contains one bounded record per session:

{
  "data": [
    {
      "sessionId": "ses_1vR8zPqY2dV5hJ3mK7nB9cF4sT6wX0aL8eG2uN5iQ1o",
      "version": "sv_8sH2mN6qR1vY5cJ9kP3tW7xF0aD4eG8uL2bC6iQ1oZ5",
      "startTime": "2026-08-13T14:00:00.000Z",
      "endTime": "2026-08-13T14:14:00.000Z",
      "durationSeconds": 840,
      "pageViews": 4,
      "entryPage": "/pricing",
      "exitPage": "/thank-you",
      "updatedAt": "2026-08-13T14:15:00.000Z"
    }
  ],
  "meta": {
    "limit": 50,
    "hasMore": true,
    "nextCursor": "SIGNED_OPAQUE_CURSOR",
    "timeframe": "30d",
    "asOf": "2026-08-13T15:00:00.000Z"
  }
}

Use the fields as follows:

Field	Meaning
`sessionId`	Stable opaque identifier scoped to the organization, visitor, and canonical session bucket
`version`	Content fingerprint that changes whenever a field in the bounded summary changes
`startTime`, `endTime`	First and latest event currently materialized for the session
`durationSeconds`	Difference between `startTime` and `endTime`, not elapsed wall-clock time
`pageViews`	Number of pageviews in the session
`entryPage`, `exitPage`	Path-only first and latest pages; either value can be `null`
`updatedAt`	Time the canonical summary was last materialized; use `version` for change detection

The response is structurally limited to canonical session facts. This endpoint never returns raw or detailed events, page sequences, full URLs, origins, query strings, or fragments. entryPage and exitPage contain paths only.

Cursor pagination

The default page size is 50 sessions and the maximum is 100. Supported timeframes are 24h, 7d, 14d, 30d, 90d, and all; the default is 30d. Sessions are ordered by startTime and canonical session key, both descending. The first response fixes meta.asOf, so relative timeframe boundaries do not move while you traverse subsequent pages. When meta.hasMore is true, pass meta.nextCursor as cursor. Replace URL_ENCODED_NEXT_CURSOR below with the cursor encoded as a URL query value:

curl "https://api.aws53.cloud/v1/data/visitors/VISITOR_EMAIL_HASH/sessions?cursor=URL_ENCODED_NEXT_CURSOR" \
  -H "X-API-Key: $LEADPIPE_API_KEY"

The cursor is signed and bound to the organization, visitor, timeframe, optional pixel scope, and frozen asOf. Pass it unchanged and keep the same scope throughout the traversal. Do not construct, modify, or reuse it with different filters. Successful responses include RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset; the reset value is expressed in seconds. Use those headers to pace requests. A 429 response also includes Retry-After in seconds.

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.

<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:

{
  "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.

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

See Add attribution to a pixel for more script examples and parameter rules.

Query qualified visitors

Use POST /v1/data/query to retrieve identified visitors matching a saved segment. Get the segment ID from the segment you created in your organization; replace the example UUID before running this request.

curl "https://api.aws53.cloud/v1/data/query" \
  -H "X-API-Key: $LEADPIPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "segmentId": "00000000-0000-4000-8000-000000000001",
    "page": 1,
    "limit": 50
  }'

The endpoint accepts exactly one of segmentId or ruleAst. A saved segment must belong to the organization associated with the API key; a missing or inaccessible segment returns 404. You can also provide pixelId and a window override as documented in the generated reference. The hosted schema names ruleAst but does not define its operators or complete structure. Use a saved segment until that contract is published, or confirm a custom rule definition with Leadpipe before implementing it. This query reads existing data and does not consume visitor-resolution credits.

Pagination and historical coverage

Endpoint	Pagination	Completion
`GET /v1/data` without `email`	One-based `page`, up to 50 people per page	Follow `meta.hasMore`
`GET /v1/data/visitors/{visitorId}/sessions`	Opaque `cursor`; `limit` defaults to 50 and caps at 100	Follow `meta.nextCursor` and `meta.hasMore`
`POST /v1/data/query`	One-based `page`; `limit` defaults to 50 and caps at 100	Follow `meta.hasMore`

Use one pixel scope and time window throughout a traversal. domain and pixelId are alternative visitor-list scopes and cannot be combined. List and qualification responses include a frozen traversal boundary; session cursors carry the frozen asOf automatically. Do not invent an asOf request parameter that is absent from the endpoint schema. When meta.coverage is present, check partial. If it is true, the returned population does not fully cover the requested historical window, even after you finish pagination. Preserve this qualification in reports and exports. A missing coverage value is not proof of complete historical coverage. Identity aliases are represented as one person. Recent events and enrichment updates can appear after a processing delay; a completed traversal is not a permanent guarantee that no new data will arrive. See Authentication and errors for pacing and retries.

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 for the complete list and journey schema.
Open List privacy-bounded session summaries for the generated session endpoint reference.
Open Query qualified visitor data for the generated qualification endpoint reference.
Read Manage pixels to install pixels and pass custom attribution.
Read Visitor suppression to exclude unwanted traffic from credits and automations.

Start here

Visitors

Pixels

Visitor suppression

Account status

Authentication and endpoints

Visitor payload

Retrieve session summaries

Passing partner-specific data through the pixel

Query qualified visitors

Backward compatibility

Next steps

​Authentication and endpoints

​Visitor payload

​Retrieve session summaries

​Cursor pagination

​Passing partner-specific data through the pixel

​Query qualified visitors

​Pagination and historical coverage

​Backward compatibility

​Next steps

Authentication and endpoints

Visitor payload

Retrieve session summaries

Cursor pagination

Passing partner-specific data through the pixel

Query qualified visitors

Pagination and historical coverage

Backward compatibility

Next steps