# Account health and credit status
Source: https://docs.leadpipe.com/api-reference/account/account-health-and-credit-status
https://api.aws53.cloud/openapi-data.json get /v1/data/account
Returns organization status, credit balance, pixel summary, and intent audience slots. Use this to check if your account is healthy and has remaining credits.
# Activate an Orbit audience destination
Source: https://docs.leadpipe.com/api-reference/audience-builder/activate-an-orbit-audience-destination
https://api.aws53.cloud/openapi-intent.json post /v1/intent/audiences/{audienceId}/destinations/{destinationId}/activate
Activates a destination and approves the current audience definition for delivery. Requires a non-viewer member using bearer authentication and an organization eligible for delivery. With syncCurrent true, the latest completed matching audience run is scheduled for delivery when available; the returned delivery is null otherwise. Provider configuration is verified before activation. Requests share a 120-per-60-second allowance per source IP within this integration, destination, or delivery route family.
# Cancel a queued intent audience run
Source: https://docs.leadpipe.com/api-reference/audience-builder/cancel-a-queued-intent-audience-run
https://api.aws53.cloud/openapi-intent.json delete /v1/intent/audiences/{id}/runs/{runId}
Cancels a queued run owned by the authenticated organization and returns its updated state. Only queued runs can be cancelled; repeating cancellation or racing with processing returns a conflict.
# Create a saved intent topic list
Source: https://docs.leadpipe.com/api-reference/audience-builder/create-a-saved-intent-topic-list
https://api.aws53.cloud/openapi-intent.json post /v1/intent/topics/lists
Saves a named list of 1 to 250 topic identifiers in the authenticated organization. Duplicate topic identifiers are removed and the saved identifiers are sorted numerically. Source metadata is optional, and creating a list does not create an audience.
# Create an audience from a saved topic list
Source: https://docs.leadpipe.com/api-reference/audience-builder/create-an-audience-from-a-saved-topic-list
https://api.aws53.cloud/openapi-intent.json post /v1/intent/topics/lists/{id}/instantiate
Creates an audience in the authenticated organization from a saved topic list, optionally overriding the name, score thresholds, and filters. The audience defaults to draft and uses the list name when no name is supplied. Active creation requires audience access and counts toward the 50-audience limit; the source list is unchanged.
# Create an intent audience draft
Source: https://docs.leadpipe.com/api-reference/audience-builder/create-an-intent-audience-draft
https://api.aws53.cloud/openapi-intent.json post /v1/intent/audiences
Saves an audience in the authenticated organization. New audiences default to draft; active creation requires an available audience slot or eligible one-shot access, and paused creation is rejected. The organization can save at most 50 audiences. This operation does not itself materialize contacts.
# Create an Orbit audience destination
Source: https://docs.leadpipe.com/api-reference/audience-builder/create-an-orbit-audience-destination
https://api.aws53.cloud/openapi-intent.json post /v1/intent/audiences/{audienceId}/destinations
Creates a draft webhook or EmailOctopus destination for an audience owned by the authenticated organization. Requires a non-viewer member using bearer authentication. Webhook URLs must resolve to public addresses and subscribe to contact upserts. A new webhook signing secret is returned only in this response. No contacts are delivered until activation. Requests share a 120-per-60-second allowance per source IP within this integration, destination, or delivery route family.
# Create or reuse a stored CSV export for a completed run
Source: https://docs.leadpipe.com/api-reference/audience-builder/create-or-reuse-a-stored-csv-export-for-a-completed-run
https://api.aws53.cloud/openapi-intent.json post /v1/intent/audiences/{id}/runs/{runId}/exports
Creates a stored CSV for a completed audience run owned by the authenticated organization, or reuses an existing completed export. Returns export metadata and an expiring signed download URL. A concurrent export already being processed returns a conflict.
# Delete a saved intent topic list
Source: https://docs.leadpipe.com/api-reference/audience-builder/delete-a-saved-intent-topic-list
https://api.aws53.cloud/openapi-intent.json delete /v1/intent/topics/lists/{id}
Permanently deletes a saved topic list owned by the authenticated organization. Audiences previously created from the list are not deleted.
# Delete an intent audience
Source: https://docs.leadpipe.com/api-reference/audience-builder/delete-an-intent-audience
https://api.aws53.cloud/openapi-intent.json delete /v1/intent/audiences/{id}
Deletes an audience owned by the authenticated organization and its associated runs, materialized results, and exports. Export-file cleanup is best effort. A consumed one-shot trial remains consumed after deletion. This action cannot be undone.
# Delete an Orbit audience destination
Source: https://docs.leadpipe.com/api-reference/audience-builder/delete-an-orbit-audience-destination
https://api.aws53.cloud/openapi-intent.json delete /v1/intent/audiences/{audienceId}/destinations/{destinationId}
Permanently deletes a destination owned by the authenticated organization after cancelling pending deliveries. Requires a non-viewer member using bearer authentication. This does not delete the source audience or remove contacts already sent to the external service. Requests share a 120-per-60-second allowance per source IP within this integration, destination, or delivery route family.
# Download a completed intent audience run as CSV
Source: https://docs.leadpipe.com/api-reference/audience-builder/download-a-completed-intent-audience-run-as-csv
https://api.aws53.cloud/openapi-intent.json get /v1/intent/audiences/{id}/runs/{runId}/export.csv
Streams a CSV of a completed audience run owned by the authenticated organization, capped at 300,000 rows. Response headers report the total result count and whether the export was truncated. Queued, running, failed, or cancelled runs cannot be exported.
# Get a stored export and fresh signed download URL
Source: https://docs.leadpipe.com/api-reference/audience-builder/get-a-stored-export-and-fresh-signed-download-url
https://api.aws53.cloud/openapi-intent.json get /v1/intent/audiences/{id}/runs/{runId}/exports/{exportId}
Returns a completed stored export owned by the authenticated organization and a fresh, expiring signed download URL. The audience, run, and export identifiers must belong together. An export that is not completed returns a conflict.
# Get an EmailOctopus list and its fields
Source: https://docs.leadpipe.com/api-reference/audience-builder/get-an-emailoctopus-list-and-its-fields
https://api.aws53.cloud/openapi-intent.json get /v1/intent/integrations/emailoctopus/lists/{listId}
Returns one EmailOctopus list, its destination fields, and supported source fields for mapping audience contacts. The connected account must be healthy and owned by the authenticated organization. Requires a non-viewer member using bearer authentication. Requests share a 120-per-60-second allowance per source IP within this integration, destination, or delivery route family.
# Get an intent audience
Source: https://docs.leadpipe.com/api-reference/audience-builder/get-an-intent-audience
https://api.aws53.cloud/openapi-intent.json get /v1/intent/audiences/{id}
Returns one audience owned by the authenticated organization, including its normalized configuration, topic labels, access type, and refresh state. An audience outside the organization is treated as not found.
# Get an Orbit audience delivery
Source: https://docs.leadpipe.com/api-reference/audience-builder/get-an-orbit-audience-delivery
https://api.aws53.cloud/openapi-intent.json get /v1/intent/audiences/{audienceId}/deliveries/{deliveryId}
Returns an organization-owned delivery and a paginated list of failed or skipped members. Requires a non-viewer member using bearer authentication. Failure pagination defaults to 25 rows and allows at most 100; failures are ordered by creation time then identifier, both descending. Member email addresses are represented by hashes. Requests share a 120-per-60-second allowance per source IP within this integration, destination, or delivery route family.
# Get an Orbit audience destination
Source: https://docs.leadpipe.com/api-reference/audience-builder/get-an-orbit-audience-destination
https://api.aws53.cloud/openapi-intent.json get /v1/intent/audiences/{audienceId}/destinations/{destinationId}
Returns a destination belonging to the selected audience and authenticated organization, including configuration and delivery counters but no webhook signing secret. Requires a non-viewer member using bearer authentication. Requests share a 120-per-60-second allowance per source IP within this integration, destination, or delivery route family.
# Get audience run trends for charts
Source: https://docs.leadpipe.com/api-reference/audience-builder/get-audience-run-trends-for-charts
https://api.aws53.cloud/openapi-intent.json get /v1/intent/audiences/{id}/trends
Returns chronological per-run metrics and run-over-run movement counts for completed runs.
# Get fill-rate stats for a completed intent audience run
Source: https://docs.leadpipe.com/api-reference/audience-builder/get-fill-rate-stats-for-a-completed-intent-audience-run
https://api.aws53.cloud/openapi-intent.json get /v1/intent/audiences/{id}/runs/{runId}/stats
Returns contact-field fill rates and intent-score statistics for a completed run owned by the authenticated organization. A run that is not completed returns a conflict; the statistics describe the stored run snapshot.
# Get hydrated run results
Source: https://docs.leadpipe.com/api-reference/audience-builder/get-hydrated-run-results
https://api.aws53.cloud/openapi-intent.json get /v1/intent/audiences/{id}/runs/{runId}/results
Returns a completed run and its materialized contact results for an audience owned by the authenticated organization. Offset pagination defaults to 100 rows with a maximum of 500, ordered by intent score descending, topic overlap descending, then email hash ascending. Queued or running runs return 202; failed or cancelled runs return a conflict. Previously completed snapshots do not refresh with this request.
# Get latest audience movement summary
Source: https://docs.leadpipe.com/api-reference/audience-builder/get-latest-audience-movement-summary
https://api.aws53.cloud/openapi-intent.json get /v1/intent/audiences/{id}/dashboard
Compares the latest completed run against the prior completed run and returns compact counts for people added, people removed, intent movement, topic movement, and website visits.
# Get matched intent topics over time for a website visitor
Source: https://docs.leadpipe.com/api-reference/audience-builder/get-matched-intent-topics-over-time-for-a-website-visitor
https://api.aws53.cloud/openapi-intent.json get /v1/intent/audiences/website-visitors/{hashedEmail}/topic-history
Returns chronological intent audience runs where this hashed email appeared, including the topics matched in each run. Use audienceId to scope the history to one saved audience.
# List connected Orbit integration accounts
Source: https://docs.leadpipe.com/api-reference/audience-builder/list-connected-orbit-integration-accounts
https://api.aws53.cloud/openapi-intent.json get /v1/intent/integrations/accounts
Refreshes connected EmailOctopus accounts for the authenticated organization and returns them most recently updated first. If the provider refresh fails, saved account state is returned. Requires a non-viewer member using bearer authentication; API keys are not allowed. The list is not paginated. Requests share a 120-per-60-second allowance per source IP within this integration, destination, or delivery route family.
# List EmailOctopus lists
Source: https://docs.leadpipe.com/api-reference/audience-builder/list-emailoctopus-lists
https://api.aws53.cloud/openapi-intent.json get /v1/intent/integrations/emailoctopus/lists
Returns the lists available in a healthy EmailOctopus account owned by the authenticated organization. Requires a non-viewer member using bearer authentication. Provider list order is preserved; the response is not paginated. Requests share a 120-per-60-second allowance per source IP within this integration, destination, or delivery route family.
# List intent audience runs
Source: https://docs.leadpipe.com/api-reference/audience-builder/list-intent-audience-runs
https://api.aws53.cloud/openapi-intent.json get /v1/intent/audiences/{id}/runs
Lists runs for an audience owned by the authenticated organization, newest creation first. The limit defaults to 25 and allows up to 100; there is no cursor or offset, and ties in creation time have no guaranteed secondary order. No runs produces an empty list.
# List intent audiences
Source: https://docs.leadpipe.com/api-reference/audience-builder/list-intent-audiences
https://api.aws53.cloud/openapi-intent.json get /v1/intent/audiences
Returns audiences belonging to the authenticated organization, optionally filtered by status, newest creation first. The limit defaults to 50 and allows up to 100; there is no cursor or offset. Equal creation timestamps have no guaranteed secondary ordering. An organization with no matches receives an empty list.
# List Orbit audience deliveries
Source: https://docs.leadpipe.com/api-reference/audience-builder/list-orbit-audience-deliveries
https://api.aws53.cloud/openapi-intent.json get /v1/intent/audiences/{audienceId}/deliveries
Returns deliveries for an audience owned by the authenticated organization, newest creation first, with a total count. Requires a non-viewer member using bearer authentication. Offset pagination defaults to 25 rows and allows at most 100. Equal creation timestamps have no guaranteed secondary order; an empty page returns an empty deliveries array. Requests share a 120-per-60-second allowance per source IP within this integration, destination, or delivery route family.
# List Orbit audience destinations
Source: https://docs.leadpipe.com/api-reference/audience-builder/list-orbit-audience-destinations
https://api.aws53.cloud/openapi-intent.json get /v1/intent/audiences/{audienceId}/destinations
Returns destinations for an audience owned by the authenticated organization, newest creation first. Requires a non-viewer member using bearer authentication. The list is not paginated; no destinations produces an empty list. Webhook signing secrets are omitted. Requests share a 120-per-60-second allowance per source IP within this integration, destination, or delivery route family.
# List Orbit integration apps
Source: https://docs.leadpipe.com/api-reference/audience-builder/list-orbit-integration-apps
https://api.aws53.cloud/openapi-intent.json get /v1/intent/integrations/apps
Returns the supported external audience integration apps. Requires a non-viewer organization member using bearer authentication; API keys cannot manage integrations. Requests share a 120-per-60-second allowance per source IP within this integration, destination, or delivery route family.
# List people in one intent audience who visited the site
Source: https://docs.leadpipe.com/api-reference/audience-builder/list-people-in-one-intent-audience-who-visited-the-site
https://api.aws53.cloud/openapi-intent.json get /v1/intent/audiences/{id}/website-visitors
Returns the overlap between the latest completed run for this audience and recent identified website visitors.
# List people who are in intent audiences and visited the site
Source: https://docs.leadpipe.com/api-reference/audience-builder/list-people-who-are-in-intent-audiences-and-visited-the-site
https://api.aws53.cloud/openapi-intent.json get /v1/intent/audiences/website-visitors
Returns the all-org overlap between latest completed intent audience runs and recent identified website visitors. Results are deduplicated by hashed email and include all latest audience matches for each person.
# List saved intent topic lists
Source: https://docs.leadpipe.com/api-reference/audience-builder/list-saved-intent-topic-lists
https://api.aws53.cloud/openapi-intent.json get /v1/intent/topics/lists
Returns saved topic lists owned by the authenticated organization, most recently updated first. The limit defaults to 50 and allows up to 100; there is no cursor or offset, and equal update timestamps have no guaranteed secondary ordering. No saved lists produces an empty list.
# List stored exports for a run
Source: https://docs.leadpipe.com/api-reference/audience-builder/list-stored-exports-for-a-run
https://api.aws53.cloud/openapi-intent.json get /v1/intent/audiences/{id}/runs/{runId}/exports
Lists stored CSV exports for an audience run owned by the authenticated organization, newest creation first. This unpaginated list is empty when no exports exist; it does not generate files or issue signed download URLs.
# Preview an intent audience
Source: https://docs.leadpipe.com/api-reference/audience-builder/preview-an-intent-audience
https://api.aws53.cloud/openapi-intent.json post /v1/intent/audiences/preview
Counts and samples an audience using the latest available intent snapshot without saving an audience. Requires an authenticated organization member or API key. Sample contact details are masked, and counts can change as new intent data becomes available.
# Queue an intent audience materialization run
Source: https://docs.leadpipe.com/api-reference/audience-builder/queue-an-intent-audience-materialization-run
https://api.aws53.cloud/openapi-intent.json post /v1/intent/audiences/{id}/runs
Queues a materialization run for an active audience owned by the authenticated organization. Processing is asynchronous. An existing in-flight run can be returned instead of creating a duplicate; an Idempotency-Key makes retries return the same run.
# Queue an Orbit audience destination sync
Source: https://docs.leadpipe.com/api-reference/audience-builder/queue-an-orbit-audience-destination-sync
https://api.aws53.cloud/openapi-intent.json post /v1/intent/audiences/{audienceId}/destinations/{destinationId}/sync
Schedules delivery of the latest completed audience run to an active destination owned by the authenticated organization. Requires a non-viewer member using bearer authentication and delivery eligibility. Incremental mode sends changes; full_resync requests the full snapshot. Processing is asynchronous. Requests share a 120-per-60-second allowance per source IP within this integration, destination, or delivery route family.
# Retry a failed or partial Orbit audience delivery
Source: https://docs.leadpipe.com/api-reference/audience-builder/retry-a-failed-or-partial-orbit-audience-delivery
https://api.aws53.cloud/openapi-intent.json post /v1/intent/audiences/{audienceId}/deliveries/{deliveryId}/retry
Retries a failed or partial delivery owned by the authenticated organization and reactivates its destination. Requires a non-viewer member using bearer authentication and delivery eligibility. The source snapshot must remain completed and unexpired, and its configuration must still match the approved destination. Processing is asynchronous. Requests share a 120-per-60-second allowance per source IP within this integration, destination, or delivery route family.
# Rotate an Orbit webhook signing secret
Source: https://docs.leadpipe.com/api-reference/audience-builder/rotate-an-orbit-webhook-signing-secret
https://api.aws53.cloud/openapi-intent.json post /v1/intent/audiences/{audienceId}/destinations/{destinationId}/rotate-secret
Replaces the signing secret for a paused or draft webhook destination owned by the authenticated organization. Requires a non-viewer member using bearer authentication. The new secret is returned once and replaces the previous secret immediately. Requests share a 120-per-60-second allowance per source IP within this integration, destination, or delivery route family.
# Test an Orbit audience destination without syncing contacts
Source: https://docs.leadpipe.com/api-reference/audience-builder/test-an-orbit-audience-destination-without-syncing-contacts
https://api.aws53.cloud/openapi-intent.json post /v1/intent/audiences/{audienceId}/destinations/{destinationId}/test
Checks an organization-owned destination without syncing audience contacts. Requires a non-viewer member using bearer authentication and delivery eligibility. Webhook destinations receive a synthetic test event; EmailOctopus destinations have their account and list checked. Requests share a 120-per-60-second allowance per source IP within this integration, destination, or delivery route family.
# Update a saved intent topic list
Source: https://docs.leadpipe.com/api-reference/audience-builder/update-a-saved-intent-topic-list
https://api.aws53.cloud/openapi-intent.json patch /v1/intent/topics/lists/{id}
Updates a saved topic list owned by the authenticated organization. Only supplied fields change; topic identifiers are deduplicated and sorted numerically. Source URL and keywords can be cleared with null. Existing audiences are not rewritten.
# Update an intent audience
Source: https://docs.leadpipe.com/api-reference/audience-builder/update-an-intent-audience
https://api.aws53.cloud/openapi-intent.json patch /v1/intent/audiences/{id}
Updates the name, status, or configuration of an audience owned by the authenticated organization. Activation requires available audience access; pausing stops future automatic refreshes. Configuration updates affect future runs, not previously materialized results.
# Update or pause an Orbit audience destination
Source: https://docs.leadpipe.com/api-reference/audience-builder/update-or-pause-an-orbit-audience-destination
https://api.aws53.cloud/openapi-intent.json patch /v1/intent/audiences/{audienceId}/destinations/{destinationId}
Updates or pauses a destination belonging to the authenticated organization. Requires a non-viewer member using bearer authentication. Configuration changes reset the delivery baseline; pausing cancels pending deliveries. This operation does not activate a destination. Requests share a 120-per-60-second allowance per source IP within this integration, destination, or delivery route family.
# Validate an intent audience config
Source: https://docs.leadpipe.com/api-reference/audience-builder/validate-an-intent-audience-config
https://api.aws53.cloud/openapi-intent.json post /v1/intent/audiences/validate
Validates and normalizes a topic, score, and filter definition without saving an audience or materializing contacts. Requires an authenticated organization member or organization API key. Returns the normalized configuration, configuration hash, and applied filter fields.
# Authentication and errors
Source: https://docs.leadpipe.com/api-reference/authentication-and-errors
Use an organization API key, handle endpoint-specific errors, and pace API requests
The Identification, Orbit, and IP to company APIs use `https://api.aws53.cloud` as the base URL. Create or manage your organization API key in **Settings > API Keys** and send it in the `X-API-Key` header for operations that support API-key authentication.
```http theme={null}
X-API-Key: YOUR_ORGANIZATION_API_KEY
```
Keys are scoped to an organization. Use resource IDs from that organization. Regenerating a key invalidates the previous one; update every backend that uses it. Do not place keys in browser code or pixel URLs.
## Authentication by API
| API area | Authentication |
| ---------------------------------------------------------- | --------------------------------------------------------------------- |
| Identification API | Organization API key |
| IP to company API | Active organization API key and an eligible organization |
| Orbit topic discovery and filter catalog | Public; see each endpoint for optional authentication and rate limits |
| Orbit audience definitions, runs, results, and topic lists | Organization API key or supported Bearer authentication |
| Orbit integrations, destinations, and deliveries | See the access discrepancy below before integrating |
Do not send an `sk_...` API key as a Bearer token.
The hosted Orbit specification currently conflicts on integration, destination, and delivery authentication: its security declarations allow API keys, but its operation descriptions require a non-viewer member using Bearer authentication. API-key support for these operations needs confirmation from Leadpipe before you rely on it. The generated authentication control alone does not resolve this discrepancy.
## Read the endpoint's error response
The generated endpoint reference defines the status codes and response body for each operation. Identification and Orbit do not use one universal error envelope.
| Status | Action |
| ------ | -------------------------------------------------------------------------------------------------------- |
| `400` | Correct the request using the endpoint schema and returned validation details. |
| `401` | Check the header and current key. |
| `403` | Check key revocation, organization status, selected-resource access, and feature access. |
| `404` | Check the resource ID and organization. |
| `409` | Resolve the endpoint-specific conflict before retrying. |
| `429` | Wait as instructed by the response headers and reduce request frequency. |
| `5xx` | Capture a redacted response and request ID when present; limit retries and escalate persistent failures. |
For [company lookups](/ip-to-company/introduction#handle-errors-and-rate-limits), `429` can also mean the separate billing allowance is exhausted. That requires a billing reset or limit increase, rather than a short retry delay.
For an Orbit results read, `202` means the run is still queued or running. Failed or cancelled runs return a conflict. See the [polling example](/orbit-api/examples).
## Rate limits and retries
For Identification visitor reads and qualification queries, use `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset`. The reset value is in seconds. A `429` response also documents `Retry-After` in seconds. Do not hardcode an allowance from another endpoint.
Orbit has endpoint-specific allowances. Public catalog requests and site analysis have different authentication behavior; see [Find topics](/orbit-api/find-topics#authentication-and-rate-limits).
Use bounded retries for reads. Before retrying a write, check whether it supports safe repetition. Orbit run creation supports `Idempotency-Key`: reuse the same key for retries of the same intended run, and choose a new key for a new run. Do not assume that every write accepts that header.
Company lookup is a `GET` that consumes allowance when it returns a company, including on repeat requests. Avoid automatic retries after an uncertain response, and do not cache or prefetch responses. See [Company-lookup usage](/ip-to-company/introduction#track-your-company-lookup-allowance).
For troubleshooting, record the method, path, HTTP status, and request ID when available. Remove API keys and personal visitor data from shared logs.
# Retrieve visitor data
Source: https://docs.leadpipe.com/api-reference/data-api
Authenticate, retrieve visitor data and session summaries, 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 `https://api.aws53.cloud`; visitor endpoints begin with `/v1/data`. Start with [Make your first API request](/api-reference/quickstart) 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.
```bash theme={null}
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:
```json theme={null}
{
"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:
```bash theme={null}
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.
```html theme={null}
```
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.
Do not put secrets, API keys, passwords, or sensitive personal information in pixel query parameters.
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 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.
```bash theme={null}
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](/api-reference/authentication-and-errors#rate-limits-and-retries) 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](/api-reference/visitors/query-visitor-data-via-api-key) for the complete list and journey schema.
* Open [List privacy-bounded session summaries](/api-reference/visitors/list-privacy-bounded-session-summaries) for the generated session endpoint reference.
* 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.
# Identification API overview
Source: https://docs.leadpipe.com/api-reference/introduction
Programmatic access to Leadpipe identification, visitor data, and pixel management
The Leadpipe Identification API gives you programmatic access to resolved visitor data and full control over your tracking pixels.
To look up stored company information for an IP address, use the separate [IP to company API section](/ip-to-company/introduction).
## Choose a task
List identified visitors, retrieve a journey, and understand canonical visitor fields.
Page through stable, privacy-bounded session facts without receiving detailed events.
Use a saved segment or canonical rule to return only visitors who qualify.
Create, list, pause, activate, and configure tracking pixels.
Prevent selected visitors from consuming credits or triggering automations.
Review organization health, credits, pixels, and intent access.
## Start integrating
1. [Make your first API request](/api-reference/quickstart) to verify account access and retrieve visitors.
2. Read [Authentication and errors](/api-reference/authentication-and-errors) for organization scope, key handling, and retries.
3. Use [Retrieve visitor data](/api-reference/data-api) for journeys, session pagination, saved segments, and historical coverage.
## Endpoint reference
The endpoint pages under **Visitors**, **Pixels**, **Visitor suppression**, and **Account status** are generated from the [hosted Identification OpenAPI specification](https://api.aws53.cloud/openapi-data.json). Use them for exact request fields, responses, and status codes.
Pixel path filters support include-only and exclude modes. See [Manage pixels](/guides/manage-pixels#path-filters) before changing page targeting.
Suppressed visitors are still identified, but they consume no credits and trigger no webhooks or integrations. Read [Visitor suppression](/api-reference/visitor-suppression) before uploading or replacing a rule list.
# Create a pixel for a domain
Source: https://docs.leadpipe.com/api-reference/pixels/create-a-pixel-for-a-domain
https://api.aws53.cloud/openapi-data.json post /v1/data/pixels
Creates a new tracking pixel. Authenticates via X-API-Key header.
# List all pixels for the organization
Source: https://docs.leadpipe.com/api-reference/pixels/list-all-pixels-for-the-organization
https://api.aws53.cloud/openapi-data.json get /v1/data/pixels
Returns all non-deleted pixels belonging to the X-API-Key organization, newest creation first. Equal creation timestamps have no guaranteed tie-breaker. The list is not paginated; no matches returns an empty data array. Revoked keys and expired or suspended organizations are rejected.
# Update a pixel (pause, activate, or set path filters)
Source: https://docs.leadpipe.com/api-reference/pixels/update-a-pixel-pause-activate-or-set-path-filters
https://api.aws53.cloud/openapi-data.json patch /v1/data/pixels/{id}
Updates a pixel. Accepts status, excludedPaths, includedPaths, or any combination. Set paths to null to clear. Mutually exclusive: cannot have both includedPaths and excludedPaths set. Authenticates via X-API-Key header.
# Make your first API request
Source: https://docs.leadpipe.com/api-reference/quickstart
Check your organization API key and retrieve identified visitor data from your backend
Use these read-only requests to check authentication and retrieve visitor data. You need an organization API key from **Settings > API Keys** and `curl` on your computer or server. Set `LEADPIPE_API_KEY` in your local environment or secret manager before running the examples.
## Check account status
```bash theme={null}
curl "https://api.aws53.cloud/v1/data/account" \
-H "X-API-Key: $LEADPIPE_API_KEY"
```
A successful response contains `data.healthy`, organization status, credits, pixels, and intent access. Check these values before diagnosing missing visitor data. See [Account status](/api-reference/account/account-health-and-credit-status) for the response schema.
## Retrieve visitors
```bash theme={null}
curl "https://api.aws53.cloud/v1/data?timeframe=7d&page=1" \
-H "X-API-Key: $LEADPIPE_API_KEY"
```
A successful list request returns visitor records in `data` and pagination information in `meta`. An empty list can mean there is no identified activity in the selected scope. Check the pixel and date range before treating it as an authentication problem.
For one site, pass `pixelId` or `domain`; do not combine them. Get pixel IDs from [List pixels](/api-reference/pixels/list-all-pixels-for-the-organization).
## Continue your integration
| Task | Guide |
| ------------------------------ | ---------------------------------------------------------------------------- |
| Retrieve one visitor's journey | [Visitor data](/api-reference/data-api) |
| Read bounded session facts | [Session summaries](/api-reference/data-api#retrieve-session-summaries) |
| Read a saved segment | [Query qualified visitors](/api-reference/data-api#query-qualified-visitors) |
| Exclude unwanted traffic | [Visitor suppression](/api-reference/visitor-suppression) |
| Resolve errors or rate limits | [Authentication and errors](/api-reference/authentication-and-errors) |
Keep the API key in your backend. The [pixel snippet](/guides/get-started) runs in the browser and does not contain an API key.
# Visitor suppression
Source: https://docs.leadpipe.com/api-reference/visitor-suppression
Stop spending credits and firing automations on traffic you do not want
Suppressed visitors are still identified. They consume no credits and trigger no webhooks or integrations.
Rules apply to your whole organization, across every pixel. There is no cap on how many rules you can store.
## Start with the industries endpoint
An `industry` rule matches the enriched company industry exactly, case-insensitive. A value that never appears in your data suppresses nothing, silently, and you keep paying for those visitors. `Ed Tech` does not match `Higher Education`.
Call the industries endpoint first and copy each `value` verbatim into your rules.
```bash theme={null}
GET /v1/data/suppression-rules/industries?limit=4
X-API-Key: YOUR_API_KEY
```
```json theme={null}
{
"data": [
{ "value": "Information Technology & Services", "visitors": 22, "suppressed": false },
{ "value": "Venture Capital And Private Equity Principals", "visitors": 8, "suppressed": false },
{ "value": "Banking", "visitors": 4, "suppressed": false },
{ "value": "Business Consulting And Services", "visitors": 4, "suppressed": false }
],
"meta": { "visitorsWithoutIndustry": 120, "suppressedIndustryRules": 1, "limit": 4 }
}
```
`visitors` is how many identified visitors carry that industry, so you can assess how much traffic a rule would match. `suppressed` tells you a rule already exists.
`meta.visitorsWithoutIndustry` counts identified visitors with no company industry at all. No industry rule can reach them. Suppress those by domain or email instead.
Email and domain values are normalized before matching. You still need the correct rule type and value: an email domain and an enriched company domain can differ.
## Rule types
| Type | Matches |
| ---------------- | -------------------------------------------- |
| `email` | One person's email address |
| `domain` | The email domain of the identified person |
| `company_domain` | The website domain of the identified company |
| `industry` | The enriched company industry, exactly |
## Values are normalized before storage
Values are lowercased. Domains lose their scheme, `www.`, path, and port. Submitting `https://www.acme-partners.example/pricing` stores `acme-partners.example`, and that normalized value is what you get back when you read the list. This surprises people reconciling an upload against a source file.
For append uploads, submitting rules already stored does not add duplicates. A replacement still removes rules outside the submitted set, so review the source list and concurrent edits before repeating `PUT`.
## Append or replace
Use `POST` to add rules on top of what is already stored. This is the normal upload path.
Use `PUT` when a file is your source of truth. It deletes every existing rule and replaces it with what you submit, in one transaction, so re-posting the whole list on every sync run keeps the stored list matching the file exactly.
Pass `types` on `PUT` to scope the replace to certain rule types and leave the rest untouched — sync your `email` list without disturbing industry rules. Send an empty `rules` array together with `types` to clear a category.
Both endpoints accept up to 25,000 rules per call. A list longer than that cannot be replaced atomically, so build it up with `POST` instead.
## One bad row does not fail the batch
Rows that fail validation come back in `rejected`. Every other row is still applied, so a 5,000-row CSV does not fail on one bad cell.
```bash theme={null}
POST /v1/data/suppression-rules
X-API-Key: YOUR_API_KEY
```
```json theme={null}
{
"rules": [
{ "type": "company_domain", "value": "https://www.acme-partners.example/pricing" },
{ "type": "domain", "value": "acme-partners.example" },
{ "type": "email", "value": "procurement@bigco.example" },
{ "type": "industry", "value": "Higher Education" },
{ "type": "domain", "value": "not a domain" }
]
}
```
```json theme={null}
{
"data": {
"added": 4,
"removed": 0,
"duplicates": 0,
"rejectedCount": 1,
"rejected": [
{ "index": 4, "type": "domain", "value": "not a domain", "reason": "Invalid domain" }
],
"total": 4
}
}
```
`index` is the position of the row in the array you submitted. `rejected` carries detail for the first 100 failures; `rejectedCount` is the true total. `duplicates` counts rows skipped because they were already stored or repeated inside the same request.
## Rules take effect going forward
Suppression is forward-only. A new rule applies from the next sync cycle onward, and visitors you were already charged for are not refunded. Removing a rule works the same way: it stops suppressing from the next cycle.
## Reading the list back
```bash theme={null}
GET /v1/data/suppression-rules?limit=3
X-API-Key: YOUR_API_KEY
```
```json theme={null}
{
"data": {
"rules": [
{ "id": "db7bac6c-...", "type": "industry", "value": "higher education", "createdAt": "2026-07-24T21:29:08.089Z" },
{ "id": "6d691a6b-...", "type": "domain", "value": "acme-partners.example", "createdAt": "2026-07-24T21:29:08.089Z" },
{ "id": "5a09ef03-...", "type": "company_domain", "value": "acme-partners.example", "createdAt": "2026-07-24T21:29:08.089Z" }
],
"counts": { "email": 1, "domain": 1, "company_domain": 1, "industry": 1 },
"total": 4,
"filteredTotal": 4,
"limit": 3,
"offset": 0,
"hasMore": true
}
}
```
Rules come back newest first. `limit` defaults to `500` and caps at `5000`. `counts` and `total` describe the whole organization list. For a filtered traversal, follow `data.hasMore` and advance `offset` by the number of returned rules; use `filteredTotal` for the matching population.
## Removing rules
Delete in bulk by rule id, by `type` and `value`, or both at once. Values are normalized the same way as on upload, so you can delete using the exact rows you uploaded without ever tracking ids. Unknown ids and values are ignored.
```bash theme={null}
DELETE /v1/data/suppression-rules
X-API-Key: YOUR_API_KEY
```
```json theme={null}
{ "rules": [{ "type": "domain", "value": "acme-partners.example" }] }
```
```json theme={null}
{ "data": { "deleted": 1, "total": 3 } }
```
Use `DELETE /v1/data/suppression-rules/{ruleId}` when you already hold the id of a single rule.
## Limits
| Limit | Value |
| ----------------------------- | ------------------------------------------------------------- |
| Rules per request | `25,000` |
| Rules stored per organization | No cap |
| Effect on visitor credits | Matching visitors consume no credits from the next sync cycle |
Use the endpoint-specific response and any returned rate-limit headers to pace requests. See [Authentication and errors](/api-reference/authentication-and-errors#rate-limits-and-retries).
## Next steps
* Use [List industries present in your visitor data](/api-reference/visitor-suppression/list-industries-present-in-your-visitor-data) before creating industry rules.
* Read the [Data API guide](/api-reference/data-api) to retrieve visitor data or query qualified visitors.
* Read [Manage pixels](/guides/manage-pixels) to control where tracking runs before applying visitor-level suppression.
# Delete a single suppression rule
Source: https://docs.leadpipe.com/api-reference/visitor-suppression/delete-a-single-suppression-rule
https://api.aws53.cloud/openapi-data.json delete /v1/data/suppression-rules/{ruleId}
Deletes one rule by id. Authenticates via X-API-Key header.
# Delete suppression rules in bulk
Source: https://docs.leadpipe.com/api-reference/visitor-suppression/delete-suppression-rules-in-bulk
https://api.aws53.cloud/openapi-data.json delete /v1/data/suppression-rules
Deletes by rule id, by type+value, or both. Values are normalized the same way as on upload, so you can delete with the exact rows you uploaded without tracking ids. Unknown ids and values are ignored. Authenticates via X-API-Key header.
# List industries present in your visitor data
Source: https://docs.leadpipe.com/api-reference/visitor-suppression/list-industries-present-in-your-visitor-data
https://api.aws53.cloud/openapi-data.json get /v1/data/suppression-rules/industries
Industry rules match the enriched company industry exactly (case-insensitive), so suppressing a value that never appears in your data is a silent no-op. This endpoint returns the industry values actually seen on your identified visitors, most common first, with the visitor count behind each and whether it is already suppressed. Use the returned `value` verbatim when creating `industry` rules. Authenticates via X-API-Key header.
# List suppression rules
Source: https://docs.leadpipe.com/api-reference/visitor-suppression/list-suppression-rules
https://api.aws53.cloud/openapi-data.json get /v1/data/suppression-rules
Returns the organization's suppression rules, newest first. Suppressed visitors are still identified, but they consume no credits and trigger no webhooks or integrations. Paginated: `limit` defaults to 500 and caps at 5000. `counts` and `total` always describe the whole list, not the returned page. Authenticates via X-API-Key header.
# Replace the suppression list
Source: https://docs.leadpipe.com/api-reference/visitor-suppression/replace-the-suppression-list
https://api.aws53.cloud/openapi-data.json put /v1/data/suppression-rules
Destructive sync: every existing rule is deleted and replaced by the submitted set, in one transaction. This is the endpoint to point at a source-of-truth file — re-post the whole list on every run and the stored list matches it exactly. Rules removed here stop suppressing from the next sync cycle onward. Pass `types` to replace only some rule types and leave the rest untouched (e.g. sync your `email` list without disturbing industry rules); send an empty `rules` array with `types` to clear a category. Up to 25,000 rules per call — a list longer than that cannot be replaced atomically, so build it with POST instead. Authenticates via X-API-Key header.
# Upload suppression rules (append)
Source: https://docs.leadpipe.com/api-reference/visitor-suppression/upload-suppression-rules-append
https://api.aws53.cloud/openapi-data.json post /v1/data/suppression-rules
Adds up to 25,000 rules in one call, on top of what is already stored; send more by posting again. There is no cap on how many rules an organization may keep. Values are normalized before storage (lowercased; domains lose scheme, `www.`, path and port), so re-uploading the same list is a no-op. Rows that fail validation come back in `rejected` — every other row is still applied. Rules take effect from the next sync cycle onward; visitors already charged are not refunded. Authenticates via X-API-Key header.
# List privacy-bounded session summaries
Source: https://docs.leadpipe.com/api-reference/visitors/list-privacy-bounded-session-summaries
https://api.aws53.cloud/openapi-data.json get /v1/data/visitors/{visitorId}/sessions
Returns deterministic, cursor-paginated session summaries without detailed events, page sequences, full URLs, query strings, or fragments. `visitorId` is the lowercase SHA-256 value returned as `emailHash` by the visitor list and qualification endpoints. The signed cursor is bound to the API-key organization, visitor, timeframe, optional pixel scope, and frozen `asOf`; do not construct, edit, or reuse it with different filters. Sessions are ordered by start time and stable session identifier, both descending. `limit` defaults to 50 and is capped at 100. An empty page returns an empty `data` array and null `nextCursor`. Recent events can revise a session summary and therefore change its `version` after a short processing delay.
# Look up a company by IP address
Source: https://docs.leadpipe.com/api-reference/visitors/look-up-a-company-by-ip-address
https://api.aws53.cloud/openapi-data.json get /v1/data/company
Look up stored company information for an IPv4 or IPv6 address. Each company result uses one lookup unit; a null result uses none.
See [Lookup usage and limits](/ip-to-company/introduction) for authentication, allowances, and error handling.
# Query qualified visitor data via API key
Source: https://docs.leadpipe.com/api-reference/visitors/query-qualified-visitor-data-via-api-key
https://api.aws53.cloud/openapi-data.json post /v1/data/query
Returns identified people matching either one saved segment or one canonical `ruleAst` for the organization owning the `X-API-Key`; provide exactly one source. `window` overrides the rule window for this request, and `pixelId` restricts matching to one owned pixel. Identity aliases are represented as one person. Results use one-based pagination, are ordered by most recently seen first with a stable identity tie-breaker, and include a frozen traversal boundary and historical-coverage metadata. The qualification-specific rate limit is reported through response headers. This operation reads data and records API-key usage metadata but does not consume visitor-resolution credits.
# Query visitor data via API key
Source: https://docs.leadpipe.com/api-reference/visitors/query-visitor-data-via-api-key
https://api.aws53.cloud/openapi-data.json get /v1/data
Returns resolved identified-person data for the organization owning the `X-API-Key`. Without `email`, the operation returns 50 people per one-based page, newest activity first; with `email`, it returns that person plus a session journey and summary. Identity aliases are represented as one person. `timeframe` supports `today`, `24h`, `3d`, `7d`, `14d`, `30d`, `mtd`, `90d`, `ytd`, and `all`; reads also return a frozen `asOf` and historical-coverage metadata. `domain` and `pixelId` are alternative scope mechanisms and cannot be combined. The read is rate-limited per API key; use the response rate-limit headers for pacing. Recent events and enrichment changes may appear after a short processing delay.
# Ads play
Source: https://docs.leadpipe.com/guides/ads-play
Use Leadpipe data to recover more value from your paid and retargeting workflows
## When this play fits
The ads play fits when your team already spends money to drive traffic and wants to recover more value from visitors who never convert on the first session.
This is often the cleanest starting point for marketing-led teams because it does not require every identified visitor to become a direct outreach record.
## What this play is trying to do
Instead of treating site traffic as a binary outcome of conversion or no conversion, the ads play treats identified traffic as a better signal for audience-building, prioritization, and retargeting.
## Good ads use cases
* Build a tighter retargeting audience from recent high-fit visitors
* Compare visitors from paid campaigns against visitors from organic or direct traffic
* Focus spend on visitors who reached pricing, demo, or product pages
* Exclude low-fit traffic before building follow-up audiences
* Review which sources are bringing the most valuable visitors
## A good rollout
* focus on your highest-value pages or campaigns
* suppress obvious bad-fit traffic
* save a focused view for high-fit visitors
* route that slice into the ad or audience workflow your team already uses
* compare performance against broader retargeting audiences
## Why teams like this play
Marketing teams can start with audience quality and campaign relevance before asking sales to change process.
Source, landing page, and fit give your team a better read on which traffic is worth more attention.
You do not need to action every record individually to get value from the product.
## Teams that usually use this play
* paid media teams
* demand gen teams
* growth teams
* agencies managing campaign traffic
## Best practice
* do not use broad traffic without filtering
* do not ignore source quality
* do not mix very different traffic sources into one audience without reviewing the result
# Agencies and partners
Source: https://docs.leadpipe.com/guides/agencies-and-partners
Use Leadpipe as a repeatable client service
## Why agencies care about Leadpipe
Agencies and partners usually need a repeatable service they can run across multiple clients.
That usually means answering:
* what problem are we solving for clients?
* who owns the workflow after identification?
* how do we keep delivery consistent across accounts?
* how do we package the value cleanly?
## The strongest agency use cases
Recover more value from existing traffic by turning anonymous visits into usable audience or follow-up inputs.
Give clients a filtered stream of named visitors they can act on.
Add identified-visitor reporting to the service you already provide.
Package routing into CRMs, Slack, email, or internal workflows.
## What makes the agency model work
* define one offer clearly
* use consistent naming and setup standards
* narrow traffic before routing it
* choose one reporting cadence
* make the next step obvious for the client
## Good agency offers
* identified visitor reporting
* sales-ready lead routing
* paid media recovery
* CRM or Slack automation for clients
* branded delivery under the agency's own identity
## White-label setup
Confirm the white-label capabilities included in your agreement before promising a branded login or sign-up flow. Agree on client access, billing visibility, organization limits, supported branding, and ownership of downstream connections. The public API reference does not define a complete white-label provisioning contract.
## Next steps
* Read [Run Leadpipe for clients](/guides/run-leadpipe-for-clients) for a practical rollout model.
* Read [What to do with identified visitors](/guides/what-to-do-with-identified-visitors) to choose the right client workflow.
# Use Agent Lipo briefings
Source: https://docs.leadpipe.com/guides/agent-lipo
Review Leadpipe's daily summaries of notable visitor activity
## Overview
Agent Lipo turns recent identified visitor activity into a concise briefing. Open **Agent Lipo > Briefings** to read the latest letter and revisit earlier ones.
![Agent Lipo briefings]()
The briefings list shows when each letter was produced, how many named visits it covers, and whether it contains follow-up items. The latest-letter card also shows its delivery state.
## Review a briefing
1. Open the latest letter.
2. Review the highlighted visitor or account changes.
3. Check the named-visit and follow-up counts for context.
4. Use the underlying visitor data before acting on an individual signal.
Agent Lipo is marked as beta in the dashboard. Its presentation and controls may change.
# Analytics dashboard
Source: https://docs.leadpipe.com/guides/analytics-dashboard
Read traffic, quality, and credit usage from the Leadpipe dashboard
## Overview
The **Analytics Dashboard** gives you the fastest read on whether traffic is flowing, how active it is, and whether the mix looks healthy.
![Analytics dashboard]()
## What the top cards mean
| Card | What it tells you |
| ----------------- | ----------------------------------------------------------------------- |
| `Unique visitors` | How many distinct visitors Leadpipe saw in the selected range |
| `Total sessions` | How many sessions those visitors generated |
| `Total pageviews` | How many pageviews were captured |
| `Credits used` | How many credits were consumed and how much of your allowance is in use |
Use the pixel selector to scope the dashboard to one site. Choose `Today`, `7d`, `30d`, or `90d` to change the reporting window. Turn on **Compare** when you want to compare the selected period with the previous one.
## Charts and breakdowns
This chart helps you see whether activity is stable, rising, or dropping over the selected period. The dashboard also exposes `Volume` and `Quality` views so you can compare raw activity with the health of the traffic mix.
The intent donut breaks visitors into `High`, `Medium`, and `Low` intent buckets for the selected range.
This shows the most common roles appearing in the traffic, which helps you judge whether the audience matches your target buyer.
This shows where visitors are concentrated geographically.
The dashboard can also surface which companies visited, which URLs attracted attention, and where the traffic came from, including tagged sources and common channels such as Google Ads, Facebook, referrals, and direct traffic.
## What to look at first
* Check `Credits used` to make sure the traffic mix is healthy
* Check `Traffic over time` to confirm collection is steady
* Check `Top companies` and `Top job titles` to see whether the right audience is reaching the site
* Check `Top URLs` to understand which pages are pulling the strongest visitor activity
* Check `Source` patterns to see which channels are bringing the best traffic
## What a healthy dashboard review looks like
* traffic is showing up for the right pixel and date range
* sessions and pageviews move in a believable way
* the intent mix matches the kind of traffic you expect
* credits are not being burned on noisy traffic
## Next steps
* Read [Use visitor insights](/guides/use-visitor-insights) when you want to inspect the actual identified records behind the trends.
* Read [Suppress unwanted visitors](/guides/suppress-unwanted-visitors) if the dashboard shows too much noisy traffic.
# Product FAQ
Source: https://docs.leadpipe.com/guides/common-questions
Answers about installation, visitor data, suppression, credits, integrations, and Orbit
## What does Leadpipe identify?
Leadpipe resolves website activity into identified people and available company and contact information. A visitor record is an input to qualification, not a guaranteed sales lead. See [How Leadpipe works](/guides/how-leadpipe-works) and [Data quality](/guides/understanding-data-quality).
## How do I install and verify a pixel?
Create a pixel in **Pixels**, copy **View code**, publish the snippet in the site's ``, and confirm the script loads and the pixel verifies. Follow [Get started](/guides/get-started) for the browser check and expected result.
## Can I use multiple pixels?
Yes. Use separate pixels for different websites or routing needs. Keep each pixel associated with its intended domain. Multiple pixels and saved views do not themselves define team permissions or isolate client accounts. See [Manage pixels](/guides/manage-pixels).
## Can I exclude parts of my site?
Yes. **Page targeting** supports include-only and exclude modes using path prefixes. `includedPaths` and `excludedPaths` are mutually exclusive. See [Path filters](/guides/manage-pixels#path-filters).
## What happens when I create a pixel through the API?
The creation response includes the pixel and its embed `code`. Install the returned snippet in the site's ``. Use the [generated pixel reference](/api-reference/pixels/create-a-pixel-for-a-domain) for required fields.
## Why do some visitors have missing contact details?
Records have different enrichment levels and contact coverage. An identified email may be available while a name, phone number, or company attribute is missing. Review the fields your workflow requires and measure coverage on your own traffic. See [Understanding data quality](/guides/understanding-data-quality).
## What does suppression do?
Suppressed visitors are still identified, but they consume no credits and trigger no webhooks or integrations. Rules apply from the next sync cycle and do not refund earlier charges. See [Suppress unwanted visitors](/guides/suppress-unwanted-visitors).
## Does filtering a view prevent credit usage?
Do not assume that it does. Filters select data for review or supported automation workflows; suppression controls credits and automation triggers for matching visitors. Compare [the three controls](/guides/suppress-unwanted-visitors#choose-the-right-control).
## What is a segment?
A segment is a saved filter definition. Reopen it from **Saved view** and reuse it in supported integrations and webhooks. It is not a separate organization or a permission boundary. See [Filters and segments](/guides/filter-save-views-and-segments).
## How do intent levels work?
Website visitor data can carry `high`, `medium`, or `low` intent labels. The current public API schema does not define their exact calculation thresholds. Review the underlying activity and your qualification criteria before using a label in automation. Orbit topic scores are a separate signal. See [Identification and Orbit](/guides/how-leadpipe-works#identification-and-orbit).
## Will repeat visits create duplicate CRM contacts?
Leadpipe's webhook send frequency and your CRM's contact matching are separate controls. **Once per visitor** sends once for each qualifying visitor; other triggers can deliver updates. Verify the destination's create/update behavior with a test record before enabling broad delivery. See [Integration verification](/guides/set-up-integrations#verify-the-first-delivery).
## Should I use an integration, webhook, API, or CSV?
Use a listed native integration for its supported connection flow, a webhook for event delivery to your receiver, an API for backend reads, and CSV for manual review or import. Check [Delivery options](/guides/integrations-and-delivery-options) for tradeoffs and a verification checklist.
## Where can I check credits and trial terms?
Check the billing area for the current offer and account status for usage. Visitor credits and Orbit audience access are different categories. See [Credits and account status](/guides/credits-and-account-status) and the [trial scorecard](/guides/trial-success-guide#trial-scorecard).
## What is Orbit?
Orbit builds audiences from topic research signals, including people who have not visited your site. Preview a definition, save an audience, and run it to retrieve a result snapshot. See [Orbit API overview](/orbit-api/introduction).
## Why does my Orbit preview differ from my export?
Previews use the latest available data and return masked samples. Exports use a completed run snapshot. Also inspect the CSV truncation headers: direct exports have a row cap. See [Stats and export](/orbit-api/stats-and-export).
## Can I fetch data programmatically?
Yes. Use an organization API key for the documented Identification and Orbit API-key operations. Start with the [API quickstart](/api-reference/quickstart). Check [Authentication and errors](/api-reference/authentication-and-errors) for the unresolved Orbit destination access discrepancy.
## Can I look up a company from an IP address?
Yes. Use `GET /v1/data/company` with one IPv4 or IPv6 address and an active organization API key. Your organization must be eligible. It returns stored company information, not a person or a visitor journey. Company results consume a separate lookup allowance; a null result consumes none. See [IP to company API](/ip-to-company/introduction).
## How do I manage team access or client delivery?
Open **Settings > Team** for the controls available to your role. For agencies, confirm client login, billing visibility, account separation, and commercial terms before offering a branded service. See [Team and account](/guides/manage-your-team-and-account) and [Run Leadpipe for clients](/guides/run-leadpipe-for-clients).
## Can AI tools answer questions from these docs?
Yes. Connect the public documentation MCP at `https://docs.leadpipe.com/mcp` or use the page menu to copy Markdown. This is separate from the authenticated product MCP in **Settings**. See [Search docs with AI](/guides/search-docs-with-ai).
For missing data or delivery failures, use [Troubleshooting](/guides/troubleshooting).
# Geography and privacy
Source: https://docs.leadpipe.com/guides/compliance-and-geography
Check geographic coverage and the information needed to review your intended use of visitor data
Before rollout, confirm that Leadpipe supports the people and locations you intend to identify and that your proposed downstream workflow fits your organization's requirements.
## Geographic coverage
Person-level location in [Visitor Insights](/guides/use-visitor-insights) is primarily described for the United States. A person's location and their employer's location are different fields; a non-US company does not establish support for identifying visitors in that company's country.
These docs do not establish country-by-country availability or a European identification offering. Confirm the specific countries and product area with Leadpipe before planning a deployment outside the documented scope.
## Review your intended use
Give your privacy or legal reviewer the actual installation scope, contact fields, and destination workflow. Request the current privacy documentation and contractual terms from your Leadpipe contact, including any applicable information about data sources, retention, deletion requests, and subprocessors.
Identification and contact availability do not themselves establish permission for every downstream use. Review email, advertising, and sales workflows separately with the responsible team.
## Product controls
[Page targeting](/guides/manage-pixels#path-filters) limits where the pixel runs. [Suppression](/guides/suppress-unwanted-visitors) prevents matching visitors from consuming credits or triggering integrations and webhooks from the next sync cycle. Suppression is not a data-deletion request and does not recall previously delivered records.
Use [team and account controls](/guides/manage-your-team-and-account) to manage access, and keep API keys and authenticated MCP configurations private.
# Credits and account status
Source: https://docs.leadpipe.com/guides/credits-and-account-status
Check account health and distinguish visitor credits, company-lookup allowance, and Orbit access
Use your billing area for the current plan and commercial terms. Use account status to check organization health, credit usage, pixel counts, and Orbit audience slots.
## Check your organization
Open the account and billing areas in **Settings**. Developers can retrieve the same categories of status through [GET /v1/data/account](/api-reference/account/account-health-and-credit-status).
| Status area | What to check |
| ------------ | ---------------------------------------------------------------------- |
| Organization | Status and the `healthy` indicator |
| Credits | Used, limit, remaining, percent used, and reset time when available |
| Pixels | Total, active, and paused counts |
| Intent | Audience slots, used slots, available slots, and status when available |
Some account-status values can be `null`. Treat these as unavailable values; do not substitute zero or assume unlimited access.
## Control unwanted usage
[Suppression](/guides/suppress-unwanted-visitors) prevents matching visitors from consuming credits or triggering webhooks and integrations, starting with the next sync cycle. It does not refund visitors already charged.
[Page targeting](/guides/manage-pixels#path-filters) controls which pages the pixel tracks. [Filters and segments](/guides/filter-save-views-and-segments) narrow a view or automation audience. A filtered-out row is not automatically suppressed.
The [qualification query](/api-reference/visitors/query-qualified-visitor-data-via-api-key) reads existing visitor data and does not consume visitor-resolution credits.
## Company-lookup allowance
[IP to company lookups](/ip-to-company/introduction#track-your-company-lookup-allowance) use a separate organization-wide allowance. Every company result consumes one unit, including repeat lookups of the same IP; `data: null` consumes none. Read the lookup response's `meta` counters for this balance. Other products do not consume the company-lookup allowance.
## Orbit access
An Orbit audience is a saved definition. Activating it requires available audience access; obtaining contacts requires a run. Website visitor credit balances and Orbit audience slots are separate fields in account status.
Deleting an Orbit audience does not restore a consumed one-shot trial. Review [audience lifecycle and deletion](/orbit-api/manage-audiences) before removing one.
## Pricing and trial questions
For your exact price, billing period, trial expiry, included features, and available extensions, check the current offer shown for your organization or confirm with your Leadpipe contact. Estimate value with the [trial scorecard](/guides/trial-success-guide#trial-scorecard), using actual costs and measured outcomes.
# Filter, save views, and segments
Source: https://docs.leadpipe.com/guides/filter-save-views-and-segments
Turn raw visitor data into reusable workflows
## Overview
Filters help you narrow the visitor table. Save a reusable filter set as a segment, then reopen it from the **Saved view** selector or use it in automations such as webhooks and integrations.
![Visitor Insights filters]()
## Common filter areas
Leadpipe groups filters around the decisions your team needs to make:
* `Professional & Company`
* `Location`
* `Acquisition`
* `Intent`
* `Enrichment`
* `Contact & Recency`
Each group lets you either `Include` or `Exclude` matching traffic. That makes the panel useful both for finding good-fit visitors and removing noise.
## Recommended workflow
Build the view around a concrete question, such as who viewed pricing recently or which visitors came from a specific channel.
Keep the first version narrow and understandable. It is easier to refine a focused view than untangle an overloaded one.
Select **Save View**, name the segment, and add an optional description. You and your team can then return to the same working set without rebuilding its filters.
![Save as Segment dialog]()
The dialog reports when a selected filter cannot yet be saved in a canonical segment. Remove the unsupported filter or keep working with the unsaved result set.
## Working with saved views and segments
Once you save a segment, select it from the **Saved view** area without rebuilding the logic each time.
![Saved segments selector]()
That makes it easier to:
* review the same audience every day
* compare different audience slices quickly
* reuse one saved segment across webhooks or integrations
## Good first segments
* Recent pricing page visitors
* High-intent visitors from paid or social sources
* Visitors from target industries or company sizes
* Visitors from one specific pixel or domain
# Get started
Source: https://docs.leadpipe.com/guides/get-started
Install and verify a Leadpipe pixel, review identified visitors, and confirm your first delivery
Set up one website first. You have finished when the pixel is verified, you can review visitor data, and you have checked one downstream output.
## Before you start
You need access to a Leadpipe organization, permission to create a pixel, and a way to edit your website's HTML or shared header. If someone else manages the site, send them the installation steps below and the snippet from **Pixels**.
Open **Pixels > Create Pixel**. Enter a recognizable name and the website domain without a protocol or path, such as `example.com`.
Open the pixel's **View code** action. Copy the complete snippet generated for that pixel.
```html Example structure — use the snippet from your account theme={null}
```
The pixel identifier comes from Leadpipe. It is not your API key.
Add the snippet inside the site's `` element. A shared header lets it load on the pages you want to track. Publish the website change.
For WordPress or another site builder, use your site's supported header-code mechanism. The exact control depends on your theme, host, and plugins; your site administrator can install the same snippet.
Open a published page on the configured domain. In browser developer tools, open **Network**, reload the page, and search for your pixel ID or `leadpipe.aws53.cloud`.
Confirm the script request succeeds. If it is missing or blocked, follow [pixel troubleshooting](/guides/troubleshooting#the-pixel-is-unverified).
Return to **Pixels** and check verification and recent activity. Use the verify action if available.
Open **Visitor Insights**, choose the correct pixel and date range, and clear saved filters for the first check.
A successful script load confirms installation; it does not guarantee that your test visit resolves to a person. Recent events and enrichment can take a short time to appear. See [No visitors are showing up](/guides/troubleshooting#no-visitors-are-showing-up) if the view remains empty.
Add [suppression rules](/guides/suppress-unwanted-visitors) for internal traffic and known customers before enabling delivery. Use [page targeting](/guides/manage-pixels#path-filters) if only selected pages should be tracked.
Save a focused [segment](/guides/filter-save-views-and-segments), then choose an [integration, webhook, API, or CSV export](/guides/integrations-and-delivery-options). Inspect a delivered or exported record in the destination and confirm the audience, fields, and owner are correct.
## Verify your setup
* The pixel belongs to the intended domain and shows as verified.
* The published pages load the correct pixel script.
* Visitor data appears under the intended pixel and date range.
* Suppression and page targeting match your requirements.
* One output contains the expected records, and someone owns the next step.
Use the [trial scorecard](/guides/trial-success-guide#trial-scorecard) to measure results after setup.
# How Leadpipe works
Source: https://docs.leadpipe.com/guides/how-leadpipe-works
Understand what Leadpipe identifies, what the data means, and how teams use it
## The simple version
Leadpipe helps you identify website visitors, understand which traffic matters, and move that traffic into a useful workflow.
That usually means three things happen:
1. A pixel collects the visit on the right site.
2. Leadpipe resolves that traffic into people and companies.
3. Your team filters that data and sends the right visitors into sales, ads, email, or reporting workflows.
## Key terms
| Term | Meaning | Use it for |
| -------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Organization | The account boundary for your team, API key, pixels, and data | Check which account owns a resource |
| Pixel | The tracking snippet and configuration for a website | Control collection and page targeting |
| Identified visitor | A resolved person with available contact and activity data | Review who visited; identification alone does not establish sales qualification |
| Session | A group of visitor activity represented in the session data | Review repeat activity and visit context |
| Filter | A condition applied to the current visitor view | Narrow what you inspect |
| Segment / saved view | A saved filter definition you can reopen and reuse in supported automations | Keep a repeatable qualification rule |
| Suppression rule | A rule that prevents matched visitors from consuming credits or triggering integrations and webhooks | Exclude known people, domains, or industries from those actions |
| Orbit audience | A saved definition of topics, score thresholds, and filters | Find people with topic research signals |
| Orbit run | A saved result snapshot for an audience | Retrieve, compare, or export one set of results |
A saved view narrows data; it does not establish a permission boundary. Use organization and team controls for access management.
## Identification and Orbit
Identification starts with visits to your website. Orbit starts with research topics and can include people who have never visited your site. Orbit can also [show audience members who visited your site](/orbit-api/visitor-overlap).
Website intent labels and Orbit topic scores describe different signals. Do not treat either as proof that someone is ready to buy. Review recency, activity, and fit before acting.
## What Leadpipe is actually helping you answer
Leadpipe helps you understand which people and companies were on your site.
Recency, landing page, repeat activity, and intent help your team prioritize what matters.
Filters, segments, and suppression help you keep the useful traffic and remove the rest.
Leadpipe is strongest when the data flows into a clear next step.
## What a useful Leadpipe workflow looks like
A strong Leadpipe setup usually looks like this:
* track the right site with the right pixel
* review identified visitors in **Visitor Insights**
* suppress obvious noise and bad-fit traffic
* save one focused view for the team that will use the data
* route that slice into one output such as a CRM, Slack, webhook, or export
## What to expect from the data
Some records will be richer than others. The most useful way to judge Leadpipe is by whether the traffic is actionable for your team.
Read [Understanding data quality](/guides/understanding-data-quality) for a more detailed explanation.
## Where to go next
* Read [Get started](/guides/get-started) to install your first pixel and confirm data is flowing.
* Read [What to do with identified visitors](/guides/what-to-do-with-identified-visitors) to choose the right operating play.
* Read [Trial success guide](/guides/trial-success-guide) to evaluate value quickly and cleanly.
# Integrations and delivery options
Source: https://docs.leadpipe.com/guides/integrations-and-delivery-options
Choose the right path for getting Leadpipe data into the rest of your stack
## Pick the simplest path that fits your workflow
Customers usually ask the same question in different ways: do we need a native integration, can we use a webhook, or should we start with a CSV?
The right answer depends on how mature the workflow is and how much control your team needs.
| Option | Best when | Tradeoff |
| -------------------- | ----------------------------------------------------------------- | ------------------------------------------------------- |
| Native integration | You want the fastest path into a common downstream tool | Less flexible than building your own flow |
| Webhook | You need a custom workflow or a tool without a direct integration | Requires a more technical setup |
| API | Your backend needs to pull visitor data or a saved Orbit run | Requires authentication, pagination, and error handling |
| CSV or manual export | You are validating value or handling lower volume | More manual and less real-time |
## How to choose
Choose this when the destination already exists in Leadpipe and your team wants the shortest path to operational use.
Choose this when your team needs logic, branching, or delivery into an internal system or unsupported tool.
Choose this when you are still proving value, validating fit, or testing a workflow before investing in automation.
## Check whether your destination is supported
Open **Integrations**, search for the app, and inspect its connection requirements. If it is listed, follow [Set up integrations](/guides/set-up-integrations). If it is absent, evaluate an HTTPS webhook receiver, your own API client, or a CSV import supported by the destination.
A webhook can feed an automation platform that accepts incoming webhooks. That does not establish a native Leadpipe connector for every platform. Confirm the receiver, field mapping, and destination requirements before committing to the workflow.
## Verify the data contract
Before enabling live automation, compare a test or exported record with the destination's required fields. Confirm:
* Which email is used as the contact identifier.
* Whether repeat data updates a contact or creates another record.
* Which activity fields arrive and whether you need separate API session reads.
* Whether the selected segment, pixel, and send frequency match the intended audience.
Identification API responses and webhook events have different envelopes. Orbit results belong to a completed run and have their own schema. Do not reuse a parser without checking the corresponding reference or test payload.
## A practical rollout order
1. Start with the destination your team already uses every day.
2. Push a narrow slice of high-signal traffic first.
3. Confirm the records are useful in that destination.
4. Add more destinations only after the first workflow is stable.
## Common patterns
* CRM first for sales teams
* Slack first for visibility and fast internal testing
* CSV first for a trial or lightweight review process
* Webhook first for a custom ops workflow
## Next steps
* Read [Set up integrations](/guides/set-up-integrations) for destination-level setup guidance.
* Read [Set up webhooks](/guides/set-up-webhooks) if you need a more flexible delivery path.
# Lifecycle email play
Source: https://docs.leadpipe.com/guides/lifecycle-email-play
Use Leadpipe data in email, nurture, and outbound workflows that already exist
## When this play fits
Choose the lifecycle email play when your team already has a follow-up motion in an email or outbound system and needs better inputs, not a brand-new process.
This play often works well for:
* marketing teams running nurture programs
* outbound teams using sequencers
* operators who want a filtered list rather than a live firehose
## Good lifecycle and outbound use cases
* Send a filtered audience into Klaviyo or another lifecycle tool
* Build a daily outbound list for a sequencer
* Follow up on recent visitors from one target segment
* Create a recurring export for manual outreach review
* Route one saved segment into a nurture workflow
## How to run it well
1. Start with a narrow audience your team would genuinely want to contact.
2. Use filters, segments, and suppression before the data leaves Leadpipe.
3. Send that audience into one email or outbound destination first.
4. Review both quality and response, not just volume.
## The key principle
Leadpipe gives your team better inputs for email, nurture, and outbound workflows.
# Manage pixels
Source: https://docs.leadpipe.com/guides/manage-pixels
Create, verify, and control Leadpipe tracking pixels
## Overview
Use **Pixels** to control where Leadpipe collects data and how each tracked site behaves.
![Pixels]()
Each pixel gives you a place to manage:
* Pixel name and domain
* Installation status and recent activity
* Page targeting
* Pixel actions
The page also gives you search, status filtering, and a top-level **Create Pixel** action for adding new sites quickly.
## Core tasks
Use **Create Pixel** when you want to start tracking a new site. Enter a recognizable name and the website domain without a protocol or path.
Open the pixel code, copy it, and place it in the header of the site you want to track.
Track all pages, only selected path prefixes, or every page except selected path prefixes.
## Basic install flow
1. Create the pixel for the site or domain you want to track.
![Create Pixel dialog]()
2. Open `View code`.
3. Copy the snippet.
![Pixel installation dialog]()
4. Paste it into the site header.
5. Return to **Pixels** and confirm the pixel verifies.
If you only want to track part of the site, configure **Page targeting**.
## Add attribution to a pixel
Add query parameters to the end of your pixel script URL when you need to associate identified visitors with a client, campaign, source, or another internal label.
When Leadpipe identifies a visitor, it includes these attribution values in the webhook payload and the Data API's `customAttribution` field. The dashboard continues to show all visitor activity.
### Basic format
The standard pixel does not include attribution parameters:
```html Standard pixel theme={null}
```
Add `?key=value` after `.js` to include the first attribution value:
```html Pixel with attribution theme={null}
```
### Track a single client
Use a `client` parameter to identify which client's website produced the visitor.
```html theme={null}
```
The webhook payload includes `client = bigco`.
### Track a client and campaign
Use `&` to add another parameter.
```html theme={null}
```
The webhook payload includes `client = acme` and `campaign = spring2026`.
### Track multiple attributes
Add more parameters when your routing or reporting workflow needs additional context.
```html theme={null}
```
The webhook payload includes `client = acme`, `source = facebook`, and `vertical = ecom`.
### Use custom parameter names
Parameter names are flexible. Use labels that match your workflow.
```html theme={null}
```
The webhook payload includes `account = demo123` and `rep = john`.
### Attribution parameter rules
* Start the first parameter with `?` and separate each additional parameter with `&`.
* Use short, URL-safe parameter names and values. Prefer letters, numbers, hyphens, and underscores.
* Do not use spaces. Use `my-client` instead of `my client`.
* Choose parameter names that match your routing and reporting workflow.
* Use attribution labels only. Do not put API keys, secrets, or sensitive personal data in the pixel URL.
See [Passing partner-specific data through the pixel](/api-reference/data-api#passing-partner-specific-data-through-the-pixel) for the `customAttribution` response shape and Data API availability.
## Path filters
Open a pixel's **Page targeting** control to choose where it runs.
![Page targeting options]()
Leadpipe supports these modes:
| Dashboard option | API field | Behavior |
| ---------------- | --------------- | ---------------------------------------------- |
| `All pages` | — | Track every page |
| `Only these` | `includedPaths` | Track only matching path prefixes |
| `Except these` | `excludedPaths` | Track every page except matching path prefixes |
These two modes are mutually exclusive. A pixel should use one or the other.
Use allowlist mode when only a few high-value paths should be tracked. Use denylist mode when the pixel should fire broadly but skip low-value areas like blogs, careers pages, or support content.
![Include-only page targeting]()
## What the table columns mean
| Column | What it means |
| ---------------- | ------------------------------------------------------------- |
| `Pixel` | The pixel name and domain it belongs to |
| `Page targeting` | Whether the pixel runs on all pages or selected path prefixes |
| `Install` | Whether the pixel still needs installation attention |
| `Activity` | Recent collection activity |
If you are working through the API, the pixel list also includes `pausedReason`, which explains why a pixel is paused.
## Delete a pixel
Open the row action menu and select **Delete pixel**.
![Delete pixel action]()
Deleting a pixel is destructive. Confirm that no live site or downstream workflow still depends on it before you continue.
## When to use multiple pixels
Use separate pixels when you need to split tracking by:
* Brand
* Domain
* Team ownership
* Automation routing
This keeps reporting and downstream automations easier to reason about.
## Keep your pixel setup clean
* Name pixels clearly
* Match each pixel to the correct domain
* Review paused and unverified pixels regularly
* Add exclusions when internal or irrelevant paths distort the data
* Use separate pixels when different sites need different routing or reporting
# Manage your team and account
Source: https://docs.leadpipe.com/guides/manage-your-team-and-account
Control access, security, developer tools, billing, and account-level settings
## Overview
Leadpipe account management lives under **Settings** and related admin areas.
This is where you manage:
* Your profile and organization details
* Team access
* Billing
* API keys
* MCP setup
* Security controls
## API key
Open **Settings > API Keys** to manage customer API access. Your role must have permission to view or change API keys.
Regenerating the key invalidates the current one, so any scripts or downstream systems using it need to be updated immediately.
For exact auth requirements, use the API docs rather than relying on the settings page alone.
## MCP
Open **Settings > MCP** for setup instructions tailored to Claude, ChatGPT, Cursor, and other MCP-compatible apps.
![Leadpipe MCP settings]()
The setup embeds your Leadpipe API key in the selected client's configuration. Treat that configuration as a secret: do not commit it to source control or share it in screenshots.
## Visitor suppression
![Visitor suppression]()
The current suppression UI supports these rule types:
* `Email`
* `Email domain`
* `Company domain`
* `Industry`
The screen also indicates that suppression values are normalized before matching, including lowercasing and trimming, and stripping leading `@` and `www.` where relevant.
Use [visitor suppression](/guides/suppress-unwanted-visitors) to prevent matching visitors from consuming credits or triggering webhooks and integrations. Suppressed visitors are still identified.
## Security
![Security]()
The **Security** screen displays tabs for:
* `2FA`
* `Sessions`
* `Logs`
Two-factor authentication can be enabled from this page. Use the other tabs when those controls are available to your role and organization.
## Team
Open **Settings > Team** to review access and invite users. The controls available to you depend on your role.
## Billing
The billing area shows the current plan and the options available to your organization.
Because plans and pricing can change, the in-app billing screen should be treated as the current source of truth.
## Good admin habits
* Limit access to the people who need it
* Protect the API key and rotate it deliberately
* Keep MCP client configurations out of source control
# Run Leadpipe for clients
Source: https://docs.leadpipe.com/guides/run-leadpipe-for-clients
Create a repeatable operating model for client delivery
## Start with a standard client rollout
Use the same basic rollout shape each time:
1. Define the client's ICP and what traffic should count as valuable.
2. Install the right pixel on the right domain.
3. Suppress known noise early.
4. Save one focused view or segment.
5. Route the data into one agreed destination.
6. Review the output on a regular cadence.
## Decide what you are actually delivering
Best when the client wants visibility first and is not ready for heavy workflow changes.
Best when the client has a team that can act on named visitors quickly.
Best when the client wants better audience quality and campaign follow-up.
Best when you already own the client's routing and downstream systems.
## Good client workflows
* a weekly identified visitor report
* a Slack feed for high-intent traffic
* CRM routing for qualified visitors
* a filtered export for client outreach
* a paid-traffic review workflow for agencies running ads
* a branded client experience when included in your agency agreement
## Confirm account separation and ownership
Use an explicit organization and API-key ownership model for each client. Pixel names, attribution labels, and saved views organize data; they are not substitutes for access controls.
Before rollout, confirm who can log in, which data they can see, who sees billing, who owns each integration account, and who handles offboarding. Verify these controls with the intended client role before sharing access.
## What to standardize internally
* naming conventions for pixels and segments
* who approves suppression rules
* which destination is primary
* what the client sees in reports
* what counts as a successful month or trial
## What to avoid
* building a different operating model for every client
* routing raw traffic without qualification
* promising a workflow that the client will not actually use
## Good companion guides
* [Sales play](/guides/sales-play)
* [Ads play](/guides/ads-play)
* [Trial success guide](/guides/trial-success-guide)
# Sales play
Source: https://docs.leadpipe.com/guides/sales-play
Use Leadpipe to surface high-fit visitors for fast sales follow-up
## When this play fits
The sales play works best when your team already has a CRM, clear ownership, and a habit of acting quickly on buying signals.
This is the strongest first play for teams that care about:
* named visitors
* account-level prioritization
* recent buying signals
* direct follow-up by an SDR, AE, or founder
## Good sales use cases
* Route pricing-page visitors into your CRM
* Alert reps when target accounts return to the site
* Build a daily list of recent high-intent visitors
* Give founders a short call list from one saved view
* Prioritize named visitors from specific industries, company sizes, or locations
## How the play works
Start with the ICP, industries, company size, role, or intent signals your team actually cares about.
Remove customers, competitors, internal traffic, and other low-value segments before routing anything downstream.
Build a repeatable slice that your team can trust.
This can be a direct integration, webhook, Slack alert, or export depending on your setup.
Track whether the records are workable, how fast reps act, and whether the visits create meetings or opportunities.
## What makes this play work
* recency matters
* narrow slices beat broad dumps
* ownership needs to be clear
* the team needs a script for what to do with the signal
## Teams that usually use this play
* SDR teams
* AE teams working named accounts
* founder-led sales teams
* agencies handing off leads to clients
## Best practice
Start with fewer, better visitors and expand once the workflow proves itself.
# Search docs with AI
Source: https://docs.leadpipe.com/guides/search-docs-with-ai
Connect an AI tool to the public Leadpipe documentation and distinguish docs search from product access
Use the documentation MCP server to let an AI tool search Leadpipe's published guides and API references.
```text theme={null}
https://docs.leadpipe.com/mcp
```
The docs search server is public and does not need your organization API key. It provides documentation context; it does not retrieve your private visitor data or manage pixels and audiences.
## Connect a client
In your MCP client's settings, add a remote HTTP server with the URL above. For Codex CLI, run:
```bash theme={null}
codex mcp add leadpipe-docs --url https://docs.leadpipe.com/mcp
```
Start a new session after changing the configuration, then ask the tool to search the Leadpipe docs and cite the page it used.
## Ask a useful question
Include the product area, your intended result, and any error status. For example:
```text theme={null}
Using the Leadpipe docs, explain the difference between suppression and a saved
segment. Which one prevents credits and webhook triggers? Cite the source page.
```
For API questions, include the method and path. Ask for the documented request shape and expected response. If a source does not establish a behavior, ask the tool to identify what needs confirmation.
## Read pages as Markdown
Use the page's contextual menu to copy its content or view it as Markdown. The public [llms.txt index](https://docs.leadpipe.com/llms.txt) lists documentation pages for tools that consume Markdown.
## Access your Leadpipe account through MCP
To work with account data, use **Settings > MCP** in Leadpipe and follow the client-specific setup shown there. That authenticated product connection is separate from the public docs server. Keep its API key and configuration private.
See [Manage your team and account](/guides/manage-your-team-and-account#mcp) for product MCP setup.
# Set up integrations
Source: https://docs.leadpipe.com/guides/set-up-integrations
Send Leadpipe visitor data into the tools your team already uses
## Overview
Integrations let you route identified visitors into downstream systems without exporting data manually.
![Integrations]()
If you are still deciding how data should leave Leadpipe, start with [Integrations and delivery options](/guides/integrations-and-delivery-options). That guide explains when to use a native integration, a webhook, or a manual export.
The page separates connected integrations from available apps. Connected cards show their current state and delivery details. Available apps support search and category filtering, and each app has its own **Connect** action. Some integrations also show app-specific constraints directly in the list, such as `One HubSpot connection per org`.
Leadpipe supports a broad mix of destinations, including:
* CRMs such as HubSpot, Salesforce, Zoho CRM, Pipedrive, Freshsales, Close, Copper, Insightly, Nutshell, and GoHighLevel
* Messaging and notification tools such as Slack
* Spreadsheets and databases such as Google Sheets, Airtable, and Notion
* Marketing and lifecycle tools such as Mailchimp, Klaviyo, Omnisend, ActiveCampaign, Customer.io, and Monday.com
* Outbound tools such as Smartlead, SmartReach, and Instantly
## Recommended rollout
Start with the system your team already checks every day.
Do not push everything at once. Start with a narrower audience so you can inspect quality before scaling up.
If the destination flow is pixel-specific, choose the pixel you want the integration to use.
Confirm the right contacts are being created or updated and that the timing matches your workflow.
Once the first integration is stable, add more destinations where the same visitor data should flow.
## Verify the first delivery
1. Open the selected app in **Integrations** and complete its **Connect** flow with an account that can write to the destination.
2. Select the supported segment and pixel controls for that connection.
3. Inspect one qualifying record in Leadpipe and in the destination. Check email, company, source, and the fields your team needs.
4. Check the destination's duplicate-handling behavior before increasing volume. **Once per visitor** delivery and CRM contact deduplication are separate controls.
5. Review connection status and recent delivery details. Follow [delivery troubleshooting](/guides/troubleshooting#a-webhook-or-integration-is-not-delivering) if records are missing.
App-specific field mappings, object types, and connection limits differ. Use the available app's setup controls to verify them; the catalog listing alone does not establish those behaviors.
## Good destination patterns
Use a CRM first when a sales team needs named visitors to show up in an existing pipeline or lead-routing process.
Use Slack when you want fast visibility before you build a heavier workflow.
Use Google Sheets, Airtable, or Notion when you need a lightweight review layer before committing to automation.
Use these when your team already has a clear follow-up process and knows what should happen after identification.
## Good first use cases
* Send qualified visitors to a CRM
* Post high-intent activity into Slack
* Build lightweight reporting in Google Sheets or Airtable
* Feed outbound systems with filtered prospect lists
# Set up webhooks
Source: https://docs.leadpipe.com/guides/set-up-webhooks
Stream visitor identifications to your own systems
## Overview
Webhooks let you send Leadpipe events to your own endpoints when visitors are identified or updated.
![Webhooks]()
Each webhook can be configured around:
* A destination URL
* A segment
* A pixel
* A trigger
* Delivery status and success rate
Select **Create Webhook**, enter an HTTPS destination, then choose the segment, pixel, and send frequency.
![Create Webhook dialog]()
The table also shows delivery volume, success rate, and whether a webhook has been marked `Inactive` or `Auto-disabled`.
## Trigger types
Use this when you want one delivery for each qualifying visitor. Existing webhook cards label this trigger `First Match`.
Use this when the downstream system should receive qualifying visitor updates after the first delivery.
## Recommended workflow
Limit the first webhook to a clear slice of traffic so you can validate the payloads and delivery behavior.
Choose the send frequency that matches how your downstream system handles repeat deliveries.
Review deliveries, success rate, and inactive status before scaling the webhook to more traffic.
## Testing and delivery history
Once the webhook is configured, you can send a test payload and review delivery history to confirm the endpoint is receiving data correctly.
If a webhook shows **Auto-disabled**, review its failed deliveries and fix the receiving endpoint before enabling it again.
## Verify your receiver
1. Send a test from Leadpipe and save the redacted request body and response status in your own test logs.
2. Check the event envelope and visitor fields in that payload. The Identification API uses different response wrappers, so an API response is not a substitute webhook fixture.
3. Confirm the receiver accepts the payload and the destination record contains the expected fields.
4. Test how your own receiver handles the same payload twice. Use an upsert or deduplication policy appropriate to the destination.
5. Inspect one live delivery to verify segment, pixel, and trigger behavior. A successful synthetic test does not prove a visitor qualifies for live delivery.
Before relying on unattended delivery, confirm the webhook's authentication or signature mechanism, retry schedule, timeout, and replay controls through your Leadpipe support channel. This guide does not establish those guarantees. Orbit destination signing and delivery operations have a separate contract.
## Add attribution to webhook payloads
Add custom parameters to your pixel script when your webhook needs to identify the client, campaign, source, or another label associated with a visitor.
Leadpipe includes those values in the webhook payload when it identifies the visitor. See [Add attribution to a pixel](/guides/manage-pixels#add-attribution-to-a-pixel) for the format, rules, and examples.
## When to use webhooks instead of integrations
Use webhooks when:
* You need a custom destination
* You want full control over downstream processing
* An existing integration does not fit your workflow
## How to read webhook status
| Field | What it tells you |
| ------------ | ------------------------------------------------------------------ |
| `Trigger` | Whether the webhook sends on `First Match` or `Every Update` |
| `Status` | Whether the webhook is active, inactive, or has been auto-disabled |
| `Deliveries` | How many payload attempts have been made |
| `Success` | The observed success rate for that webhook |
# Suppress unwanted visitors
Source: https://docs.leadpipe.com/guides/suppress-unwanted-visitors
Prevent internal, customer, or irrelevant traffic from affecting Leadpipe
## Overview
Suppressed visitors are still identified, but they consume no credits and trigger no webhooks or integrations. Rules apply from the next sync cycle; they do not refund credits already used.
![Visitor suppression settings]()
Use suppression rules for:
* Internal traffic
* Known customers
* Competitors
* Industries you do not want to target
## Choose the right control
| Control | What it changes | Use it when |
| ----------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Pixel page targeting | Where the pixel runs | Track only selected page prefixes, or exclude specific areas |
| Filter or saved segment | Which visitors you review or select for supported automations | Narrow by ICP, activity, or contact availability |
| Suppression rule | Whether matched visitors consume credits or trigger webhooks and integrations | Exclude known people, email domains, companies, or industries |
Filtering a table is not a guarantee that excluded rows will not consume credits. Suppression does not delete visitor data or remove records already delivered to another tool.
## Add and verify rules
1. Open **Settings > Visitor Suppression**.
2. Choose the rule type and enter the value you want to exclude.
3. For industry rules, use a value present in your visitor data. The [industries endpoint](/api-reference/visitor-suppression) returns valid values; a guessed label may match nobody.
4. Save and review the rule list. Allow the next sync cycle to apply the rules before checking new automation activity.
Use an email domain for the address domain and a company domain for the enriched employer domain. These can differ for a person using a personal email address.
## Supported rule types
* Email
* Email domain
* Company domain
* Industry
## When to use suppression
Use suppression when:
* Your own team visits the site frequently
* Existing customers should not trigger outbound workflows
* Competitor traffic adds noise
* Certain industries are not relevant for your sales motion
## Manage suppression programmatically
You can also manage these rules through the API, which is the better path when your exclusion list lives in a CRM export or a file your team already maintains. See [Visitor suppression](/api-reference/visitor-suppression) for uploading in bulk, syncing a source-of-truth list, and checking which industry values actually appear in your data.
## Best practices
* Add internal domains early
* Add known customer domains before you turn on automations
* Review the rule list regularly
* Keep the list focused on traffic you truly want to exclude
* Add rules before the unwanted traffic reaches downstream automations
# Trial success guide
Source: https://docs.leadpipe.com/guides/trial-success-guide
Run a Leadpipe trial in a way that proves real value quickly
## What a good trial should answer
A good trial should not just prove that Leadpipe can collect data. It should prove that your team can turn that data into something commercially useful.
By the end of a trial, you should be able to answer:
* did the data fit our traffic?
* did we find enough useful visitors?
* did we route them somewhere useful?
* did the workflow create meetings, replies, audiences, or another real outcome?
## The best trial shape
Start narrow so the data is easier to judge.
Do not let bad-fit traffic distort the trial.
Be specific about who should count as a good result.
Pick one workflow such as CRM routing, Slack alerts, lifecycle email, or export review.
The right question is not just how many visitors were identified. It is whether the identified visitors were useful.
## What to measure
| Measure | Why it matters |
| ----------------------------- | ----------------------------------------------------- |
| Verified pixel and data flow | Confirms the setup is real |
| Volume of identified visitors | Shows whether the traffic is large enough to evaluate |
| Fit of identified visitors | Shows whether the product matches your market |
| Actionability of records | Shows whether the data is usable in your workflow |
| Downstream result | Shows whether the workflow creates business value |
## Trial scorecard
Choose a single pixel, date range, audience definition, and downstream owner. Record the same measurements at the start and end of the evaluation.
| Measure | Record |
| --------------------- | ------------------------------------------------------------------ |
| Scope | Domain, pixel, date range, and filters |
| Identified records | Number of distinct people in the reviewed scope |
| ICP-qualified records | People who meet the fit criteria you defined before the trial |
| Actionable records | Qualified people with the contact fields your workflow requires |
| Delivered records | People confirmed in the destination, after checking duplicates |
| Outcomes | Replies, meetings, accepted leads, or another agreed result |
| Cost | Actual Leadpipe cost plus any separately measured downstream costs |
Calculate `cost per actionable record = actual cost / actionable records` and `cost per outcome = actual cost / outcomes`. If the denominator is zero, report no measurable result rather than a zero cost. Free-trial cost alone does not predict paid-plan economics.
Keep the denominator consistent. Do not compare identified people with sessions or pageviews and label the result an identification rate.
## Trial allowance and end conditions
Check your organization's current trial allowance, expiry, and feature access in the app before choosing an evaluation period. Confirm extensions through your existing Leadpipe contact. These docs do not promise a fixed number of trial credits, a standard extension, or an account-specific price.
See [Credits and account status](/guides/credits-and-account-status) for usage checks.
## Common reasons trials fail
Trials are harder to judge when the traffic mix is noisy and unfiltered.
A trial without a downstream owner often creates interest but not proof.
Start with one clear path, not five integrations and three segments at once.
A smaller set of usable records can be more valuable than a larger noisy feed.
## A clean trial outcome
At the end of the trial, you should be able to say one of three things clearly:
* this is a fit and we know how we will use it
* this is a fit, but we need a tighter workflow
* this is not a fit for our traffic or operating model
# Troubleshooting
Source: https://docs.leadpipe.com/guides/troubleshooting
Diagnose missing visitors, pixel verification, delivery failures, and API errors
Start with the symptom below. Check one stage at a time: installation, collection, visitor qualification, then delivery.
## No visitors are showing up
1. In **Pixels**, confirm the domain, verification state, and recent activity. Check whether the pixel is paused.
2. Open a published page and confirm the pixel script loads using the [installation check](/guides/get-started).
3. In **Visitor Insights**, choose the intended pixel and date range. Clear search, filters, and the saved view.
4. Review [page targeting](/guides/manage-pixels#path-filters). Include-only rules can leave most of your site untracked.
5. Check your organization and credits in the account area, or use [account status](/api-reference/account/account-health-and-credit-status).
A script loading successfully does not guarantee that a particular visit will be identified. Recent activity can also appear after a processing delay. If using the API, inspect historical coverage as described in [Visitor data](/api-reference/data-api#pagination-and-historical-coverage).
## The pixel is unverified
1. Confirm the snippet is on the published site, not only in an editor or staging preview.
2. Confirm the snippet's pixel ID matches the configured domain.
3. In browser developer tools, reload with **Network** open and inspect the script request. A missing request suggests the snippet was not published or is not on that page.
4. If the browser reports blocking, inspect the blocker or the site's content security policy with your site administrator. Keep the site's consent requirements in place.
5. After correcting installation, return to **Pixels** and run verification if the action is available.
## The data looks noisy
Use the control that matches the problem:
| Problem | Check |
| --------------------------------------------------- | -------------------------------------------------------------- |
| Unwanted pages are tracked | Pixel [page targeting](/guides/manage-pixels#path-filters) |
| Known customers or internal people trigger delivery | [Suppression rules](/guides/suppress-unwanted-visitors) |
| The table includes visitors outside your ICP | [Filters and segments](/guides/filter-save-views-and-segments) |
| An export contains the wrong site or period | Pixel scope, date range, and filters before exporting |
Suppression still allows identification. It prevents future credits and automation triggers from the next sync cycle; it does not reverse earlier charges or deliveries.
## A webhook or integration is not delivering
1. Check that the connection is active and points to the intended destination.
2. Confirm its pixel, segment, and send frequency. **Once per visitor** does not send every repeat visit.
3. Review suppression rules for the expected visitor.
4. For webhooks, send a test payload and inspect both Leadpipe delivery history and your receiver's logs.
5. If the test succeeds but live data does not arrive, compare the test with an actual qualifying visitor and the configured trigger.
6. If the connection is **Auto-disabled**, fix the recorded failures before enabling it again.
See [webhook receiver checks](/guides/set-up-webhooks#verify-your-receiver). Delivery and retry behavior can differ between Identification webhooks and Orbit destinations.
## The API request fails
| Status or symptom | Next action |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Compare parameters and body with the generated endpoint reference. For qualification queries, provide exactly one of `segmentId` or `ruleAst`. |
| `401` | Check the `X-API-Key` header and that your backend uses the current key. |
| `403` | Check key revocation, organization status, access to the selected pixel, and the endpoint's access requirements. |
| `404` | Check the ID and organization. Some cross-organization resources are returned as not found. |
| `409` | Read the endpoint-specific conflict. An Orbit run may be pending, failed, cancelled, or unavailable for export. |
| `429` | Respect `Retry-After` when returned, and use the rate-limit headers to pace subsequent requests. |
| `5xx` | Save the redacted response and request ID when present. Use bounded retries for reads; check an operation's retry contract before repeating a write. |
If a key was regenerated, update each backend or integration that used the previous key. See [Authentication and errors](/api-reference/authentication-and-errors).
## Orbit results are not ready
A saved audience is a definition. It needs a completed run before results or exports are available. Result reads return `202` while a run is queued or running; `202` is not a completed empty audience.
List the audience's runs and inspect its state. Failed or cancelled runs return a conflict when you request results. Use the [bounded polling example](/orbit-api/examples), and keep the same run ID across result pages and exports.
## Before contacting support
Include the page or workflow, expected result, actual result, time with time zone, and organization or pixel ID. For an API issue, include the method, path, status, request ID when present, and a redacted response. For a delivery issue, include the delivery ID and receiver status when available.
Use your existing Leadpipe support channel. Remove API keys, webhook secrets, signed download URLs, and personal visitor data before sharing logs or screenshots.
# Understanding data quality
Source: https://docs.leadpipe.com/guides/understanding-data-quality
Judge Leadpipe data by usefulness, not by whether every field is filled
## Start with usefulness
Judge Leadpipe data by whether it supports the workflow you care about.
For some teams, a company, landing page, and recency signal are already useful. For others, the record needs a work email, phone number, or stronger firmographic context before it is actionable.
## What usually matters most
| Field or signal | Why teams care |
| --------------- | ------------------------------------------------- |
| `Name` | Helps your team understand who was likely on site |
| `Company` | Ties the visit to an account or target market |
| `Job title` | Helps qualify role, department, and seniority |
| `Emails` | Makes direct follow-up possible when available |
| `Phone` | Supports sales workflows that call fast |
| `Source` | Helps marketing judge acquisition quality |
| `Landing` | Adds context about what triggered the visit |
| `Recency` | Helps teams act while the signal is fresh |
| `Firmographics` | Helps narrow traffic to the right accounts |
## How to think about strong versus partial records
A strong record has a clear identity, strong context, and enough detail to support action right away.
A partial record can still be useful for prioritization, reporting, suppression, or audience building.
## Why quality can vary
Quality depends on your traffic mix, your market, and how tightly you define what useful looks like.
For example:
* clean B2B traffic is usually easier to operationalize than broad consumer traffic
* filtered traffic is easier to trust than unfiltered traffic
* a sales workflow may need richer records than an ads or reporting workflow
## How to improve the quality of what your team sees
* Suppress existing customers, competitors, internal traffic, and bad-fit segments
* Exclude low-value pages if they create too much noise
* Save views around your actual ideal customer profile
* Route only the highest-signal slice into your first workflow
## Measure coverage for your workflow
Review a defined sample using the same pixel, period, and filters. Count identified records, records that match your ICP, and records with the fields your destination needs.
| Metric | Calculation |
| ------------------- | --------------------------------------------------------- |
| Work-email coverage | Records with a usable work email / records reviewed |
| Phone coverage | Records with a phone value / records reviewed |
| ICP fit | Records matching your ICP / records reviewed |
| Actionable records | Records meeting both your fit and required-field criteria |
A populated contact field is not proof of current deliverability or permission to contact someone. For Orbit, [run stats](/orbit-api/stats-and-export) report field fill rates for one completed snapshot. For the Identification API, use the generated visitor schema to distinguish missing arrays, nullable fields, and activity values.
## Identification, enrichment, and intent
Identification associates activity with a person. Enrichment adds available attributes such as role and company. Intent describes activity or topic signals. A record can have a resolved identity while still missing enrichment fields, and a complete profile may still be outside your ICP.
Do not interpret an intent score or contact-field completeness as an identity-confidence percentage. These docs do not establish a universal match-rate guarantee or a customer-facing identity-confidence score. Evaluate your own traffic using the [trial scorecard](/guides/trial-success-guide#trial-scorecard).
## What not to do
* Do not judge the product by the noisiest traffic on your site
* Do not push everything into downstream tools on day one
* Do not assume every workflow needs the same level of data completeness
## Next steps
* Read [Suppress unwanted visitors](/guides/suppress-unwanted-visitors) to control noise and spend.
* Read [What to do with identified visitors](/guides/what-to-do-with-identified-visitors) to choose the right use case for the data you have.
# Use visitor insights
Source: https://docs.leadpipe.com/guides/use-visitor-insights
Read visitor data, firmographics, and intent in Leadpipe
## What you see in Visitor Insights
**Visitor Insights** is where you review identified visitors and deciding what to do next.
![Visitor Insights overview]()
Use the left panel to change the date range and pixel scope, search the current results, and export the current slice to CSV.
The table can include:
| Column | What it helps you understand |
| ----------- | -------------------------------- |
| `Name` | Which person Leadpipe identified |
| `Job title` | Seniority and role |
| `Emails` | Known contact points |
| `Source` | Where the visit came from |
| `Landing` | The first page in the session |
## What the row states mean
`Engaged` is a row-level status that flags a stronger visitor signal than a basic one-off visit.
`Email Only` means the record has an email-level identity but does not currently show the fuller named-person profile you see on richer rows.
Values like `+2 more` or `+7 more` mean Leadpipe has additional emails or phone numbers for that visitor beyond the primary value shown in the table.
## Read intent and engagement
Leadpipe surfaces intent signals so you can prioritize follow-up.
A high-intent classification based on the qualification filters available to your organization.
A medium-intent classification based on the qualification filters available to your organization.
A lower-intent classification based on the qualification filters available to your organization.
## Use the filters sidebar
![Visitor Insights filters]()
The left sidebar is where you narrow the table into something operational.
The filter groups include:
* `Professional & Company`
* `Location`
* `Acquisition`
* `Intent`
* `Enrichment`
* `Contact & Recency`
Inside those groups, add only the conditions needed for the audience you want to review.
For people-level location, Leadpipe primarily identifies city and state in the United States. When the company is elsewhere but the visitor was identified in the US, you can still see the US-based person-level location.
## A simple review flow
1. Start with the current date range and pixel you care about.
2. Scan the table for recent visitors, strong sources, and relevant landing pages.
3. Add filters to narrow the list.
4. Save the result as a segment once it becomes reusable.
![High-intent decision makers]()
## Export the current results
Select **Export CSV** to download the current filtered result set. Confirm the filters and pixel scope before exporting so the file contains the audience you expect.
![Export visitor data]()
## Start simple
Use the default table first. Then narrow the data with filters once you understand what healthy traffic looks like for your site.
Focus on:
* Recency, so you act on fresh visits
* Landing pages, so you know where interest started
* Source, so you can tie visitor quality back to acquisition
* Firmographics, so you can prioritize the right accounts
## Next steps
* Use [Filter, save views, and segments](/guides/filter-save-views-and-segments) to turn this data into repeatable workflows.
* Use [Set up integrations](/guides/set-up-integrations) when you want visitor data to flow into external tools.
# What to do with identified visitors
Source: https://docs.leadpipe.com/guides/what-to-do-with-identified-visitors
Choose a practical workflow for Leadpipe instead of letting the data sit idle
## Start with one clear use case
Leadpipe works best when you decide what should happen after identification.
The simplest approach is to start with one use case, one owner, and one destination.
## The three cleanest starting plays
Route qualified visitors to a CRM, queue, or rep workflow.
Use high-fit traffic to improve retargeting and audience-building workflows.
Send filtered visitors into email or outbound systems that already have a follow-up motion.
## Common use cases by team
| Team | Good first use case | What success looks like |
| ---------------- | ----------------------------------------------- | ----------------------------------------------------------- |
| Sales | Send high-fit visitors to a CRM or Slack | Reps can act on recent, relevant traffic quickly |
| Marketing | Build better retargeting or follow-up audiences | Better audience quality and clearer campaign prioritization |
| Founder-led team | Review a narrow saved view every day | Fast manual follow-up on the best traffic |
| RevOps or ops | Route filtered visitors into existing systems | Cleaner handoff and better workflow consistency |
| Agency | Build one repeatable client workflow | Clear reporting and one obvious next step for the client |
## How to choose the right first play
Pick this when your team already works leads in a CRM and can act quickly on named visitors.
Pick this when paid media is important and you want to recover value from traffic that would otherwise disappear.
Pick this when your team already has an email or outbound process and just needs better inputs.
## A simple workflow to put in place
Every Leadpipe workflow should answer five questions clearly:
1. Which traffic should count as useful?
2. Who owns the next step?
3. Where should the data go?
4. How fast should the team act?
5. What metric proves the workflow is working?
## A good first workflow is narrow
Start with one narrow slice:
* one pixel or domain
* one ideal customer profile
* one saved view or segment
* one destination
* one owner
That is usually enough to prove value without creating operational noise.
## Good first workflows
* Send pricing-page visitors from target industries to your CRM
* Send high-intent visitors from one pixel to Slack
* Export a saved view for founder-led outreach
* Route one segment into your email or outbound tool
* Build one client-facing report around identified visitor activity
## Next steps
* Read [Integrations and delivery options](/guides/integrations-and-delivery-options) to decide how data should leave Leadpipe.
* Read [Trial success guide](/guides/trial-success-guide) to measure the rollout properly.
# Leadpipe documentation
Source: https://docs.leadpipe.com/index
Install a pixel, understand visitor data, connect your tools, or build with the Leadpipe APIs
Leadpipe identifies people and companies visiting your website. Use their activity and available contact data to qualify visitors and send them into your team's workflows. Orbit builds audiences from topic research signals, including people who have not visited your site.
## Choose your starting point
Install and verify a pixel, review visitor data, and set up your first output.
Find topics, preview an audience, and retrieve results from a completed run.
Choose a native integration, webhook, API, or CSV export.
Check account status and retrieve your first page of visitor data.
Retrieve a stored company mapping for an IP address and track your lookup allowance.
## Find an answer
| Your question | Start here |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| Why is no visitor data appearing? | [Troubleshooting](/guides/troubleshooting#no-visitors-are-showing-up) |
| How do I avoid spending credits on unwanted traffic? | [Suppression, filters, and page targeting](/guides/suppress-unwanted-visitors#choose-the-right-control) |
| What does a visitor record tell me? | [Data quality](/guides/understanding-data-quality) |
| What is the difference between a view, segment, audience, and run? | [Core concepts](/guides/how-leadpipe-works#key-terms) |
| How do I send data to my CRM or endpoint? | [Delivery options](/guides/integrations-and-delivery-options) |
| What should I measure during a trial? | [Trial scorecard](/guides/trial-success-guide#trial-scorecard) |
| How do I use these docs in an AI tool? | [Search docs with AI](/guides/search-docs-with-ai) |
The **Guides** tab covers dashboard tasks and product concepts. **Identification API**, **Orbit API**, and **IP to company API** contain integration guides and generated endpoint references with request and response schemas.
For more questions, open the [Product FAQ](/guides/common-questions).
# IP to company API overview
Source: https://docs.leadpipe.com/ip-to-company/introduction
Look up stored company information for an IP address and handle results, usage, and errors
Use `GET /v1/data/company` to look up stored company information for one IPv4 or IPv6 address. The response contains company details and usage metadata. It does not return people, visits, pixels, or organization data, and it does not start a new enrichment request.
The mapping is provider-reported and may be stale. A company result is not proof that the company owns the IP address or that a particular person visited your site.
## Before you start
You need an active organization API key, an organization eligible for company lookups, and `curl`. Create or manage keys in **Settings > API Keys**. Keep your key in your backend or secret manager and set it as `LEADPIPE_API_KEY` for the example below.
Provide one IP address without a URL, port, CIDR suffix, or IPv6 zone identifier. The API normalizes IPv6 spelling and treats IPv4-mapped IPv6 addresses as their IPv4 equivalent.
## Look up an IP address
Replace `192.0.2.10` with the address you want to look up. This documentation address is illustrative; it does not guarantee a company result.
```bash theme={null}
curl "https://api.aws53.cloud/v1/data/company?ip=192.0.2.10" \
-H "X-API-Key: $LEADPIPE_API_KEY"
```
Every request that returns a company consumes one company-lookup unit, including repeated requests for the same address. Do not prefetch or cache responses; the endpoint returns `Cache-Control: no-store`. Avoid automatic retries after an uncertain response because another successful lookup consumes another unit.
## Interpret the result
A successful request returns `200` with `data` and `meta`:
| Result | Meaning | Usage |
| ------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `data` is an object | A stored company mapping is available. Inspect the available company fields. | `meta.credits_consumed` is `1`. |
| `data` is `null` | No successful company identity is stored for this address. This does not prove the address is not used by a company. | `meta.credits_consumed` is `0`. |
A null result does not queue enrichment. Handle it as an unavailable company result rather than polling for a job to finish.
The company schema uses fields such as `name`, `website`, and `employeeCount`. Strings can be empty, and fields such as employee count and LinkedIn profile can be `null`. `annualSales` has no supplied currency; do not assume it is a dollar amount.
Use [Look up a company by IP address](/api-reference/visitors/look-up-a-company-by-ip-address) for the complete schema and company/no-company examples.
## Track your company-lookup allowance
Company lookups have a separate organization-wide allowance equal to the effective identification-plan limit. All API keys in the organization share it. Other products do not consume this allowance, and it resets when the organization's existing billing allowance resets.
Read the successful response's `meta` values:
| Field | Meaning |
| ------------------ | -------------------------------------------------------------------- |
| `credits_consumed` | Units used by this request: `1` for a company result, otherwise `0`. |
| `limit` | Company-lookup allowance for the current billing period. |
| `used` | Company-lookup units used, including this request. |
| `remaining` | Company-lookup units left after this request. |
Once the allowance is exhausted, further lookups are refused. A short wait does not restore the billing allowance; it requires a billing reset or a limit increase.
## Handle errors and rate limits
Requests are limited to 60 per minute per client IP. `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` describe request pacing; they are separate from the company allowance in `meta`. The reset header is in seconds.
| Status | What to do |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Supply one valid IPv4 or IPv6 address without extra URL, port, CIDR, or zone information. |
| `401` | Check that `X-API-Key` contains a valid key. |
| `403` | Check whether the key was revoked or the organization is ineligible; confirm access with Leadpipe if needed. |
| `429` for request rate | Respect `Retry-After` in seconds and reduce request frequency. |
| `429` for company allowance | Stop requests until the billing allowance resets or the limit increases. Inspect the error message to distinguish this from a pacing limit. |
| `503` | The company lookup or allowance service is unavailable. Capture the redacted error and request ID when present, and escalate persistent failures. |
Error responses contain `error.code` and `error.message`. Error `meta`, when present, contains diagnostic information rather than the successful response's allowance counters.
## Related APIs
* Use the [Identification API](/api-reference/introduction) for identified visitors, their activity, and pixel management.
* Use the [Orbit API](/orbit-api/introduction) for audiences based on topic research signals.
The endpoint reference is generated from the [hosted Identification OpenAPI specification](https://api.aws53.cloud/openapi-data.json), which also contains the company-lookup operation.
# Audience filters
Source: https://docs.leadpipe.com/orbit-api/audience-filters
https://api.aws53.cloud/openapi-intent.json GET /v1/intent/audiences/filters
Audience filters using the public Orbit API
# Audience runs
Source: https://docs.leadpipe.com/orbit-api/daily-runs
Queue manual runs and inspect materialized snapshots for an audience
## Overview
Audience results are read from runs. A run can be `manual`, `daily`, or `preview`; public run creation supports `manual` runs. Daily refreshes are scheduled for eligible active audiences.
## Queue a manual run
```bash theme={null}
POST /v1/intent/audiences/{id}/runs
x-api-key: YOUR_API_KEY
Idempotency-Key: unique-client-retry-key
Content-Type: application/json
```
```json theme={null}
{
"runType": "manual"
}
```
Use `Idempotency-Key` when retrying from a client. The key can be up to `120` characters. Reuse it for retries of the same intended run; choose a new key for a new run. An existing in-flight run may also be returned instead of creating a duplicate.
The audience must be active before you queue a run. A successful queue response is `202`, not confirmation that contacts are ready.
### Response
```json theme={null}
{
"data": {
"id": "ad53af16-efbc-4fe1-a764-ded7181653a1",
"audienceId": "8c049a20-3385-42da-b710-0d038eff5812",
"organizationId": "a1657c63-bed2-41b4-b816-f09614490057",
"status": "queued",
"runType": "manual",
"configHash": "8e7f74e01dd2ce8cd0c12969155eac44d624818f1de711f175aab34d2ab193a8",
"dataDate": "2026-05-04",
"candidateCount": 0,
"resultCount": 0,
"attempts": 0,
"createdAt": "2026-05-05T09:30:00.000Z"
}
}
```
## List runs
```bash theme={null}
GET /v1/intent/audiences/{id}/runs?limit=25
x-api-key: YOUR_API_KEY
```
```json theme={null}
{
"data": [
{
"id": "ad53af16-efbc-4fe1-a764-ded7181653a1",
"audienceId": "8c049a20-3385-42da-b710-0d038eff5812",
"status": "completed",
"runType": "daily",
"dataDate": "2026-05-04",
"candidateCount": 121463,
"resultCount": 20,
"startedAt": "2026-05-05T07:49:00.675Z",
"completedAt": "2026-05-05T07:49:03.000Z"
}
]
}
```
## Cancel a queued run
```bash theme={null}
DELETE /v1/intent/audiences/{id}/runs/{runId}
x-api-key: YOUR_API_KEY
```
Only queued runs can be cancelled. Completed, failed, running, or already cancelled runs cannot be cancelled.
## Run status values
| Status | Meaning |
| ----------- | --------------------------------------------------------- |
| `queued` | Waiting for a worker |
| `running` | Materialization is in progress |
| `completed` | Results, stats, and exports are available |
| `failed` | Processing failed; inspect `errorCode` and `errorMessage` |
| `cancelled` | The queued run was cancelled |
## Notes
* Each run is a separate snapshot.
* Use the run ID for results, stats, and exports.
* Result endpoints return `202` while a run is queued or running.
* Request only `manual` runs through the public run-creation API; daily refreshes are scheduled automatically.
* Pausing stops future automatic refreshes. Read `dailyRefreshEnabled` and account access instead of assuming every active audience has the same refresh entitlement.
## Next steps
* Read [Get people](/orbit-api/get-people) to retrieve hydrated results from a completed run.
* Read [Stats and export](/orbit-api/stats-and-export) to inspect fill rates or download CSV data.
# Delivery options and access
Source: https://docs.leadpipe.com/orbit-api/delivery-options
Choose how to retrieve Orbit contacts and understand the current destination authentication limitation
Use a completed audience run as the source for Orbit contacts. Choose paginated results for backend processing, direct CSV for a download, or a stored export when you need a reusable export record and a fresh signed URL.
| Need | Guide |
| -------------------------------------- | ------------------------------------------------------------------ |
| Read contacts in your backend | [Get people](/orbit-api/get-people) |
| Check field coverage | [Stats and export](/orbit-api/stats-and-export) |
| Download CSV or renew a signed URL | [Stats and export](/orbit-api/stats-and-export#stored-csv-exports) |
| Send audience changes to a destination | Review the access note below first |
## Destination access
The hosted Orbit spec currently declares API-key access for integration, destination, and delivery operations, while their descriptions require a non-viewer organization member using Bearer authentication. Confirm the supported authentication with Leadpipe before implementing these operations. Do not assume the generated API-key control means a request will be accepted.
The reference describes webhook and EmailOctopus destinations, activation, synchronization, testing, secret rotation, and delivery history. These are separate from Identification webhooks configured in **Webhooks**. Do not transfer authentication, trigger, or retry assumptions between them.
Until the access discrepancy is resolved, the documented API-key workflows for obtaining contacts are run results and exports. See [Build and export an audience](/orbit-api/examples).
# Build and export an audience
Source: https://docs.leadpipe.com/orbit-api/examples
Validate an Orbit configuration, create an active audience, poll a run with a limit, and check a CSV export
This example creates an audience and runs it. You need `bash`, `curl`, `jq`, an organization API key, and audience access.
Creating an active audience can use an audience slot or eligible one-shot access. This example writes files in a new local directory and leaves the audience in your organization. Review the preview before running the creation step.
## Find topic IDs
Set `LEADPIPE_API_KEY` in your environment. Search for topics and select the returned IDs that match your use case:
```bash theme={null}
curl "https://api.aws53.cloud/v1/intent/topics/search?q=CRM&type=b2b&limit=10" \
-H "X-API-Key: $LEADPIPE_API_KEY"
```
Set `ORBIT_TOPIC_IDS` to a JSON array of your selected integer IDs. Use values returned by discovery, not IDs copied from an unrelated example. The following scripts share files in the working directory you create in the next step.
## Validate and preview
Run in Bash:
```bash theme={null}
set -euo pipefail
: "${LEADPIPE_API_KEY:?Set your organization API key}"
: "${ORBIT_TOPIC_IDS:?Set a JSON array of topic IDs from discovery}"
# Keep each evaluation in a new directory.
ORBIT_EXAMPLE_DIR=$(mktemp -d "${TMPDIR:-/tmp}/leadpipe-orbit.XXXXXX")
cd "$ORBIT_EXAMPLE_DIR"
BASE="https://api.aws53.cloud"
API_KEY="$LEADPIPE_API_KEY"
# Stop before the next step if an HTTP request failed.
require_success() {
case "$1" in
2??) ;;
*) printf 'Request stopped with HTTP %s. Inspect %s.\n' "$1" "$2" >&2; exit 1 ;;
esac
}
jq -en --argjson topics "$ORBIT_TOPIC_IDS" '
if ($topics | type) == "array" and ($topics | length) > 0
then {topicIds: $topics, minScore: 70, maxScore: 99, minTopicOverlap: 1}
else error("Provide a nonempty array of topic IDs") end
' > config.json
HTTP_STATUS=$(curl --max-time 30 -w '%{http_code}' \
"$BASE/v1/intent/audiences/validate" \
-H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
--data-binary @config.json -o validation.json)
require_success "$HTTP_STATUS" validation.json
jq -e '.data.valid == true' validation.json >/dev/null
jq -e '.data.normalizedConfig' validation.json > normalized-config.json
HTTP_STATUS=$(curl --max-time 30 -w '%{http_code}' \
"$BASE/v1/intent/audiences/preview" \
-H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
--data-binary @normalized-config.json -o preview.json)
require_success "$HTTP_STATUS" preview.json
jq '.data | {totalCount, dataDate, breakdowns, sample}' preview.json
```
Review the preview size and audience mix. Samples are masked. Add filters using the [live catalog](/orbit-api/icp-filters), then repeat validation and preview if needed.
## Create, run, and export
After reviewing the preview, run this in the same Bash session and directory. It stops immediately on request failures and polls only `202` responses, for at most 60 attempts. The five-second interval and attempt limit are example client settings, not service timing guarantees.
```bash theme={null}
jq -n --slurpfile config normalized-config.json \
'{name: "CRM research evaluation", status: "active", config: $config[0]}' \
> audience-request.json
HTTP_STATUS=$(curl --max-time 30 -w '%{http_code}' \
"$BASE/v1/intent/audiences" \
-H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
--data-binary @audience-request.json -o audience.json)
require_success "$HTTP_STATUS" audience.json
AUDIENCE_ID=$(jq -er '.data.id | strings | select(length > 0)' audience.json)
# Save this key. Reuse it when retrying this run request; use a new key for a new run.
RUN_KEY="example-$AUDIENCE_ID-001"
printf '%s\n' "$RUN_KEY" > run-key.txt
HTTP_STATUS=$(curl --max-time 30 -w '%{http_code}' \
"$BASE/v1/intent/audiences/$AUDIENCE_ID/runs" \
-H "X-API-Key: $API_KEY" -H "Idempotency-Key: $RUN_KEY" \
-H "Content-Type: application/json" \
-d '{"runType":"manual"}' -o run.json)
require_success "$HTTP_STATUS" run.json
RUN_ID=$(jq -er '.data.id | strings | select(length > 0)' run.json)
READY=false
for attempt in $(seq 1 60); do
HTTP_STATUS=$(curl --max-time 30 \
-o results.json -D result-headers.txt -w '%{http_code}' \
"$BASE/v1/intent/audiences/$AUDIENCE_ID/runs/$RUN_ID/results?limit=100&offset=0" \
-H "X-API-Key: $API_KEY")
case "$HTTP_STATUS" in
200) READY=true; break ;;
202) sleep 5 ;;
*)
printf 'Results request stopped with HTTP %s. Inspect results.json and result-headers.txt.\n' "$HTTP_STATUS" >&2
exit 1
;;
esac
done
if [ "$READY" != true ]; then
printf 'Polling limit reached. Resume reads using audience.json and run.json; do not create another audience.\n' >&2
exit 1
fi
jq '.data.results[:3]' results.json
HTTP_STATUS=$(curl --max-time 300 -w '%{http_code}' \
-D export-headers.txt -o audience.csv \
"$BASE/v1/intent/audiences/$AUDIENCE_ID/runs/$RUN_ID/export.csv" \
-H "X-API-Key: $API_KEY")
require_success "$HTTP_STATUS" audience.csv
if grep -qi '^X-Export-Truncated: true' export-headers.txt; then
printf 'CSV is truncated. Use paginated results to retrieve the complete run.\n' >&2
else
printf 'CSV saved. Check X-Export-Result-Count and X-Export-Row-Cap in export-headers.txt.\n'
fi
```
On `401`, `403`, `409`, or `429`, this example stops instead of treating the error as pending. Read the response before retrying. For `429`, honor `Retry-After` when present. A request timeout can leave a write's outcome uncertain: inspect existing audiences or retry the run request with its saved idempotency key rather than restarting creation blindly.
`results.json` contains only the first page. Follow [result pagination](/orbit-api/get-people#pagination) to read every row. Direct CSV exports are capped at 300,000 rows.
## Stored exports
For a reusable export record and an expiring signed URL, use [stored exports](/orbit-api/stats-and-export#stored-csv-exports). Signed URLs contain access credentials; keep them out of public logs and shared tickets.
## Finish the evaluation
The example leaves an active audience behind. [Pause it](/orbit-api/manage-audiences#activate-or-pause) if you do not want future automatic refreshes. Deletion also removes its runs, results, and exports and does not restore a consumed one-shot trial.
# Find topics
Source: https://docs.leadpipe.com/orbit-api/find-topics
Browse, filter, and search the topic inventory
## Choose a discovery method
| Start with | Endpoint | Reference |
| -------------------- | -------------------------------- | ------------------------------------------------- |
| A website | `POST /v1/intent/topics/analyze` | [Analyze a site](/orbit-api/site-topics) |
| A keyword | `GET /v1/intent/topics/search` | [Search topics](/orbit-api/topic-search) |
| Catalog filters | `GET /v1/intent/topics` | [Browse topics](/orbit-api/topic-inventory) |
| Available categories | `GET /v1/intent/topics/facets` | [Topic facets](/orbit-api/topic-inventory-facets) |
Choose returned topic IDs based on the research behavior you want to target. Reuse those IDs in preview and audience creation requests.
## Browse all topics
Use the inventory endpoint to browse the full topic library.
```bash theme={null}
GET /v1/intent/topics
GET /v1/intent/topics?type=b2b
GET /v1/intent/topics?type=b2b&industry=Marketing
GET /v1/intent/topics?q=CRM
```
| Param | Type | Description |
| ---------- | ------ | ------------------------- |
| `type` | string | `b2b`, `b2c`, or `both` |
| `industry` | string | Exact industry match |
| `category` | string | Exact category match |
| `q` | string | Text search in topic name |
The inventory returns the whole matching catalog without pagination. `meta.count` is the number of matching topics, `meta.total` is the catalog total, and `meta.filters` describes the applied filters. Do not send `page` or `pageSize` to traverse this endpoint.
Industry and category filters use case-insensitive exact matching. `q` uses a case-insensitive topic-name substring. Catalog results are cached for 24 hours, with stale fallback if refresh fails. See [Topic inventory](/orbit-api/topic-inventory) for the response schema.
## Get facet values
Use facets when you need available filter values with counts.
```bash theme={null}
GET /v1/intent/topics/facets
```
```json theme={null}
{
"data": {
"types": [
{ "value": "b2b", "count": 8766 },
{ "value": "b2c", "count": 6447 },
{ "value": "both", "count": 5555 }
],
"industries": [
{ "value": "Marketing", "count": 829 },
{ "value": "Technology", "count": 1644 }
],
"categories": [
{ "value": "Service", "count": 7234 },
{ "value": "Product", "count": 4521 }
],
"total": 20768
}
}
```
## Search topics
Use search for autocomplete-style topic lookup.
```bash theme={null}
GET /v1/intent/topics/search?q=account+based&type=b2b&limit=5
```
```json theme={null}
{
"data": [
{
"topicId": 117890,
"topicName": "Account-Based Marketing",
"type": "b2b",
"industry": "Marketing",
"category": "Service"
}
]
}
```
## Save a topic list
Use topic lists when a set of topics should be reused later or turned into an audience.
```bash theme={null}
POST /v1/intent/topics/lists
x-api-key: YOUR_API_KEY
Content-Type: application/json
```
```json theme={null}
{
"name": "CRM Topics",
"topicIds": [117801, 102391],
"source": "search",
"keywords": ["crm", "customer data"]
}
```
List saved topic lists:
```bash theme={null}
GET /v1/intent/topics/lists?limit=50
x-api-key: YOUR_API_KEY
```
Update or delete a saved list:
```bash theme={null}
PATCH /v1/intent/topics/lists/{id}
DELETE /v1/intent/topics/lists/{id}
```
## Create an audience from a topic list
```bash theme={null}
POST /v1/intent/topics/lists/{id}/instantiate
x-api-key: YOUR_API_KEY
Content-Type: application/json
```
```json theme={null}
{
"name": "CRM Decision Makers",
"status": "draft",
"minScore": 70,
"maxScore": 99,
"minTopicOverlap": 1,
"filters": {
"contact.hasBusinessEmail": true
}
}
```
## Authentication and rate limits
Topic inventory, facets, search, and the audience filter catalog are public. Their documented allowance is 2 requests per source IP per 60 seconds without valid authentication, or 200 with a valid organization API key or Bearer token.
Site analysis (`POST /v1/intent/topics/analyze`) has a separate allowance: 2 requests per source IP per 60 seconds without a valid Bearer token, or 30 with one. Do not assume an API key increases the site-analysis allowance.
Recent site-analysis history is a Bearer-only dashboard operation. It is not an API-key workflow; save a topic list when your API integration needs to reuse selected topics.
## Next steps
* Read [ICP filters](/orbit-api/icp-filters) to narrow a topic audience by company and role.
* Read [Preview audience](/orbit-api/preview-audience) to validate the config and inspect sample rows.
# Get people
Source: https://docs.leadpipe.com/orbit-api/get-people
Retrieve paginated hydrated results from a completed Orbit audience run
## Overview
Use run results to retrieve hydrated people data for a saved audience.
```bash theme={null}
GET /v1/intent/audiences/{id}/runs/{runId}/results?limit=100&offset=0
x-api-key: YOUR_API_KEY
```
The endpoint returns:
* `202` while the run is `queued` or `running`
* `200` with paginated results when the run is `completed`
* `409` when the run state cannot serve results
## Read a run
Use the audience ID and run ID returned by your earlier requests. Follow [Build and export an audience](/orbit-api/examples) for environment setup, run creation, and a polling loop that stops on errors or after a time limit.
Keep the same `runId` throughout pagination. Reading a completed run does not refresh it with new people.
## Pending response
```json theme={null}
{
"data": {
"run": {
"id": "ad53af16-efbc-4fe1-a764-ded7181653a1",
"status": "running",
"runType": "manual",
"candidateCount": 0,
"resultCount": 0
},
"state": "running",
"results": [],
"total": 0,
"limit": 50,
"offset": 0
}
}
```
## Completed response
```json theme={null}
{
"data": {
"run": {
"id": "ad53af16-efbc-4fe1-a764-ded7181653a1",
"status": "completed",
"runType": "manual",
"candidateCount": 121463,
"resultCount": 20,
"completedAt": "2026-05-05T16:52:31.000Z"
},
"results": [
{
"hashedEmail": "50c41e8bb3919b482ed996c139cc85935d2bef278ebc42a22f8c84b04b73709b",
"firstName": "sherry",
"lastName": "lynn",
"fullName": "sherry lynn",
"businessEmail": "sherry@example.com",
"personalEmail": "sherry.personal@example.com",
"email": "sherry.personal@example.com",
"primaryContactEmail": "sherry@example.com",
"phone": "+18005551212",
"linkedinUrl": "https://linkedin.com/in/example",
"headline": "director of marketing",
"jobTitle": "director of marketing operations",
"seniority": "director",
"department": "marketing",
"company": {
"name": "example company",
"domain": "example.com",
"industry": "software development",
"industryGroup": "technology",
"revenueRange": "10 million to 25 million"
},
"geo": {
"city": "san francisco",
"state": "CALIFORNIA",
"stateCode": "CA",
"country": "united states",
"countryCode": "US"
},
"intent": {
"score": 84,
"topicOverlap": 2,
"matchedTopics": [
{
"topicId": 117796,
"topicName": "Internet Marketing Automation",
"type": "b2b",
"industry": "Marketing",
"category": "Technology"
}
]
}
}
],
"total": 20,
"limit": 50,
"offset": 0
}
}
```
## Pagination
Use `limit` and `offset`.
| Query param | Type | Default | Max | Description |
| ----------- | ------- | ------- | ----- | ---------------------- |
| `limit` | integer | `100` | `500` | Results per page |
| `offset` | integer | `0` | - | Number of rows to skip |
Continue increasing `offset` until `offset + results.length >= total`.
## Person fields
Rows can include identity, contact, role, company, geography, demographics, profile signals, company signals, geo signals, compliance, source metadata, and intent matched topics. Any nullable field can be `null` when data is unavailable.
## Next steps
* Read [Stats and export](/orbit-api/stats-and-export) to inspect result quality or export the run.
* Read [Examples](/orbit-api/examples) for an end-to-end audience workflow.
# ICP filters
Source: https://docs.leadpipe.com/orbit-api/icp-filters
Get available filter definitions and build audience rules
## Get the filter catalog
```bash theme={null}
GET /v1/intent/audiences/filters
x-api-key: YOUR_API_KEY
```
The response is a catalog, not a flat list of values. Render filters from `data.groups[].filters[]` and submit each filter by its `key`.
This endpoint is public. An active organization API key can raise the allowance as described in [topic authentication and limits](/orbit-api/find-topics#authentication-and-rate-limits).
Use each filter's label, type, supported operators, values, and UI hints to build the control. Submit `values[].value`, not its display label. Read the returned `logic` rules and examples for supported combinations. See the [generated filter catalog reference](/orbit-api/audience-filters) for the full schema.
## Common filter keys
Use the live catalog as the source of truth. Common current groups include:
| Area | Example keys |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| Company | `company.industries`, `company.industryGroups`, `company.revenueRanges`, `company.names`, `company.domains` |
| Role | `role.seniority`, `role.departments`, `role.isDecisionMaker`, `role.isCeo`, `role.isVp`, `role.isFinance` |
| Job titles | `jobTitle.include`, `jobTitle.exclude`, `jobTitle.exact` |
| Contactability | `contact.hasBusinessEmail`, `contact.hasPersonalEmail`, `contact.hasLinkedin`, `contact.hasAnyPhone` |
| Geography | `geo.personalStates`, `geo.companyStates`, `geo.personalCities`, `geo.companyCities` |
| Demographics | `demographics.gender`, `demographics.ageRanges`, `demographics.incomeRanges`, `demographics.netWorth` |
Do not submit old flat filter keys such as `companyIndustry`, `companySize`, `seniority`, or `hasBusinessEmail`.
## Multi-select filters
Submit raw `values[].value`, not the display labels.
```json theme={null}
{
"filters": {
"company.industries": {
"values": ["software development", "financial services"]
},
"role.seniority": {
"values": ["director", "vp", "c_suite"]
}
}
}
```
Values inside one multi-select are ORed together. Different top-level filters are ANDed together.
## Boolean filters
```json theme={null}
{
"filters": {
"contact.hasBusinessEmail": true,
"role.isDecisionMaker": true
}
}
```
Object form is also supported:
```json theme={null}
{
"filters": {
"contact.hasBusinessEmail": {
"operator": "is_true"
}
}
}
```
## Text chip filters
Use text chip filters for free-text job title, company name, domain, NAICS, SIC, city, or ZIP inputs when those keys are present in the catalog.
```json theme={null}
{
"filters": {
"jobTitle.include": {
"values": ["CFO", "VP Finance", "Head of Revenue"],
"operator": "contains",
"mode": "any"
},
"jobTitle.exclude": {
"values": ["assistant", "intern", "student"],
"operator": "contains",
"mode": "any"
}
}
}
```
Supported text operators are `contains`, `exact`, and `starts_with`. `mode: "any"` ORs terms together, and `mode: "all"` ANDs terms together.
## Number range filters
```json theme={null}
{
"filters": {
"company.revenueMin": {
"min": 1000000,
"max": 10000000
}
}
}
```
Single-sided range form:
```json theme={null}
{
"filters": {
"company.revenueMin": {
"operator": "gte",
"value": 1000000
}
}
}
```
## Advanced logic
Prefer simple top-level filters for normal builders. Advanced `and` and `or` groups are supported when the user explicitly builds nested logic.
```json theme={null}
{
"filters": {
"and": [
{ "field": "contact.hasBusinessEmail", "value": true },
{
"or": [
{ "field": "role.isCfo", "value": true },
{ "field": "role.isVp", "value": true },
{
"field": "jobTitle.include",
"values": ["head of finance"],
"mode": "any"
}
]
}
]
}
}
```
Rules:
* A group can contain either `and` or `or` at the same level, not both.
* Top-level simple filters and top-level groups are combined with AND.
* Check the returned catalog rules for restrictions on combining fields, then validate the complete configuration before saving it.
## Next steps
* Read [Preview audience](/orbit-api/preview-audience) to validate filters before saving an audience.
* Read [Manage audiences](/orbit-api/manage-audiences) to create or update a saved audience config.
# Orbit API overview
Source: https://docs.leadpipe.com/orbit-api/introduction
What Orbit is and how to authenticate to the Orbit API
Orbit turns topic-level research behavior into a usable audience. Start with the subjects people are actively researching, narrow the audience with ICP filters, then materialize a run to retrieve people, fill-rate stats, or a CSV export.
The dashboard provides a visual workflow for analyzing a site or topics. This API reference covers the same customer-facing Orbit capabilities for programmatic use.
![Orbit home]()
## Choose a task
Browse or search the topic inventory and save reusable topic lists.
Inspect available filter definitions and build audience rules.
Validate a config, estimate audience size, and inspect sample rows.
Create, activate, pause, update, list, or delete saved audiences.
Queue a materialization run and monitor its status.
Read hydrated people, inspect stats, and export completed runs.
Orbit is built for net-new targeting. It helps you find people and accounts that have not visited your site yet but are already showing signs of demand in the market.
## What Orbit is
Orbit is Leadpipe's intent audience API.
Use it to find people researching specific B2B or B2C topics, then narrow those audiences with company, role, job title, contactability, geography, and demographic filters.
The current workflow is:
1. Analyze a site, browse topics, or search topics.
2. Validate or preview an audience config.
3. Save an audience as `draft` or `active`.
4. Queue a manual run, or let active audiences refresh through scheduled daily runs.
5. Read run results, run stats, or export CSV from the run ID.
Topic overlap controls how strict the audience should be. A higher overlap means a person must match more of the selected topics, which makes the signal narrower and usually stronger.
## Base URL
```bash theme={null}
https://api.aws53.cloud
```
## Authentication
Authenticated requests can use an `x-api-key` header.
```bash theme={null}
x-api-key: sk_your_api_key
```
API keys are scoped to an organization. Create and manage them in **Settings > API Keys** in the dashboard.
Bearer-authenticated requests are also supported for logged-in frontend users. Do not send `sk_...` API keys as Bearer tokens.
## Quick start
Follow [Build and export an audience](/orbit-api/examples) for a complete example with validation, a saved audience, a manual run, bounded polling, and export checks.
You need an organization API key, audience access, `curl`, and `jq`. Select real topic IDs from [topic discovery](/orbit-api/find-topics); sample topic IDs are not recommendations for your audience.
A preview estimates size and returns masked samples. Creating an audience saves its definition; it does not produce contacts. A completed run provides the result snapshot you can page through or export.
## Endpoint groups
### Topic discovery
| Method | Path | Auth | Purpose |
| -------- | ------------------------------------------ | ----------- | ------------------------------------ |
| `POST` | `/v1/intent/topics/analyze` | Optional | Match a website to intent topics |
| `GET` | `/v1/intent/topics` | Optional | Browse all topics |
| `GET` | `/v1/intent/topics/facets` | Optional | Get topic filter values with counts |
| `GET` | `/v1/intent/topics/search` | Optional | Autocomplete topic search |
| `GET` | `/v1/intent/topics/lists` | `x-api-key` | List saved topic lists |
| `POST` | `/v1/intent/topics/lists` | `x-api-key` | Save a topic list |
| `PATCH` | `/v1/intent/topics/lists/{id}` | `x-api-key` | Update a saved topic list |
| `DELETE` | `/v1/intent/topics/lists/{id}` | `x-api-key` | Delete a saved topic list |
| `POST` | `/v1/intent/topics/lists/{id}/instantiate` | `x-api-key` | Create an audience from a topic list |
### Audience builder
| Method | Path | Auth | Purpose |
| -------- | ------------------------------- | ----------- | ----------------------------------------- |
| `GET` | `/v1/intent/audiences/filters` | Public | Get ICP filter catalog |
| `POST` | `/v1/intent/audiences/validate` | `x-api-key` | Validate and normalize an audience config |
| `POST` | `/v1/intent/audiences/preview` | `x-api-key` | Preview count and sample rows |
| `GET` | `/v1/intent/audiences` | `x-api-key` | List saved audiences |
| `POST` | `/v1/intent/audiences` | `x-api-key` | Create an audience |
| `GET` | `/v1/intent/audiences/{id}` | `x-api-key` | Get one audience |
| `PATCH` | `/v1/intent/audiences/{id}` | `x-api-key` | Update, activate, or pause |
| `DELETE` | `/v1/intent/audiences/{id}` | `x-api-key` | Delete an audience |
### Audience runs and results
| Method | Path | Auth | Purpose |
| -------- | ----------------------------------------------------------- | ----------- | ------------------------------------- |
| `POST` | `/v1/intent/audiences/{id}/runs` | `x-api-key` | Queue a manual run |
| `GET` | `/v1/intent/audiences/{id}/runs` | `x-api-key` | List audience runs |
| `DELETE` | `/v1/intent/audiences/{id}/runs/{runId}` | `x-api-key` | Cancel a queued run |
| `GET` | `/v1/intent/audiences/{id}/runs/{runId}/results` | `x-api-key` | Get paginated hydrated results |
| `GET` | `/v1/intent/audiences/{id}/runs/{runId}/stats` | `x-api-key` | Get fill rates and score histogram |
| `GET` | `/v1/intent/audiences/{id}/runs/{runId}/export.csv` | `x-api-key` | Download CSV directly |
| `POST` | `/v1/intent/audiences/{id}/runs/{runId}/exports` | `x-api-key` | Create or reuse a stored CSV export |
| `GET` | `/v1/intent/audiences/{id}/runs/{runId}/exports` | `x-api-key` | List stored exports |
| `GET` | `/v1/intent/audiences/{id}/runs/{runId}/exports/{exportId}` | `x-api-key` | Get an export with a fresh signed URL |
## Authentication and limits
See [Authentication and errors](/api-reference/authentication-and-errors) for API-key setup and endpoint-specific error handling. Public discovery is not one universal rate-limit bucket: [Find topics](/orbit-api/find-topics#authentication-and-rate-limits) explains the differences.
Integration, destination, and delivery operations currently have conflicting authentication descriptions and security declarations in the hosted spec. Confirm access with Leadpipe before relying on API keys for these operations. See the [access note](/orbit-api/delivery-options).
## Related workflows
* [Visitor overlap and analytics](/orbit-api/visitor-overlap) connects topic audiences with identified website visitors and compares completed runs.
* [Delivery options and access](/orbit-api/delivery-options) distinguishes result export from destination delivery.
The endpoint reference is generated from the [hosted Orbit OpenAPI specification](https://api.aws53.cloud/openapi-intent.json).
# Manage audiences
Source: https://docs.leadpipe.com/orbit-api/manage-audiences
Create, activate, pause, list, and delete saved audiences
## Create an audience
In the dashboard, **Audience Builder** guides you through topics, signals, ICP filters, and review.
![Orbit Audience Builder]()
```bash theme={null}
POST /v1/intent/audiences
x-api-key: YOUR_API_KEY
Content-Type: application/json
```
```json theme={null}
{
"name": "Marketing Directors at Tech Companies",
"status": "draft",
"config": {
"topicIds": [117805, 117890, 117918],
"minScore": 70,
"maxScore": 99,
"minTopicOverlap": 2,
"filters": {
"company.industries": {
"values": ["software development"]
},
"role.seniority": {
"values": ["director", "vp", "c_suite"]
},
"contact.hasBusinessEmail": true
}
}
}
```
`name` and `config.topicIds` are required. New audiences default to `draft`; you can create an `active` audience when you have audience access. Creating an audience as `paused` is rejected. Pause an existing audience with `PATCH` instead.
You can save at most 50 audiences per organization. Creating a definition does not materialize contacts.
### Response
```json theme={null}
{
"data": {
"id": "6fb81599-f601-4afe-b3ff-e8a211cae27d",
"organizationId": "0f1815d3-6edc-4e8e-87e1-4d65ef4f1d2c",
"name": "Marketing Directors at Tech Companies",
"status": "draft",
"accessType": "paid",
"dailyRefreshEnabled": false,
"audienceSize": 0,
"createdAt": "2026-05-05T09:15:00.000Z",
"updatedAt": "2026-05-05T09:15:00.000Z"
}
}
```
## Activate or pause
```bash theme={null}
PATCH /v1/intent/audiences/{id}
x-api-key: YOUR_API_KEY
Content-Type: application/json
```
Activate:
```json theme={null}
{ "status": "active" }
```
Pause:
```json theme={null}
{ "status": "paused" }
```
Activating an audience can consume an audience slot. If all slots are in use, the API returns `403 SLOTS_FULL`.
## Update config
```json theme={null}
{
"name": "Updated Name",
"config": {
"topicIds": [117805],
"minScore": 80,
"filters": {
"jobTitle.include": {
"values": ["chief financial officer", "cfo"],
"operator": "contains",
"mode": "any"
}
}
}
}
```
## List audiences
The dashboard's **Saved** tab lists saved audience definitions and their current status, source, people count, and update date.
![Saved Orbit audiences]()
```bash theme={null}
GET /v1/intent/audiences?status=active&limit=50
x-api-key: YOUR_API_KEY
```
```json theme={null}
{
"data": [
{
"id": "6fb81599-f601-4afe-b3ff-e8a211cae27d",
"name": "Marketing Directors at Tech Companies",
"status": "active",
"accessType": "paid",
"dailyRefreshEnabled": true,
"audienceSize": 151,
"lastRefreshedAt": "2026-05-05T08:45:00.000Z",
"createdAt": "2026-05-04T16:20:00.000Z"
}
]
}
```
## Delete an audience
```bash theme={null}
DELETE /v1/intent/audiences/{id}
x-api-key: YOUR_API_KEY
```
Deleting an audience also deletes its associated runs, results, and exports. This cannot be undone. A consumed one-shot trial remains consumed after deletion.
Pause an audience if you only want to stop future automatic refreshes. Configuration changes affect future runs; previously completed results remain tied to their original snapshot.
## Next steps
* Read [Audience runs](/orbit-api/daily-runs) to queue and monitor a materialization run.
* Read [Get people](/orbit-api/get-people) to retrieve results from a completed run.
# Preview audience
Source: https://docs.leadpipe.com/orbit-api/preview-audience
Validate audience configs, estimate audience size, and inspect sample rows
## Validate config
Use validation to check a config and see the normalized version without running a preview query.
```bash theme={null}
POST /v1/intent/audiences/validate
x-api-key: YOUR_API_KEY
Content-Type: application/json
```
```json theme={null}
{
"topicIds": [117805, 117890],
"minScore": 70,
"maxScore": 99,
"minTopicOverlap": 1,
"filters": {
"role.seniority": {
"values": ["director", "vp", "c_suite"]
},
"contact.hasBusinessEmail": true
}
}
```
Validation returns `valid`, `configHash`, `normalizedConfig`, and `appliedFilters`.
## Preview audience
Preview returns the total count and sample rows before you save or run an audience.
```bash theme={null}
POST /v1/intent/audiences/preview
x-api-key: YOUR_API_KEY
Content-Type: application/json
```
```json theme={null}
{
"topicIds": [117805, 117890],
"minScore": 70,
"maxScore": 99,
"minTopicOverlap": 1,
"filters": {
"company.industries": {
"values": ["software development"]
},
"role.seniority": {
"values": ["director", "vp", "c_suite"]
},
"contact.hasBusinessEmail": true
}
}
```
## Read the preview
Use `totalCount` to estimate size, `breakdowns` to inspect the audience mix, and `normalizedConfig` to review what will be saved. The preview uses the latest available intent snapshot and reports its `dataDate`.
Sample contact details are masked. A preview does not save an audience or provide the full contact dataset. Counts can change as new intent data arrives; the preview is not a guarantee of the size of a later completed run.
See the [generated preview reference](/api-reference/audience-builder/preview-an-intent-audience) for the exact response schema.
## Notes
* `topicIds` is required and supports `1` to `250` topics.
* `minScore` accepts `0` to `99`; values below `50` are normalized to `50`.
* `maxScore` accepts `50` to `99`.
* `minTopicOverlap` must be at least `1`.
* Expected preview performance depends on topic breadth and filter complexity.
## Next steps
* Read [Manage audiences](/orbit-api/manage-audiences) to save and activate a validated config.
* Read [Audience runs](/orbit-api/daily-runs) to materialize an active audience.
# Analyze site topics
Source: https://docs.leadpipe.com/orbit-api/site-topics
https://api.aws53.cloud/openapi-intent.json POST /v1/intent/topics/analyze
Analyze site topics using the public Orbit API
# Stats and export
Source: https://docs.leadpipe.com/orbit-api/stats-and-export
Inspect run fill rates and export audience data to CSV
## Run stats
Stats are scoped to a completed run.
```bash theme={null}
GET /v1/intent/audiences/{id}/runs/{runId}/stats
x-api-key: YOUR_API_KEY
```
```json theme={null}
{
"data": {
"run": {
"id": "ad53af16-efbc-4fe1-a764-ded7181653a1",
"audienceId": "8c049a20-3385-42da-b710-0d038eff5812",
"status": "completed",
"runType": "manual",
"resultCount": 151,
"completedAt": "2026-05-05T08:45:03.000Z"
},
"stats": {
"total": 151,
"fillRates": {
"hashedEmail": { "count": 151, "percent": 100 },
"email": { "count": 151, "percent": 100 },
"firstName": { "count": 103, "percent": 68.21 },
"jobTitle": { "count": 59, "percent": 39.07 },
"company.name": { "count": 70, "percent": 46.36 },
"linkedinUrl": { "count": 57, "percent": 37.75 }
},
"scoreHistogram": [
{ "bucket": "50-69", "count": 24, "percent": 15.89 },
{ "bucket": "70-89", "count": 111, "percent": 73.51 },
{ "bucket": "90-99", "count": 16, "percent": 10.6 }
],
"averages": {}
}
}
}
```
`fillRates` includes public result fields exposed by the run results endpoint.
Examples below use `BASE`, `API_KEY`, `AUDIENCE_ID`, and `RUN_ID` from [Build and export an audience](/orbit-api/examples).
## Direct CSV download
Use the direct CSV endpoint when you want to stream a completed run as a CSV file immediately. The export is capped at 300,000 rows. Save and inspect `X-Export-Truncated`, `X-Export-Row-Cap`, and `X-Export-Result-Count` response headers before treating the file as a complete export. If it is truncated, use [paginated results](/orbit-api/get-people#pagination) to retrieve the remaining population.
```bash theme={null}
GET /v1/intent/audiences/{id}/runs/{runId}/export.csv
x-api-key: YOUR_API_KEY
```
```bash theme={null}
curl -D audience-headers.txt "$BASE/v1/intent/audiences/$AUDIENCE_ID/runs/$RUN_ID/export.csv" \
-H "x-api-key: $API_KEY" \
-o audience.csv
```
Check the HTTP status in `audience-headers.txt` before importing `audience.csv`; an error response can also be saved to that file.
## Stored CSV exports
Use stored exports when you need a reusable export record and a signed download URL.
```bash theme={null}
POST /v1/intent/audiences/{id}/runs/{runId}/exports
x-api-key: YOUR_API_KEY
```
```json theme={null}
{
"data": {
"export": {
"id": "40bfaa9b-eff0-468d-b382-9b721790780c",
"audienceId": "8c049a20-3385-42da-b710-0d038eff5812",
"runId": "ad53af16-efbc-4fe1-a764-ded7181653a1",
"exportType": "csv",
"status": "completed",
"contentType": "text/csv",
"byteSize": 18450,
"rowCount": 151,
"completedAt": "2026-05-05T08:46:03.000Z"
},
"downloadUrl": "https://f005.backblazeb2.com/file/...",
"downloadUrlExpiresAt": "2026-05-06T08:46:03.000Z",
"downloadUrlTtlSeconds": 86400
}
}
```
List stored exports:
```bash theme={null}
GET /v1/intent/audiences/{id}/runs/{runId}/exports
x-api-key: YOUR_API_KEY
```
Refresh a signed URL for a specific export:
```bash theme={null}
GET /v1/intent/audiences/{id}/runs/{runId}/exports/{exportId}
x-api-key: YOUR_API_KEY
```
## Export behavior
* Stored export URLs expire; call the export detail endpoint for a fresh URL.
* `POST /exports` creates or reuses a CSV export for the completed run.
* CSV rows are tied to the run snapshot identified by `runId`.
## Next steps
* Read [Examples](/orbit-api/examples) for a complete topic-to-export workflow.
* Return to [Audience runs](/orbit-api/daily-runs) to queue or inspect another snapshot.
# Browse topic inventory
Source: https://docs.leadpipe.com/orbit-api/topic-inventory
https://api.aws53.cloud/openapi-intent.json GET /v1/intent/topics
Browse topic inventory using the public Orbit API
# Topic inventory facets
Source: https://docs.leadpipe.com/orbit-api/topic-inventory-facets
https://api.aws53.cloud/openapi-intent.json GET /v1/intent/topics/facets
Topic inventory facets using the public Orbit API
# Search topics
Source: https://docs.leadpipe.com/orbit-api/topic-search
https://api.aws53.cloud/openapi-intent.json GET /v1/intent/topics/search
Search topics using the public Orbit API
# Visitor overlap and analytics
Source: https://docs.leadpipe.com/orbit-api/visitor-overlap
Find Orbit audience members who visited your website and compare completed audience runs
Use overlap when you want to combine topic research signals with activity on your own website. Use audience analytics when you want to understand how a saved audience changes between completed runs.
## Choose the scope
| Question | Endpoint |
| ------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Which people in any of our latest audiences visited our site? | `GET /v1/intent/audiences/website-visitors` |
| Which members of one audience visited? | `GET /v1/intent/audiences/{id}/website-visitors` |
| Which topics matched a visitor over time? | `GET /v1/intent/audiences/website-visitors/{hashedEmail}/topic-history` |
| What changed since the previous completed run? | `GET /v1/intent/audiences/{id}/dashboard` |
| How has the audience changed across completed runs? | `GET /v1/intent/audiences/{id}/trends` |
These operations support organization API keys. Use an audience owned by that organization.
## Retrieve website overlap
```bash theme={null}
curl "https://api.aws53.cloud/v1/intent/audiences/website-visitors?limit=100&offset=0" \
-H "X-API-Key: $LEADPIPE_API_KEY"
```
The organization-wide endpoint compares the latest completed audience runs with recent identified website visitors. It deduplicates people by email hash and includes their latest audience matches. This is an overlap result, not a list of every website visitor or every Orbit contact.
Read the response `state` before interpreting an empty result. `no_completed_runs` means there are no completed snapshots to compare. Inspect `lookbackDays`, `total`, `limit`, and `offset` in the generated reference when building reporting and pagination.
For one visitor's topic history, use the 64-character SHA-256 identifier required by the path and optionally scope with `audienceId`. Topic history describes matches in audience runs; it does not expose a person's full browsing history.
## Compare completed runs
The audience dashboard compares the latest completed run with the previous completed run. Trends provide chronological metrics across completed runs. Keep run dates in reports so readers know which snapshots were compared.
A preview, a current audience definition, and a completed run can describe different populations. Updating an audience config affects future runs rather than rewriting older results.
Use the generated references under **Visitor overlap and analytics** for exact parameters and response fields. See [Audience runs](/orbit-api/daily-runs) to produce a new snapshot.