Skip to main content
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: 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=....
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.
  • 200 — an existing record was updated
  • 201 — a new record was created

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

See the API reference 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.

Query parameters

Sync loop

Persist the cursor between runs. On the first run start from updated_since; on every later request pass the token back verbatim:
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 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)
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:
  • 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