# API: Organization

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/first-run` | Your first-run checklist: mailbox connected, accounts and contacts filling in (live counts), first agent run | `settings:read` |
| GET | `/v1/invitations` | List pending invitations (owner) | `members:write` |
| POST | `/v1/invitations` | Invite someone by email (owner, web only) (web app only) | `members:write` |
| DELETE | `/v1/invitations/:id` | Cancel a pending invitation (owner, web only) (web app only) | `members:write` |
| POST | `/v1/invitations/:id/resend` | Resend a pending invitation (owner, web only) (web app only) | `members:write` |
| GET | `/v1/members` | List members and their roles | `members:read` |
| DELETE | `/v1/members/:id` | Remove a member and revoke their API keys and app connections (owner) | `members:write` |
| PATCH | `/v1/members/:id` | Change a member's role (owner) | `members:write` |
| GET | `/v1/members/former` | People who still own records here but are no longer members (to reassign their work) | `members:read` |
| DELETE | `/v1/organization` | Schedule the organization's deletion: it's suspended at once and, unless an owner undoes it within 30 days, purged with all its data, including audit history (owner, web only, the exact name to confirm) (web app only) | `security:write` |
| GET | `/v1/organization` | Get the active organization | `settings:read` |
| PATCH | `/v1/organization` | Rename the organization (owner) | `security:write` |
| POST | `/v1/organization/acquisition` | Record how this organization found us (first answer kept; owners). Only the referrer's host name is stored | `settings:read` |
| GET | `/v1/organization/deletion` | Whether the organization is scheduled for deletion, and when it will be purged (answers while it's suspended) (web app only) | — |
| POST | `/v1/organization/deletion/cancel` | Undo the organization's scheduled deletion before its window ends (owner, web only) (web app only) | `security:write` |
| GET | `/v1/organization/exports` | Your exports of this organization (owner; each holds what its requester could read, so it's theirs alone) | `security:write` |
| POST | `/v1/organization/exports` | Export everything this organization holds (every table, as gzipped JSON lines, secrets left out); ready to download for 7 days (owner) (web app only) | `security:write` |

## Examples

### GET /v1/first-run

Your first-run checklist: mailbox connected, accounts and contacts filling in (live counts), first agent run

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

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

### GET /v1/invitations

List pending invitations (owner)

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

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

### GET /v1/members

List members and their roles

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

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

### DELETE /v1/members/$ID

Remove a member and revoke their API keys and app connections (owner)

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

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

### PATCH /v1/members/$ID

Change a member's role (owner)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/members/${id}`, {
  method: "PATCH",
  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/members/former

People who still own records here but are no longer members (to reassign their work)

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

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

### GET /v1/organization

Get the active organization

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

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

### PATCH /v1/organization

Rename the organization (owner)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/organization`, {
  method: "PATCH",
  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/organization/acquisition

Record how this organization found us (first answer kept; owners). Only the referrer's host name is stored

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

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

Your exports of this organization (owner; each holds what its requester could read, so it's theirs alone)

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

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