Define an alternate key on the Dataverse table in the Power Apps maker portal: go to Table > Keys, create a key on one or more fields (e.g., an external integration ID field), and wait for the key's status to become Active.
Reference the table row using the alternate key in the URL: PATCH https://<org>.crm.dynamics.com/api/data/v9.2/<entitySetName>(<keyFieldLogicalName>='<keyValue>') with Content-Type: application/json.
Include the fields to set or update in the JSON request body; if the record does not exist, Dataverse creates it using the key value and body fields; if it exists, it updates the matching record.
Add the header If-None-Match: * to prevent accidental updates (insert-only) or If-Match: * to prevent accidental inserts (update-only); omitting both allows true upsert behavior.
A successful upsert returns HTTP 204 (update) or HTTP 201 (insert); the OData-EntityId response header on a 201 contains the URL with the new record's primary GUID.
For composite alternate keys (multiple fields), include all key fields in the URL: (<field1>='<v1>',<field2>='<v2>').
Known gotchas
Alternate keys must be in Active status before they can be used in API calls — key activation is asynchronous and can take several minutes after creation; attempting to use an activating key returns 400.
If the alternate key field is a lookup (foreign key), you cannot use the alternate key syntax for that lookup field in the URL — alternate key upsert works only on primitive-type key fields.
Dataverse does not support alternate key upsert for virtual tables or tables where the key contains a field with a custom type plugin override — test upsert behavior in a sandbox before relying on it in production.
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