- 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=...)
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 updated201— a new record was created
Update semantics
- Only the fields you send are written. Omitted fields are left unchanged — a
POSTwith 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, passexpectedUpdatedAt 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 — eitherexternalId, 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 fromupdated_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)
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:
driveFolderUrlisnulluntil a Drive export has filed a report for the business.- The record’s
updatedAtadvances 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.