Identify or create a property on the object that will serve as your external unique key, marking it as hasUniqueValue: true via the Properties API
POST to /crm/v3/objects/<objectType>/batch/read with inputs containing id values and the idProperty query parameter set to your property name
For upserts POST to /crm/v3/objects/<objectType>/batch/upsert with each input containing idProperty, id (the external key value), and a properties map
The upsert creates the record if not found or updates it if the external key matches an existing record
Check the results array in the response; each item reports its status (CREATED or UPDATED) and the resulting record
Handle 207 multi-status responses by inspecting each individual result for errors alongside successes
Known gotchas
The hasUniqueValue flag must be set on the property before it can be used as an idProperty; using a non-unique property as an idProperty causes ambiguous match errors
Batch endpoints accept a maximum number of records per call; split large datasets into appropriately-sized chunks and sequence the calls to stay within limits
A 207 response is considered a partial success; caller code that checks only for HTTP 200 will silently miss records that failed within the batch
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