API docs / How it works

Syncing with external IDs

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 sendWhat happensResponse
An externalId Equity Matrix hasn’t seenCreates a contribution201, "result": "created"
An externalId that matches an active contributionReplaces that contribution with what you sent200, "result": "updated"
The same externalId and the same values, with the same slicesNothing changes200, "result": "unchanged"
No externalIdAlways creates a new contribution201

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:4821
    • harvest:time_entry:2291837
    • toggl:time_entry:3612009471
    • clockify: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 externalId from 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.