Question about using batch read API

[LZhao]

Hi,
I am using the /crm/v3/objects/$objType/batch/read POST API to detect deleted or merged objects on HubSpot, but I have a few questions about its behavior to ensure I use it correctly and avoid unintended deletions in my system.
Scenario 1: Deleted Objects
When an object is deleted on HubSpot, the API returns the following response:
{
"results": [],
"errors": [
{
"status": "error",
"category": "OBJECT_NOT_FOUND",
"message": "Could not get some COMPANY objects, they may be deleted or not exist. Check that ids are valid.",
"context": {
"ids": [
"8380080352",
"8144745976",
"7440157923"
]
}
}
]
}
In this case, if category is OBJECT_NOT_FOUND, I can extract the ids from the errors.context.ids array and handle them as deleted objects in my system.

Scenario 2: Merged Objects
Sometimes, contacts in HubSpot are merged. In such cases, the API can return the following response:
{
"results": [
{
"id": "84805801",
"properties": {
"email": "mary.miller@usfoods.com",
"createdate": "2020-03-03T20:18:42.589Z",
"firstname": "Mary",
"hs_object_id": "84805801",
"lastname": "Miller",
"lastmodifieddate": "2024-08-10T23:13:12.293Z"
},
"createdAt": "2020-03-03T20:18:42.589Z",
"updatedAt": "2024-08-10T23:13:12.293Z"
}
]
}
Here, the id in the response (84805801) is different from the id in my original request (62241). This indicates that the contact was merged. In such cases, I also need to remove this record (62241) from my system.

Questions:
1. Are there other scenarios I should consider to avoid mistakenly deleting or overwriting data in my system?
2. For merged objects, is it safe to assume that if the id in the response differs from the id in my request, the object has been merged, and the new ID should be used?
3. Is there a recommended approach to handle errors and results together to ensure I don’t miss any edge cases?
Any insights or recommendations for using this API correctly would be greatly appreciated, thanks

[zach_threadint · Accepted solution]

Hi @LZhao 👋

Overall, I think the approach you've outlined will generally work well. However, you may want to consider some additional cases.

For scenario 1, as long as you know for sure those specific records existed previously in the given HubSpot Portal, then your suggested approach will work in the majority of cases. However, you may want to consider the possibility that these deleted records could be "restored" at a later date. When deleting a record via HubSpot's UI, the user is given 2 choices: [1] Restorable Delete (i.e. record can be restored up to 90 days after deletion), or [2] Permanent Delete (gone forever, not restorable). You can verify which case is true via API by using the "archived" query string parameter (available on single and batch operations). If the record is returned successfully and is marked as "archived": true, then there remains a chance this record could be restored. However, if the record is not found, then it can no longer be restored. See example below for how to include the "archived" query string parameter in your Get Batch Contacts request.

For scenario 2, I would request the "hs_calculated_merged_vids" and "hs_merged_object_ids" properties be returned from your Get Batch Contacts request. This would help to confirm which records have been merged and all the IDs in play. For example:

curl --location 'https://api.hubapi.com/crm/v3/objects/CONTACTS/batch/read?archived=true' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer pat-redacted' \
--data '{
    "properties": [
        "hs_calculated_merged_vids",
        "hs_merged_object_ids"
    ],
    "inputs": [
        {
            "id": "12345"
        },
        {
            "id": "67890"
        }
    ]
}'

Where example response will resemble:

{
    "status": "COMPLETE",
    "results": [
        {
            "id": CURRENT_CONTACT_ID,
            "properties": {
                "createdate": "2024-12-17T19:49:53.973Z",
                "hs_calculated_merged_vids": "OLD_CONTACT_ID_1:CURRENT_CONTACT_ID;OLD_CONTACT_ID_2:CURRENT_CONTACT_ID",
                "hs_merged_object_ids": "OLD_CONTACT_ID_1;OLD_CONTACT_ID_2",
                "hs_object_id": CURRENT_CONTACT_ID,
                "lastmodifieddate": "2025-01-24T19:33:52.320Z"
            },
            "createdAt": "2024-12-17T19:49:53.973Z",
            "updatedAt": "2025-01-24T19:33:52.320Z",
            "archived": false
        }
    ],
    "startedAt": "2025-01-24T19:42:36.198Z",
    "completedAt": "2025-01-24T19:42:36.249Z"
}

I hope this proves helpful. Please let me know if you have any follow-up questions.

[LZhao]

Hi Zach,

This worked for me, thnaks so much. Also got another question, does HubSpot have merged account concept?

[zach_threadint]

Hi @LZhao 👋

If you mean whether it's possible to merge 2 individual "Company" records via API, then yes, that's possible. See HubSpot's "Merge two companies" API endpoint.

I hope that proves helpful. Please let me know if you have any follow-up questions.

[Jaycee_Lewis]

Hi @LZhao 👋 Thanks for your detailed post. That is always appreciated. I'd like to invite some of our community members to the conversation to share their thoughts — hey @zach_threadint @evaldas @TomM2 @Bryantworks, do you have any relevant experience and wisdom you can share with @LZhao?

Thanks! — Jaycee