# API: Engagement and intent

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/accounts/:id/intent` | An account's intent in one view: each vendor's topics and surge scores with their date and freshness, the combined topics with their sources, and first-party intent when no vendor has data | `accounts:read` |
| GET | `/v1/contacts/:id/email-engagement` | A contact's tracked email: counted opens and clicks with first and last times, per message and per link, and how many events were filtered as machine events (and why) | `contacts:read` |
| GET | `/v1/email-tracking` | First-party email tracking: whether opens and clicks are on (both off by default), how consent-first places are treated, the machine-event window, retention, and the trade-offs | `signals:read` |
| PUT | `/v1/email-tracking` | Turn open or click tracking on or off (organization owners, signed in). Each sequence also turns it on in its settings (web app only) | `settings:write` |
| GET | `/v1/intent` | Third-party intent: the switch (off by default), the vendor order, topics and threshold, and each vendor's connection (never its credentials) | `signals:read` |
| PUT | `/v1/intent` | Change intent settings (organization owners): turn it on, the vendor order (a vendor is only called when connected), topics, the score, stop at the first vendor with data, first-party fallback (web app only) | `settings:write` |
| PUT | `/v1/intent/providers/:provider` | Connect, configure, or turn on or off an intent vendor with your organization's own key (owners, signed in; stored encrypted, never returned) (web app only) | `settings:write` |
| POST | `/v1/intent/providers/:provider/check` | Check a vendor's saved key with a harmless read (web app only) | `settings:write` |
| DELETE | `/v1/intent/providers/:provider/credentials` | Remove a vendor's credentials (turns it off) (web app only) | `settings:write` |
| POST | `/v1/intent/sync` | Read intent from the connected vendors now (owners; in the background unless wait=true) (web app only) | `settings:write` |

## Examples

### GET /v1/accounts/$ID/intent

An account's intent in one view: each vendor's topics and surge scores with their date and freshness, the combined topics with their sources, and first-party intent when no vendor has data

```bash
curl -s "https://api.closefinch.com/v1/accounts/$ID/intent" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/accounts/${id}/intent`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/contacts/$ID/email-engagement

A contact's tracked email: counted opens and clicks with first and last times, per message and per link, and how many events were filtered as machine events (and why)

```bash
curl -s "https://api.closefinch.com/v1/contacts/$ID/email-engagement" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/contacts/${id}/email-engagement`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/email-tracking

First-party email tracking: whether opens and clicks are on (both off by default), how consent-first places are treated, the machine-event window, retention, and the trade-offs

```bash
curl -s "https://api.closefinch.com/v1/email-tracking" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/email-tracking`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/intent

Third-party intent: the switch (off by default), the vendor order, topics and threshold, and each vendor's connection (never its credentials)

```bash
curl -s "https://api.closefinch.com/v1/intent" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/intent`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

Request and response schemas: [https://www.closefinch.com/openapi.json](https://www.closefinch.com/openapi.json). All resources: [API reference](https://www.closefinch.com/docs/api).