Send each record's ID from the other system, and Equity Matrix keeps one contribution per record, however many times you send it.
When another tool sends you records, the same record often arrives more than once: it gets edited, a sync is retried, or a backfill overlaps an earlier one. The externalId field is what stops those from turning into duplicate slices.
How it works
Put the record’s ID from the other system in externalId when you create or update a contribution:
| What you send | What happens | Response |
|---|---|---|
An externalId Equity Matrix hasn’t seen | Creates a contribution | 201, "result": "created" |
An externalId that matches an active contribution | Replaces that contribution with what you sent | 200, "result": "updated" |
The same externalId and the same values, with the same slices | Nothing changes | 200, "result": "unchanged" |
No externalId | Always creates a new contribution | 201 |
An update is a full replace. Any field you leave out is cleared or reset. So send the whole record every time, not just what changed.
Two requests with the same new externalId arriving at the same moment still produce one contribution. The second gets a 409 with the error code conflict. Retry it once and it updates the contribution the first one created.
Choosing an external ID
- Up to 100 characters: letters, numbers and
. _ : -. - Unique within your organization.
- Put the tool and the record type in front of the record’s ID, so IDs from different places can’t collide. For example:
odoo:account.analytic.line:4821harvest:time_entry:2291837toggl:time_entry:3612009471clockify:time_entry:66f1c0a9e4b0a1
Deleting
When a record is deleted in the other tool, delete the contribution by its external ID. After that, sending the same externalId again creates a new contribution.
Things to know
- Always send an
externalIdfrom a sync. Without one, a retry after a timeout can create a duplicate. - Edits in Equity Matrix can be overwritten. If someone edits an API contribution in the app, the next resend from the other tool replaces their changes.
- Deleting in Equity Matrix doesn’t stop the other tool. If the record still exists there and gets resent, it comes back. Remove or exclude it in the other tool instead.