# API: Integrations

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/accounts/:id/slack-channels` | Slack channels filed to this account, with sync health and their external members (and which are contacts). connections lists the Slack workspaces to link or create channels in. | `accounts:read` |
| DELETE | `/v1/connections/:id` | Disconnect: stops syncing and deletes the saved credentials. Already-synced activity stays, unless an owner passes delete_data=true: then everything that came only from this source (its activities and documents, and what was made from them, embeddings included) is deleted in the background (web app only) | `connections:write` |
| PATCH | `/v1/connections/:id` | Change sharing, contact creation, calendars, backfill, or pause syncing (web app only) | `connections:write` |
| GET | `/v1/connections/:id/calendars` | Calendars this account can see, and which ones sync (settings.calendars; none chosen means the primary calendar) (web app only) | `connections:read` |
| POST | `/v1/connections/:id/export` | Export CRM records of one object type to the warehouse connection's export_table (owner, web only; passes the outbound policy) (web app only) | `integrations:write` |
| GET | `/v1/connections/:id/grant` | LGL-006 #11: the person's other connections that share this connection's grant at the provider (Google: Gmail, Calendar, Drive and Meet on the same account), so a disconnect can say what removing all access would also stop. The connection's own person only (web app only) | `connections:read` |
| GET | `/v1/connections/:id/runs` | Recent sync runs with stats and errors | `connections:read` |
| PUT | `/v1/connections/:id/secrets` | Add or replace a connection's declared secrets (e.g. the webhook signing secret shown after setup; on OAuth connections only declared extras such as a webhook secret, never the sign-in tokens). Values are stored encrypted and never returned; empty values keep the current one. (web app only) | `connections:write` |
| GET | `/v1/connections/:id/slack/channels` | Slack channels the app can see, with the account/deal each maps to and its sync health | `connections:read` |
| POST | `/v1/connections/:id/slack/channels` | Create a Slack Connect channel for an account (prefix + account name), invite its external contacts, and map it to the account | `messages:send` |
| POST | `/v1/connections/:id/slack/channels/:channel/link` | Link an existing Slack channel to an account and/or deal; its external members become contacts and its history is backfilled (queued by default) | `integrations:write` |
| POST | `/v1/connections/:id/slack/members/:userId/promote` | Make an external Slack member a contact on an account (filling name and job title from their Slack profile). Teammates and bots are refused. | `connections:write` |
| GET | `/v1/connections/:id/snippet` | The website/app snippet for the first-party intent client (intent_js connections) | `connections:read` |
| POST | `/v1/connections/:id/sync` | Sync now (web app only) | `connections:write` |
| GET | `/v1/integrations` | Available integrations (and whether this server is set up for them) plus your organization's connections | `connections:read` |
| POST | `/v1/integrations/:provider/connect` | Start connecting an account. OAuth providers return a URL to send the browser to; API-key providers connect immediately. (web app only) | `connections:write` |
| POST | `/v1/me/google-features/:feature/connect` | Grant your Google mailbox the extra access a feature your organization turned on needs (Gmail drafts and labels, or Postmaster Tools): returns the consent URL (web app only) | `connections:write` |

## Examples

### GET /v1/accounts/$ID/slack-channels

Slack channels filed to this account, with sync health and their external members (and which are contacts). connections lists the Slack workspaces to link or create channels in.

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

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

### GET /v1/connections/$ID/runs

Recent sync runs with stats and errors

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

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

### GET /v1/connections/$ID/slack/channels

Slack channels the app can see, with the account/deal each maps to and its sync health

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

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

### POST /v1/connections/$ID/slack/channels

Create a Slack Connect channel for an account (prefix + account name), invite its external contacts, and map it to the account

```bash
curl -s -X POST "https://api.closefinch.com/v1/connections/$ID/slack/channels" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/connections/${id}/slack/channels`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### POST /v1/connections/$ID/slack/channels/$CHANNEL/link

Link an existing Slack channel to an account and/or deal; its external members become contacts and its history is backfilled (queued by default)

```bash
curl -s -X POST "https://api.closefinch.com/v1/connections/$ID/slack/channels/$CHANNEL/link" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/connections/${id}/slack/channels/${channel}/link`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### POST /v1/connections/$ID/slack/members/$USER_ID/promote

Make an external Slack member a contact on an account (filling name and job title from their Slack profile). Teammates and bots are refused.

```bash
curl -s -X POST "https://api.closefinch.com/v1/connections/$ID/slack/members/$USER_ID/promote" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/connections/${id}/slack/members/${userId}/promote`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### GET /v1/connections/$ID/snippet

The website/app snippet for the first-party intent client (intent_js connections)

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

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

### GET /v1/integrations

Available integrations (and whether this server is set up for them) plus your organization's connections

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

```js
const res = await fetch(`https://api.closefinch.com/v1/integrations`, {
  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).