# API: Schema

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/backfills/:id` | One backfill run: progress, changes, errors with sample records | `records:read` |
| POST | `/v1/backfills/:id/cancel` | Stop a queued or running backfill (records already done keep their values) | `settings:write` |
| DELETE | `/v1/fields/:id` | Archive a custom field (owner). Existing values are kept but not returned until it's restored. | `settings:write` |
| PATCH | `/v1/fields/:id` | Rename a custom field or change its options (owner). The type can't change. Send an option's id to change its value: records holding the old value are updated. | `settings:write` |
| POST | `/v1/fields/:id/backfill` | Recompute a computed field across existing records in the background: all, only empty ones, or those matching a filter. test_record_ids runs on those records only first. | `settings:write` |
| GET | `/v1/fields/:id/backfills` | Backfill runs of a field, newest first | `records:read` |
| POST | `/v1/fields/:id/restore` | Restore an archived custom field (owner). Its kept values come back. | `settings:write` |
| GET | `/v1/objects` | Every object type (built-in and custom) with its fields; include_archived=true adds archived custom objects and archived fields (to restore) | `records:read` |
| POST | `/v1/objects` | Create a custom object (owner) | `settings:write` |
| DELETE | `/v1/objects/:key` | Archive a custom object (owner). Its records are kept; restore with POST /v1/objects/{key}/restore. | `settings:write` |
| PATCH | `/v1/objects/:key` | Rename a custom object (owner). The key stays the same. | `settings:write` |
| POST | `/v1/objects/:key/restore` | Restore an archived custom object (owner) | `settings:write` |
| POST | `/v1/objects/:object/fields` | Add a typed custom field to an object (owners; members too when Settings → CRM allows it). Required fields apply to records created afterwards. | `records:write` |
| POST | `/v1/objects/:object/formula-preview` | Check a formula and evaluate it on sample records (the 5 most recently changed, or up to 10 given) without saving anything | `records:read` |

## Examples

### GET /v1/backfills/$ID

One backfill run: progress, changes, errors with sample records

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

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

### POST /v1/backfills/$ID/cancel

Stop a queued or running backfill (records already done keep their values)

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

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

### DELETE /v1/fields/$ID

Archive a custom field (owner). Existing values are kept but not returned until it's restored.

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

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

### PATCH /v1/fields/$ID

Rename a custom field or change its options (owner). The type can't change. Send an option's id to change its value: records holding the old value are updated.

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

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

### POST /v1/fields/$ID/backfill

Recompute a computed field across existing records in the background: all, only empty ones, or those matching a filter. test_record_ids runs on those records only first.

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

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

Backfill runs of a field, newest first

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

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

### POST /v1/fields/$ID/restore

Restore an archived custom field (owner). Its kept values come back.

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

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

Every object type (built-in and custom) with its fields; include_archived=true adds archived custom objects and archived fields (to restore)

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

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

### POST /v1/objects

Create a custom object (owner)

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

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

### DELETE /v1/objects/$KEY

Archive a custom object (owner). Its records are kept; restore with POST /v1/objects/{key}/restore.

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

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

### PATCH /v1/objects/$KEY

Rename a custom object (owner). The key stays the same.

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

```js
const res = await fetch(`https://api.closefinch.com/v1/objects/${key}`, {
  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/objects/$KEY/restore

Restore an archived custom object (owner)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/objects/${key}/restore`, {
  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/objects/$OBJECT/fields

Add a typed custom field to an object (owners; members too when Settings → CRM allows it). Required fields apply to records created afterwards.

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

```js
const res = await fetch(`https://api.closefinch.com/v1/objects/${object}/fields`, {
  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/objects/$OBJECT/formula-preview

Check a formula and evaluate it on sample records (the 5 most recently changed, or up to 10 given) without saving anything

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

```js
const res = await fetch(`https://api.closefinch.com/v1/objects/${object}/formula-preview`, {
  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).