# API: Imports

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/imports` | Imports, newest first | `records:read` |
| POST | `/v1/imports` | Upload a CSV/TSV (up to 20 MB) or an .xlsx (base64, up to 15 MB), up to 100,000 rows. Returns suggested column mapping and detected formats; nothing is imported until you start it. | `records:write` |
| GET | `/v1/imports/:id` | An import with progress, stats, errors and a sample of rows | `records:read` |
| POST | `/v1/imports/:id/cancel` | Stop an import that hasn't finished; rows already imported stay. 409 once it has finished. | `records:write` |
| POST | `/v1/imports/:id/start` | Confirm the column mapping and dedupe rule, then import in the background | `records:write` |

## Examples

### GET /v1/imports

Imports, newest first

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

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

### POST /v1/imports

Upload a CSV/TSV (up to 20 MB) or an .xlsx (base64, up to 15 MB), up to 100,000 rows. Returns suggested column mapping and detected formats; nothing is imported until you start it.

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

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

An import with progress, stats, errors and a sample of rows

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

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

### POST /v1/imports/$ID/cancel

Stop an import that hasn't finished; rows already imported stay. 409 once it has finished.

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

```js
const res = await fetch(`https://api.closefinch.com/v1/imports/${id}/cancel`, {
  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/imports/$ID/start

Confirm the column mapping and dedupe rule, then import in the background

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

```js
const res = await fetch(`https://api.closefinch.com/v1/imports/${id}/start`, {
  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();
```

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).