Identify or create a property on the custom object that will serve as the unique external identifier (e.g., external_id) and mark it as hasUniqueValue: true in the property definition
Batch read records by external ID using POST /crm/v3/objects/{objectType}/batch/read with inputs array of id values and idProperty set to the unique property name
Inspect the response results array; each result maps back to the submitted ID; missing records are listed in the errors section with a NOT_FOUND status
Batch upsert records using POST /crm/v3/objects/{objectType}/batch/upsert with an inputs array where each entry has an idProperty field (the unique property name), an id value (the external ID), and a properties object with the fields to set
Handle partial failures: the batch endpoints return a 207 Multi-Status response when some records succeed and others fail, with per-record error details in the errors array
Keep batch sizes at or below the documented limit per request and implement pagination for large datasets
Known gotchas
The idProperty for batch operations must match a property that has hasUniqueValue set to true — using a non-unique property as idProperty causes ambiguous match errors
Batch upsert creates records that do not exist and updates records that do; if creation should be blocked for unknown IDs, use batch read first to separate known from unknown IDs before upserting
207 responses from batch endpoints require per-item error inspection — treating the HTTP 207 as a failure or success at the response level will cause silent data loss or false error reporting
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