Define an alternate key on the Dataverse table via the customisation editor, selecting one or more fields that form a unique natural key (e.g. an external system ID)
Issue a PATCH to <org>/api/data/v9.2/<EntitySet>(<keyfield>=<value>) — Dataverse performs an upsert: creates the record if absent, updates it if found
For composite alternate keys, use the format (<field1>=<val1>,<field2>=<val2>) in the URL
Set the 'If-Match: *' header on the PATCH to force an update-only operation (fails with 412 if the record does not exist); omit it for true upsert behaviour
Check that alternate key fields are indexed; Dataverse triggers asynchronous index build on key creation, and upserts against a key that is still indexing can fail transiently
Known gotchas
Alternate key field values are case-sensitive for string keys; mismatched case creates a duplicate record instead of updating the existing one
If the alternate key includes a lookup field, the key value must be the GUID of the related record, not a display name — this partially defeats the purpose of avoiding GUID lookups
Alternate key index creation runs asynchronously; immediately testing upserts after creating the key in a fresh environment may produce intermittent failures until indexing completes
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp