Keeping another system in step

If you are keeping another system in step with DealJourney, you do not have to download everything and work out the difference yourself. Three things fit together, and you will normally use all of them.

Ask whether anything changed. GET /api/v1/changes/fingerprint answers with one number per record type and nothing else. Store those numbers. When they come back the same, nothing has moved and you have transferred no records to establish that. Send the response's etag back in an If-None-Match header and an unchanged workspace replies with a bare "not modified", which is about as cheap as a question gets.

Ask what changed. GET /api/v1/changes?since= lists every create, edit and deletion in the order it happened. Work through it, remember the position it hands back, and carry on from there next time.

Fetch the records. Every list endpoint now takes changed_since, so you can pull just the customers, invoices or deals that actually moved.

Your first run

Call GET /api/v1/changes with no position at all. You get an empty list and a number marking where the feed stands today. Read whatever you need in full, then follow the feed from that number. Anything that changes while you are reading lands after that point and is handed to you again, so nothing slips through the gap.

Deletions only come from the feed

This is the part most integrations get wrong. A record that has been deleted cannot appear in a list of records, so if you only ever look at what changed, you keep rows we no longer have, forever. The feed marks them deleted, and that is the only place you will see it.

Three things to design for

The same change may arrive twice. If a record is edited while you are halfway through reading a page, we hand it to you again rather than risk skipping it. Applying a change you have already applied has to be harmless on your side. We would always rather repeat something than lose it.

Use the cursor, not an offset, for anything large. Pass back the next_cursor you were given. Offsets shift underneath you when records are being created at the same time, which is how rows get read twice or missed.

Come back inside the replay window. The feed keeps a fixed number of days of history, and the response tells you how many. If you have been away longer than that, you will get a clear error asking you to start again from a fresh position rather than a quietly incomplete answer. You will never be told "nothing changed" when the truth is that we no longer hold that far back.

Use your own reference numbers

Keeping our ids on your side is normal and you should keep doing it. What usually goes missing is the other direction: handing us your own reference and asking which of our records it is. You can now do that.

Pick a short name for your system, send up to five hundred of your references at a time, and get back our record for each one, or nothing where we have never been told. Then link the ones you create, and from that point either side can find the other.

Three situations this is really for:

Starting against a workspace that already has data. Resolve your whole list first, create only what came back empty, and you will not end up with a second copy of every customer that was already there under a slightly different spelling.

A write you are not sure landed. Resolve before you create. A create that timed out and is retried stops being a risk, because you find the record you already made instead of making another.

Losing your own mapping. A new environment, a restore, a bad day. Rebuild it in one pass instead of matching on names and email addresses.

It is also worth looking at which systems a record is already linked to before adding your own. Our accounting and CRM connectors record their links in the same place, so a customer may already be connected to an accounting system.

Supported for customers, contacts, leads and products today.

Careful with filters

If you ask for only active customers and only what changed, a customer that has just been made inactive is not in the answer at all. Nothing tells you it left your filter. The changes feed does not filter anything, so it still reports the edit, which is another reason to reconcile against it rather than trusting a filtered list on its own.

What about webhooks?

Webhooks are still the fastest way to react to something the moment it happens: Webhooks. The changes feed is what you fall back on when your endpoint was down, when you are starting from scratch, or when you want to be certain you have everything. Most solid integrations listen to webhooks and reconcile against the feed on a schedule.

The full technical reference, with request and response examples, is in the integration guide at /api/v1/docs/llm.txt, and the endpoints themselves are in the API reference: The REST API.