canonical: https://jentic.com/apis/leadboxer.com/leadboxer

# Leadboxer API

The LeadBoxer API retrieves the leads, sessions, and events that LeadBoxer tracks on your websites, where each tracked site is a dataset identified by a datasetId. Lead queries take the site id with search text, criteria filters, and a time field, and return results as JSON or as a CSV export, while lead details, session lists, and per-session event lists drill into one visitor's activity. Alongside tracking data it looks up organization and geolocation details for an IP address, a domain, or an email address, and administers segments, lead tags and assignments, hidden leads, custom tracking domains, users, and credit usage.

## For AI agents

Query tracked website leads, sessions, and events by dataset, look up company details from an IP, domain, or email, and manage segments, lead tags, and lead assignments in LeadBoxer.

## Scope

Does not handle email sending, ad campaigns, deal pipelines, or installing the tracking pixel. Use for reading tracked website leads, sessions, and events, and IP, domain, or email lookups only.

## Capabilities

- Retrieve the leads tracked on a site by dataset id, filtered by search text and criteria such as lead score and time window, as JSON or CSV
- Drill into one lead's detail, then list its sessions and the page events within a session
- Look up the organization, ISP, usage type, and geolocation behind an IP address with ipOrganization and ipCity fields
- Look up company details for a domain or an email address, with optional firstName, lastName, and companyName hints
- Create and update lead segments with text, number, time, and lead score filters, and set email notifications for them
- Tag leads, assign them to a teammate, and hide or unhide leads from a dataset
- Add, validate, and remove custom tracking domains and review credit usage over time

## Use cases

### Agent-driven lead follow-up through Jentic

An AI sales assistant can pull the recent high-scoring leads for a site, read each lead's sessions to see which pages they viewed, and then tag or assign the lead to a rep. Through Jentic the agent finds each LeadBoxer operation by intent, the x-api-key credential is injected at execution time, and a rule can allow reads and tagging while leaving user, dataset, and domain administration out of reach.

Example prompt: Call GET `/v1/leads` with site set to the dataset id, timeField 'eventEsTimestamp', and criteriaTimeFilter 'eventEsTimestamp|lessthan|6' for the last 7 days, then call PUT `/v1/management/assign-leads` with the top lead's leadId, the datasetId, and assignee set to the rep's numeric user id

### Visitor-to-company identification

B2B teams want to know which organizations are behind anonymous website traffic. The LeadBoxer IP lookup returns fields such as ipOrganization, ipDomain, ipIsp, ipUsageType, ipCountryName, and ipCity for an address, and the domain and email lookups resolve company details for a known domain or contact, each charging credits against a dataset.

Example prompt: Call GET `/v1/ip-lookup` with ip '8.8.8.8' and report the returned ipOrganization, ipDomain, and ipCountryName

### Lead segments and alerts

Sales teams often want an email when a target account returns, or a saved view of leads that meet a score threshold. LeadBoxer segments combine text, number, time, field, exit link, and lead score filters, and each segment can carry a notification type, recipient list, and schedule, so the right people hear about the right visitors.

Example prompt: Call POST `/v1/segments` with email 'owner@example.com' and a body containing name 'High intent', accountId, datasetId, type, and a leadscoreFilter for scores above 50

### Session-level visitor activity

Understanding what a lead did on the site helps tailor outreach. LeadBoxer returns a lead's detail, the list of its sessions with a required limit, and the events inside a session, so an agent can summarise pages viewed and exit links before a rep makes contact.

Example prompt: Call GET `/v1/leads/sessions` with leadId, limit 10, and site, then call GET `/v1/leads/events` with the newest sessionId, limit 50, and site to list the pages viewed

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/leads` | Retrieve leads for a site |
| GET | `/v1/leads/{leadId}` | Retrieve lead details |
| GET | `/v1/leads/sessions` | Retrieve a lead's sessions |
| GET | `/v1/ip-lookup` | Look up an IP address |
| GET | `/v1/domain-lookup` | Look up a domain |
| POST | `/v1/segments` | Create a segment |
| PUT | `/v1/management/assign-leads` | Assign leads |

## Key resources

- **Leads** — Retrieve leads per site with filters, export them as CSV, and read a lead's detail, sessions, and events
- **Lookup** — IP address, domain, and email lookups returning organization and geolocation details
- **Segments** — Create, update, and delete filtered lead segments and default segment preferences
- **Management** — Lead tags, lead assignment, custom tracking domains, and credit grants
- **Datasets and users** — Add and remove datasets and users, link users to datasets, and configure form tracking

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 62 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 74 / 100
  - Developer Experience & Jentic Compatibility: 71 / 100
  - AI-Readiness & Agent Experience: 43 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 76 / 100
- **View full report:** https://jentic.com/apis/leadboxer.com/leadboxer/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring LeadBoxer by hand means carrying the x-api-key header, passing the right email and site parameters on each call, and building the criteria filters lead queries require. Through Jentic you install once, import LeadBoxer from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** LeadBoxer puts some ids in the URL path (`/v1/leads/{leadId}`, `/v1/segments/{segmentId}`, `/v1/datasets/{datasetId}/name`), so a rule can pin those operations to one lead, segment, or dataset. Lead listing and lookups take the site id in the query string, so for those, rules bound which operations your agent may call. You choose the operations it may call, so destructive ones like removing a dataset or deleting a user are not included unless you add them.
- **Credential handling:** Your LeadBoxer API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'retrieve website leads' or 'look up the company behind an IP', and Jentic returns the matching LeadBoxer operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Snitcher API** — Website visitor identification that reveals companies behind B2B traffic
- **Clearbit API** — Company and person enrichment, including IP-to-company resolution
- **Apollo API** — B2B contact database and sales engagement sequences
- **Hunter API** — Email finder and verifier for a company domain

## FAQ

### Is there a LeadBoxer MCP server?

You don't need an MCP server to give your agent the LeadBoxer API. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls it. Operations are discovered on demand, so your agent's context carries no tool definitions it will not use.

### What authentication does the LeadBoxer API use?

Per its OpenAPI spec, the LeadBoxer API authenticates with an API key in the x-api-key header. LeadBoxer says the API is for customers with a valid API license and key. Through Jentic, the key is stored encrypted by your own Jentic One instance and injected at execution time, so it never enters the agent's context.

### Can I find out which company is behind a website visitor's IP with the LeadBoxer API?

Yes. GET `/v1/ip-lookup` takes an ip and returns organization fields such as ipDomain and ipOrganization, geolocation fields such as ipCountryName and ipCity, and ISP details including ipUsageType. Pass datasetId to choose which dataset the lookup's credit is charged to.

### What are the rate limits for the LeadBoxer API?

The OpenAPI spec does not specify rate limits. Lookups consume credits, which you can check with the credit usage summary operation; see https://docs.leadboxer.com/category/112-all for current limits.

### How do I pull recent leads from LeadBoxer through Jentic?

Install Jentic One with `curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh`, import the LeadBoxer API from the directory, and store your API key. Your agent then searches for 'retrieve website leads' and Jentic returns GET `/v1/leads`, which requires site, criteriaTimeFilter, and timeField. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Does the LeadBoxer API work on live data?

Yes. LeadBoxer warns that calls run against your production data, and recommends creating a separate LeadBoxer account if you want sandbox data for testing.

### Can I limit what my agent is allowed to do with the LeadBoxer API?

Yes. For a sales assistant, write a rule that allows GET `/v1/leads`, GET `/v1/leads/sessions`, and PUT `/v1/management/lead-tags`: the agent can read leads and their sessions and tag them, but cannot delete users, remove datasets, or change tracking domains, and every call it makes is logged.