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

# IntentWake API

The IntentWake API matches email identifiers against IntentWake's activity, emaillogin, and intent services and returns the results, either in billed batch lookups or through managed customer lists. Lists accept an initial upload and forward-only appends or removals, can be monitored over time, and produce match-result downloads that are unlocked by debiting wallet credit with a max_cents ceiling. An intent taxonomy endpoint lists the categories you can select for the intent service, and wallet and usage endpoints report the credit balance, funding status, and per-service charges.

## For AI agents

Run batch email lookups across IntentWake's activity, emaillogin, and intent services, manage monitored lists and their match-result downloads, and check wallet credit and usage.

## Scope

Does not handle sending email, storing payment methods, or company firmographic enrichment. Use for email identifier lookups, monitored lists, and their match-result downloads only.

## Capabilities

- Look up a batch of email identifiers across the activity, emaillogin, and intent services, with an Idempotency-Key header
- Narrow intent matches to chosen category_ids, vertical_ids, or sub_category_ids from the intent taxonomy
- Create a customer list, upload its initial entries, append new entries, and queue removals
- Turn monitoring on or off for a list and set which services and intent categories it uses
- Unlock a gated match-result download with a max_cents spending ceiling, or create a free filtered download from an unlocked one
- Check the wallet's credit balance, arrears, and funding status, and request funding under the owner's policy
- List recent lookup usage with per-service charge lines

## Use cases

### Intent lookups from your agent through Jentic

An AI agent connected through Jentic checks a set of leads by sending their email identifiers to the batch lookup with the intent service enabled and a few category_ids picked from the intent taxonomy. It reuses an Idempotency-Key so a retried request is not billed twice, and reads usage afterwards to report the cost. The API key stays in your own Jentic One instance, not in the agent's context.

Example prompt: Call GET `/api/v1/intent-taxonomy` to pick category ids, then POST `/api/v1/lookups/batch` with identifiers ['ana@example.com', 'li@example.com'], services.intent.category_ids set to the chosen ids, and an Idempotency-Key header

### Monitored lists with bounded spend

For a standing audience, create a list with its services and an idempotency_key, upload the initial entries, and enable monitoring. When result downloads appear, unlock one with max_cents as a hard ceiling on the debit, then fetch a short-lived URL for the artifact. Filtered downloads built from an unlocked result are free.

Example prompt: Call GET `/api/v1/lists/{id}/downloads`, then POST `/api/v1/lists/{id}/downloads/{downloadId}/unlock` with an idempotency_key and max_cents 5000, and fetch GET `/api/v1/lists/{id}/downloads/{downloadId}/url`

### Keeping a list current

Lists change as people sign up or opt out. Start an append upload and complete it to queue intake of new entries, poll the append status, and queue entry removals for people who should no longer be matched. Both appends and removals are forward-only.

Example prompt: Call POST `/api/v1/lists/{id}/entry-removals` with entries ['old@example.com'] and an idempotency_key, then poll GET `/api/v1/lists/{id}/entry-removals/{removalId}` until it completes

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/lookups/batch` | Look up a batch of email identifiers |
| GET | `/api/v1/intent-taxonomy` | Get the intent taxonomy |
| POST | `/api/v1/lists` | Create a customer list |
| GET | `/api/v1/lists/{id}` | Get a list and its status |
| PATCH | `/api/v1/lists/{id}/monitoring` | Set monitoring for a list |
| POST | `/api/v1/lists/{id}/downloads/{downloadId}/unlock` | Unlock a match-result download |
| GET | `/api/v1/wallet` | Get the wallet balance |
| GET | `/api/v1/usage` | List lookup usage and charges |

## Key resources

- **Lookups** — Billed batch lookups of email identifiers across selected services
- **Intent taxonomy** — The categories available to the intent service
- **Lists** — Create, read, and soft-delete lists; uploads, appends, removals, monitoring, and service settings
- **Downloads** — Match-result downloads, unlocks, filtered artifacts, and short-lived URLs
- **Wallet and usage** — Credit balance, funding requests, and per-service usage lines

## 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:** 64 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 99 / 100
  - Developer Experience & Jentic Compatibility: 69 / 100
  - AI-Readiness & Agent Experience: 43 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 60 / 100
- **View full report:** https://jentic.com/apis/intentwake.com/intentwake/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 IntentWake by hand means handling its bearer key, separate IP and key rate budgets with Retry-After, idempotency keys on billed calls, and multi-step upload and download flows. Through Jentic you install once, import IntentWake from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** IntentWake puts the list id in the URL path (`/api/v1/lists/{id}/...`), so a rule can pin your agent to one list and the operations you pick. You choose the operations it may call, so billed or spending ones like batch lookups, download unlocks, and wallet funding requests are not included unless you add them.
- **Credential handling:** Your IntentWake 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 'look up intent signals for emails' or 'check list download status', and Jentic returns the matching IntentWake operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **6sense API** — Account-level buyer intent and company identification
- **People Data Labs API** — Person and company enrichment from email, name, or profile
- **Clearbit API** — Company and person enrichment by email or domain
- **IndiePitcher API** — Transactional and mailing-list email sending

## FAQ

### Is there an IntentWake MCP server?

You don't need an MCP server to give your agent IntentWake. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls it. The agent finds the lookup, list, or wallet operation it needs on demand, which keeps unused tool definitions out of its context.

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

Yes. For a reporting agent, write a rule that allows only GET `/api/v1/lists/{id}` and GET `/api/v1/lists/{id}/downloads` for one list id, plus GET `/api/v1/usage.` It can watch that list and report costs, but it cannot run billed lookups, unlock downloads, or request wallet funding, and every call it makes is logged.

### What authentication does the IntentWake API use?

Per its OpenAPI spec, the IntentWake API uses HTTP bearer authentication on every operation: send your IntentWake API key in the `Authorization` header as `Bearer <key>`. Through Jentic, the key is stored encrypted by your own Jentic One instance and injected when each call runs.

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

Per the OpenAPI spec, fixed 60-second windows allow 60 requests per client IP per API service. Per API key, the budgets are 120 read requests, 60 non-billed mutation requests, and 30 requests to the billed batch lookup endpoint, and whichever IP or key budget runs out first applies. 429 responses include a Retry-After header.

### How do I avoid being charged twice for an IntentWake lookup?

Send an Idempotency-Key header with POST `/api/v1/lookups/batch`, and an idempotency_key in the body of list creation, unlocks, removals, and funding requests. Reusing the same key on a retry lets IntentWake treat it as the same request.

### How do I look up a batch of emails with the IntentWake API through Jentic?

Install Jentic One with `curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh`, import IntentWake from the API Directory, and store your API key. Your agent searches for 'look up intent signals for email addresses', gets POST `/api/v1/lookups/batch` with its input schema, and calls it with identifiers and the services to match. To run it on your own infrastructure, install Jentic One from its GitHub repo.