# API: CRM migration

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/crm-migrations` | Migrations, newest first (last 20) | `records:read` |
| POST | `/v1/crm-migrations` | Start a migration: the agent reads the CRM's objects (or the uploaded files' columns) and proposes a field and pipeline map. Nothing is written until you confirm. (web app only) | `records:write` |
| GET | `/v1/crm-migrations/:id` | A migration: proposal, progress per object (done/total), rate per hour, ETA and per-record errors | `records:read` |
| PATCH | `/v1/crm-migrations/:id` | Edit the proposed map before confirming (map to another field, create a custom field, skip, include objects, pipeline and stage choices) (web app only) | `records:write` |
| POST | `/v1/crm-migrations/:id/cancel` | Stop a migration; records already migrated stay and the connection returns to its previous mode (web app only) | `records:write` |
| POST | `/v1/crm-migrations/:id/confirm` | Confirm the map (optionally with last edits): creates custom fields, pipelines and stages, switches the connection to migrate (nothing is pushed) and starts the run (web app only) | `records:write` |
| POST | `/v1/crm-migrations/:id/cut-over` | After a finished CRM migration: run both in parallel (sync), keep the CRM as the system of record (overlay), or disconnect it (web app only) | `records:write` |
| GET | `/v1/crm-migrations/sources` | Connected CRMs a migration can pull from | `records:read` |

## Examples

### GET /v1/crm-migrations

Migrations, newest first (last 20)

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

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

### GET /v1/crm-migrations/$ID

A migration: proposal, progress per object (done/total), rate per hour, ETA and per-record errors

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

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

### GET /v1/crm-migrations/sources

Connected CRMs a migration can pull from

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

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