Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Sync

Keep another system in step with Shortcut using updatedSince and createdSince, with a watermark and a five-minute overlap.

After this page you can copy Shortcut records into another system and keep that copy current with one small loop, without missing a change and without re-reading everything.

How incremental sync works

Lists that support sync take an updatedSince timestamp. With it, the list:

  • returns every record whose updatedAt is at or after the timestamp (inclusive);

  • is ordered by updatedAt, oldest change first, then by id;

  • pages with a cursor on that same order, so records that changed in the same millisecond are never skipped between pages.

Without updatedSince, lists are ordered newest first by createdAt, which is right for browsing and wrong for sync.

curl "https://api.shortcutco.com/v1/visits?updatedSince=2026-10-16T13:55:00Z&limit=200" \
  -H "Authorization: Bearer $SHORTCUT_TOKEN"
{
  "data": [
    {
      "id": "5e0c8a1f-2b7d-4c3e-9f6a-8d1b2c3e4f50",
      "object": "visit",
      "date": "2026-10-16",
      "status": "completed",
      "closeReason": null,
      "reason": null,
      "jobId": "a4f1c9e2-7b3d-4e8a-9c5f-1d2e3f4a5b6c",
      "jobName": "Weekly mowing",
      "customerId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "propertyId": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
      "address": "412 Elm St, Bozeman, MT 59715",
      "assignedTeamId": null,
      "effectiveTeamId": "6c7d8e9f-0a1b-4c2d-8e3f-4a5b6c7d8e9f",
      "routePosition": 3,
      "plannedStartAt": "2026-10-16T16:30:00.000Z",
      "plannedEndAt": "2026-10-16T17:00:00.000Z",
      "estimatedDurationMinutes": 30,
      "arrivedAt": "2026-10-16T16:34:51.000Z",
      "completedAt": "2026-10-16T17:02:18.000Z",
      "invoiceId": null,
      "createdAt": "2026-04-02T15:12:44.120Z",
      "updatedAt": "2026-10-16T17:02:18.640Z"
    }
  ],
  "meta": { "nextCursor": null, "hasMore": false }
}

These lists take updatedSince: GET /v1/customers, GET /v1/customers/{id}/properties, GET /v1/leads, GET /v1/estimates, GET /v1/jobs, GET /v1/jobs/{id}/visits, GET /v1/visits, GET /v1/services, GET /v1/products, GET /v1/teams, GET /v1/users, GET /v1/tags, and GET /v1/invoices. GET /v1/payments takes createdSince instead; see below. The OpenAPI description lists every filter each list takes.

The sync loop

  1. Keep a watermark per resource: the largest updatedAt you have stored.

  2. On each run, ask for updatedSince = watermark minus five minutes.

  3. Page until meta.hasMore is false, upserting each record into your copy by id.

  4. Save the largest updatedAt you saw as the new watermark.

The five-minute overlap covers writes that were in flight when your last run read the list: a change whose transaction started before your read but finished after it carries an updatedAt slightly earlier than records you already saw. Re-reading the last five minutes picks those up. The cost is that each run sees a few records again, which is why step 3 upserts by id instead of inserting.

For the first run, start from 1970-01-01T00:00:00Z. The same loop then copies everything, oldest first, and leaves you with a watermark.

Save the watermark only after the whole run succeeds. If a run fails halfway, the next run starts from the old watermark and repeats the pages it already stored, which the upsert absorbs.

Timestamps in responses are all UTC with the same format, so comparing them as strings, as above, orders them correctly.

What changes updatedAt

A record's updatedAt changes when that record changes. Related records sync from their own lists.

  • A customer's updatedAt also changes when a tag is attached to or removed from them (deleting a tag they wear counts) and when one of their custom-field values changes. Saving the same tags or values again changes nothing. Their properties sync from GET /v1/customers/{id}/properties; a property change does not touch the customer.

  • A visit's updatedAt changes when the visit itself changes: its date, status, crew, route position, or times. Its jobName, address, and customerId come from its job and property, and an inherited effectiveTeamId comes from its job's crew; changes there do not touch the visit. To keep those current, re-read the visits you care about, such as the coming week's with from and to.

  • A job's updatedAt changes when the job itself changes: its name, status, price, cadence, or crew. Its nextVisitId, nextVisitDate, effectiveTeamId, and address come from its visits and property, so sync visits from their own list. A price change in the app creates a new job, linked to the earlier one by previousVersionJobId; the earlier one gets an effectiveUntilDate, and both come back in sync.

  • A crew's updatedAt does not change when people join or leave it. To keep membership current, re-list crews, or sync staff, whose teamId changes with their crew.

  • An invoice turning overdue does not change its updatedAt: the status changes on its own when dueAt passes. Re-read open invoices directly, for example GET /v1/invoices?status=unpaid and GET /v1/invoices?status=overdue, rather than relying on sync to see them go overdue.

  • Deactivating a customer or a service, archiving a product or a crew, dismissing a lead, canceling a job or a visit, or voiding an invoice is a change like any other: the record comes back with its new status. Shortcut keeps these records rather than deleting them, so sync never needs a separate deletions feed.

  • Tags and undone manual payments are the records that are deleted outright. Tags are few, so re-list them in full when you need to notice a deleted tag. The customers who wore a deleted tag come back through updatedSince without it.

  • Imports of many records at once, such as a CSV of customers, show up through updatedSince like any other change.

External references

To sync customers, properties, leads, and jobs both ways, store your own id on the Shortcut record instead of keeping a mapping table on your side. An external reference is a source you choose (hubspot, quickbooks, mywebsite: lowercase letters, digits, _, ., -) plus your externalId. Each one belongs to exactly one record of its kind in the workspace, and records carry theirs in externalReferences.

Call
What it does

GET /v1/customers/external/{source}/{externalId}

The customer your id points to, or 404.

PUT /v1/customers/external/{source}/{externalId}

The upsert: creates the customer if your id is new, otherwise updates the one it points to.

GET /v1/customers?externalSource=hubspot&externalId=51234

The same lookup as a list filter. Send both parameters or neither.

POST /v1/customers with externalReference

Creates the customer and saves your id in the same request.

PUT /v1/customers/{id}/external-references/{source}

Links an existing customer to your id, with body { "externalId": "…" }.

DELETE /v1/customers/{id}/external-references/{source}

Unlinks it. The customer itself is unchanged.

Properties have the same calls (GET and PUT /v1/properties/external/{source}/{externalId}, and PUT and DELETE /v1/properties/{id}/external-references/{source}), and POST /v1/customers/{id}/properties takes externalReference too. The property upsert also needs customerId.

Leads and jobs have them as well:

Call
What it does

GET and PUT /v1/leads/external/{source}/{externalId}

Look up, or create or update, the lead your id points to.

GET /v1/leads?externalSource=mywebsite&externalId=form-881

The lead lookup as a list filter.

POST /v1/leads with externalReference

Creates the lead and saves your id in the same request.

PUT and DELETE /v1/leads/{id}/external-references/{source}

Link or unlink an existing lead.

GET and PUT /v1/jobs/external/{source}/{externalId}

Look up, or create or update, the job your id points to.

GET /v1/jobs?externalSource=fieldops&externalId=wo-1042

The job lookup as a list filter.

POST /v1/jobs with externalReference on a service

Saves your id for the job that service creates.

PUT and DELETE /v1/jobs/{id}/external-references/{source}

Link or unlink an existing job.

The lead upsert creates a lead exactly as POST /v1/leads does, with the same rules: it counts toward the 20 leads a minute per workspace, an email that belongs to an existing customer needs customers:write, and the new-lead automations run only with automations:trigger. For a known id it applies the contact fields (names, company, email, phone) and ignores address, servicesRequested, and specialRequests.

The job upsert takes one job as a service of POST /v1/jobs describes it, plus customerId and, optionally, propertyId, name, description, and teamId. For a known id it applies name, description, and teamId and ignores the property, service, cadence, and price. Sending the job's current crew again leaves its visits alone. A customerId other than the job's customer is 409 external_reference_customer_mismatch. A one-time job ignores teamId: null, so a workspace with one crew can sync one-time jobs.

A price change in the app replaces a job with a new version: the old job gets an effectiveUntilDate, and the new one points back to it with previousVersionJobId. Your external id moves to the new version in the same change, so the lookup, the upsert, and the list filter keep finding the job that is current. A request that still names the replaced version (for example, linking it by its old id) is 409 job_superseded, and the message names the current job.

The upsert is the sync call. Send the whole record every time:

  • New id: the customer is created with their first property, as POST /v1/customers does. The answer is 201 with data.created: true.

  • Known id: the fields that differ from what Shortcut has are applied, as PATCH /v1/customers/{id} does, and property is ignored (manage properties with the property endpoints). The answer is 200 with data.created: false. A request that changes nothing writes nothing, so it does not move updatedAt or queue a QuickBooks sync.

  • Two requests for the same id at once run one after another, so they never create two customers. The same holds for every upsert.

Linking is always explicit. Shortcut never matches your id to an existing customer by email or address: an upsert with a new id creates a customer, and if that email already belongs to a customer the request fails with 409 email_in_use. To adopt existing customers, link each one with PUT /v1/customers/{id}/external-references/{source}. An id that already belongs to another record is 409 already_exists, and the message names that record.

The property upsert treats an unchanged address string as unchanged, whatever coordinates you send with it. Moving the address to another spot clears a measured property map, so it needs confirmClearPropertyMap: true; see property_map_would_clear.

Payments sync on createdSince

Payments have no updatedAt. Their list takes createdSince instead, with the same rules: inclusive, oldest first, keep the largest createdAt as the watermark, subtract five minutes, upsert by id.

When the workspace undoes a manual payment, the payment is removed and its invoice's updatedAt changes. Sync invoices alongside payments, and when an invoice changes, re-read its payments with the invoiceId filter.

A refund that succeeds later changes the payment's refundedAmount without changing the payment or its invoice, so neither createdSince nor updatedSince picks it up. To see refunds, re-read the payments you need current: one at a time with GET /v1/payments/{id}, or a recent window again with GET /v1/payments?createdSince=….

Last updated