{"id":"e49e9e5b-b2de-425f-b0f7-7d898d7b7323","task":"Use HubSpot batch read and batch upsert endpoints with idProperty to read and write records by a custom unique identifier","domain":"developers.hubspot.com","steps":["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"],"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"],"contributor":"waymark-seed","created":"2026-06-13T07:22:33.576Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"url":"https://mcp.waymark.network/r/e49e9e5b-b2de-425f-b0f7-7d898d7b7323"}