> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcurrent.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# Business record sync

> Keep your systems and Current in sync — push record changes and pull ours as a change feed

Business record sync lets you keep a customer's business records aligned between your systems and Current. It works in two directions:

* **Push** — send record changes to Current with an upsert (`POST`/`PUT /businesses`)
* **Pull** — read Current's records as a change feed (`GET /businesses?updated_since=...`)

Both operate only on the business records belonging to your API key's organization.

## Identity model

Every business is matched using one of two keys:

| Key | Fields | Notes |
| - | - | - |
| **External ID** (preferred) | `externalId` | Your own id for the business (e.g. a CRM record id). Unique within your organization. |
| **Registry natural key** | `jurisdiction` + `registrationNumber` | The official identity of the business in the Canadian registry. |

An upsert matches on `externalId` first, then falls back to the natural key. Set `externalId` on your records — it's the most reliable way to keep the two systems linked, and it lets you look a record up directly with `GET /businesses?external_id=...`.

> [!NOTE]
>
> `businessNumber` is **not** a match key — it isn't guaranteed unique. Use
> `externalId` or the natural key.

## Push: create or update a record

`POST /businesses` (or `PUT` — they're equivalent) upserts a single record. If a match is found it's updated in place; otherwise a new record is created.

```bash theme={null}
curl -X POST https://api.getcurrent.ca/v1/businesses \
  -H "Authorization: Bearer cur_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "crm_8842",
    "name": "Shopify Inc.",
    "jurisdiction": "ON",
    "registrationNumber": "2033076",
    "email": "contact@shopify.com",
    "originationDate": "2024-03-01"
  }'
```

* **`200`** — an existing record was updated
* **`201`** — a new record was created

```json theme={null}
{
  "business": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "externalId": "crm_8842",
    "name": "Shopify Inc.",
    "jurisdiction": "ON",
    "registrationNumber": "2033076",
    "email": "contact@shopify.com",
    "originationDate": "2024-03-01",
    "isMonitored": true,
    "isArchived": false,
    "verificationStatus": null,
    "createdAt": "2026-07-07T15:00:00Z",
    "updatedAt": "2026-07-07T15:00:00Z"
  }
}
```

### Update semantics

* **Only the fields you send are written.** Omitted fields are left unchanged — a `POST` with just `{ "externalId": "crm_8842", "email": "new@shopify.com" }` updates the email and nothing else.
* **Array fields replace** the stored value (send the full list you want, not a delta).
* Every changed field is recorded in an **append-only audit trail** (who/when/field/old→new), so changes made through the API are traceable for compliance.

### Who owns which fields

The fields in this request are **yours** — your push is the source of truth for them, and our verification pipeline never overwrites them. Activity-derived fields — `verificationStatus`, `lastVerifiedAt`, `latestVerificationId`, `lastVerificationJobId`, `hasUnresolvedDiscrepancies`, `lastSearchedAt`, `lastSearchJobId`, `lastScreenedAt`, and `verification` results — are **ours**: they are read-only over this API and are not affected by your writes. (The `*JobId` fields point to the batch job behind the most recent verification/search, or are null when it was run individually.) Because the two sets are disjoint, your sync and our verification never fight over a value.

### Avoiding lost updates (optional)

If two of your systems can push the same record, pass `expectedUpdatedAt` with the `updatedAt` you last read. If the record changed in between, the write is rejected with **`409`** (`code: "STALE_WRITE"`) instead of silently overwriting — re-read and retry. Omit it to always overwrite (last-write-wins).

### Required fields

You must supply a match key — either `externalId`, or **both** `jurisdiction` and `registrationNumber`. When a record is created (no existing match), `name` is also required.

### Common fields

| Field | Type | Description |
| - | - | - |
| `externalId` | string | Your internal id. Unique per organization. |
| `name` | string | Legal/display name. Required on create. |
| `jurisdiction` | string | Canadian jurisdiction code or full name (normalized server-side). |
| `registrationNumber` | string | Registration number from the registry. |
| `businessNumber` | string | CRA business number. |
| `entityType`, `registryStatus` | string | Registry classification and status. |
| `website`, `phoneNumber`, `email` | string | Primary contact details. |
| `street`, `unit`, `city`, `province`, `postalCode`, `country` | string | Primary address. |
| `notes` | string | Free-text notes. |
| `originationDate` | string | `YYYY-MM-DD` — when the business became your customer. |
| `businessDescription` | string | Free-text description of the business. |
| `incorporationDate` | string | `YYYY-MM-DD` — full incorporation date, when known. |
| `incorporationYear` | integer | Year of incorporation, when only the year is known. |
| `industry`, `industryCategory` | string | Industry/sector label and higher-level category. |
| `naicsCode`, `naicsCodeName` | string | NAICS code and human-readable description. |
| `isMonitored`, `isArchived` | boolean | Monitoring and archival flags. |
| `operatingNames`, `additionalWebsites` | string\[] | Replace-on-write arrays. |
| `people` | array | Each `{ name, role \| roles[], email }`. Replaces the stored list. |

See the [API reference](https://docs.getcurrent.ca/api-reference/upsert-business) for the complete field list.

## Pull: read records as a change feed

`GET /businesses` lists your records ordered oldest-change-first. Pass `updated_since` on the first request to fetch only records changed since your last sync, then keep re-requesting with the opaque `cursor.next` token until `pagination.hasMore` is `false`.

```bash theme={null}
curl "https://api.getcurrent.ca/v1/businesses?updated_since=2026-07-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer cur_live_xxxxxxxxxxxx"
```

```json theme={null}
{
  "businesses": [ { "id": "...", "externalId": "crm_8842", "updatedAt": "2026-07-03T09:12:44Z", ... } ],
  "pagination": { "limit": 100, "hasMore": false },
  "cursor": { "next": "MjAyNi0wNy0wM1QwOToxMjo0NFp8Li4u" }
}
```

### Query parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | Opaque continuation token from a prior response's `cursor.next`. Takes precedence over `updated_since`. |
| `updated_since` | string | Return only records with `updatedAt` after this ISO 8601 timestamp. Used only on the first request. |
| `external_id` | string | Return the single record matching this external id. |
| `archived` | boolean | Filter by archived status. |
| `monitored` | boolean | Filter by monitoring status. |
| `limit` | integer | Page size, 1–100 (default 50). |

### Sync loop

Persist the cursor between runs. On the first run start from `updated_since`; on every later request pass the token back verbatim:

```text theme={null}
cursor = load_saved_cursor()            // opaque token, or none on first run

loop:
  if cursor:
    resp = GET /businesses?cursor={cursor}&limit=100
  else:
    resp = GET /businesses?updated_since={last_sync}&limit=100
  process(resp.businesses)              // upsert into your system
  cursor = resp.cursor.next             // advance
  save_cursor(cursor)
  if not resp.pagination.hasMore:
    break                               // caught up; resume here next run
```

> [!NOTE]
>
> The feed is ordered by `updatedAt` then `id` ascending, and the cursor carries
> both, so it always moves forward and never skips records that share an
> `updatedAt` (as happens when a bulk import stamps many rows at once). Run it
> on whatever cadence fits — every few minutes for near-real-time, or
> hourly/daily for a periodic reconcile.

## What updates a record on our side

Records change (and therefore appear in the feed) when:

* You upsert them via `POST`/`PUT /businesses`
* A [verification](https://docs.getcurrent.ca/guides/verification.md) runs and refreshes the registry fields
* A user edits the record in the Current app
* A Google Drive export files reports for the business into a new folder (see below)

> [!WARNING]
>
> **Monitoring alerts do not automatically rewrite the record.** When monitoring
> detects a registry change, sanctions hit, or adverse-media mention, it raises
> an *alert* — it doesn't overwrite the stored business fields. Registry fields
> are refreshed on the record (and surface in this feed as an update) when a
> verification runs against that business.

## Google Drive folder

When your team exports reports to Google Drive from the Current app, each business gets one persistent folder, named `<name> (<externalId>)`, inside a **Current Reports** folder in Drive. Every business record carries a link to its folder in `driveFolderUrl`, so you can link to it from your own systems:

```json theme={null}
{
  "id": "...",
  "externalId": "crm_8842",
  "driveFolderUrl": "https://drive.google.com/drive/folders/1AbCdEfGhIjKlMnOp",
  ...
}
```

* `driveFolderUrl` is `null` until a Drive export has filed a report for the business.
* The record's `updatedAt` advances when the link first appears or changes, so the change feed picks it up.
* The folder lives in the Google Drive of the team member who ran the export. It opens for that person and for anyone they share it (or the **Current Reports** folder) with.

## Errors

| Status | Meaning |
| - | - |
| `400` | Missing match key, missing `name` on create, invalid jurisdiction, or malformed body. |
| `401` | Missing or invalid API key. |
| `409` | The record conflicts with an existing one on registration number or external id. |
| `429` | Rate limit exceeded. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.