We’re integrating self-hosted Invoice Ninja with an external identity service. We want separate external UUIDs on clients and client contacts, using a text custom field on each. Is this the recommended approach? Can these fields be kept internal and protected from manual edits? Are there any caveats around contact updates, merging records, or exact UUID lookup?
The unresolved issue is how reliably we maintain the reference, rather than whether Ninja can store it.
Hi,
You can use custom fields to store the values however the app doesn’t have a way to enforce that the values aren’t changed.
Since the app can’t lock the field, I’d treat the identity service as the source of truth and assume the custom field will drift sooner or later. What’s worked for me with CRM syncs in general:
Store the reference both ways. Put the Invoice Ninja client id on the record in your identity service too, so you can rebuild the custom field from the other side if someone edits or clears it.
Run a small reconciliation job, nightly is usually enough. Pull all clients and contacts through the API, compare the UUID field against your side, and log mismatches instead of auto-fixing them. Duplicates and blanks show up fast that way.
On merges, decide up front which UUID survives and write that down. Merged records are where these references usually break quietly.
For lookups I’d match on the Ninja id you stored, not a text search on the custom field. Exact matching on free text fields tends to bite you with trailing spaces or case.
Supported by Invoice Ninja and Event Schedule