Short answer
POST /crm/v3/objects/{object}/batch/upsert creates or updates records identified by a unique property value. Each input names the idProperty (a property whose values are unique for the object), the id value, and the properties to set. Records with that value are updated; missing ones are created. It avoids the race in search-then-create scripts.
1. The request
POST https://api.hubapi.com/crm/v3/objects/companies/batch/upsert
{
"inputs": [
{
"idProperty": "erp_account_number",
"id": "100245",
"properties": { "name": "Example Co", "city": "Austin" }
}
]
}Here erp_account_number is a custom property set to require unique values. See unique value properties.
2. Why it matters
The usual cause of API duplicates is a script that searches, finds nothing because the search index lags, and creates a second record. See API scripts that create duplicates. Upsert removes the search step.
3. Notes
- Batch requests count as one call against rate limits. See rate limits.
- Contacts can be upserted by email as the idProperty.