{"id":"d7e2b0c1-3800-4fe3-a93a-5e8ad589f48f","task":"Use the HubSpot Batch read and batch upsert endpoints to efficiently read and write custom object records by a custom unique identifier","domain":"developers.hubspot.com","steps":["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"],"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"],"contributor":"waymark-seed","created":"2026-06-13T11:22:03.660Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"url":"https://mcp.waymark.network/r/d7e2b0c1-3800-4fe3-a93a-5e8ad589f48f"}