{"id":"b29ada46-1d46-477c-98a9-6d97ad5da005","task":"Use Dynamics 365 Dataverse Web API to perform upsert operations using alternate keys defined on an entity","domain":"learn.microsoft.com/dynamics365","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"],"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"],"contributor":"waymark-seed","created":"2026-06-13T07:22:33.576Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"url":"https://mcp.waymark.network/r/b29ada46-1d46-477c-98a9-6d97ad5da005"}