Define an alternate key on the Dataverse table in the Power Platform maker portal or via solution import, specifying one or more column logical names that together form a unique key
Wait for the alternate key status to show as Active — key creation indexes the table asynchronously and can take minutes to hours for large tables
Construct the upsert request URL using the alternate key syntax: /api/data/vX.X/<entitysetname>(<keyname>=<value>) for a single-attribute key, or (<key1>=<val1>,<key2>=<val2>) for a composite key
Send a PATCH request with the record data as a JSON body; include the If-Match: * header to update only if the record exists, or omit the header to allow creation if not found (true upsert behavior)
On a 201 Created response the record was inserted; on 204 No Content the record was updated — use these status codes to track create vs. update for downstream logic
Handle 412 Precondition Failed when If-Match: * is used but no matching record exists, and 404 when the alternate key value does not match any record
Known gotchas
Alternate key columns must have the Searchable attribute enabled and cannot include columns that participate in certain computed or rollup field configurations — validate key eligibility before designing an integration around a specific column
URL-encoding is required for alternate key values containing special characters (spaces, ampersands, slashes); failure to encode produces a 400 that Dataverse reports as an invalid key format rather than a URL parsing error
Composite alternate keys require ALL key columns to be present in the URL — omitting one column causes Dataverse to return a generic 404 rather than a meaningful key validation error
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