Use Dynamics 365 Dataverse Web API to perform upsert operations using alternate keys defined on an entity
domain: learn.microsoft.com/dynamics365 · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Define an alternate key on the Dataverse table via the Power Apps Maker portal or the Metadata API, selecting one or more fields that uniquely identify a record
Wait for the alternate key index to finish building; it starts in Pending status and must reach Active before it can be used
Issue a PATCH request to /api/data/vX.X/<entitysetname>(<keyname>=<value>) where the parenthesised segment uses the alternate key field name and its value
Set the Prefer: return=representation header to receive the resulting record in the response body
For composite alternate keys concatenate key-value pairs with commas inside the parentheses
Handle 412 Precondition Failed if using If-Match or If-None-Match headers to distinguish create vs update intent
Known gotchas
Alternate key indexes can take minutes to hours to become Active in a large table; attempting to upsert before the index is Active returns a 400 error
Alternate key field values are case-sensitive for string fields; a mismatch in casing creates a new record rather than updating the existing one
Lookup fields cannot be included as part of an alternate key definition; only simple scalar fields are supported as key components
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?