Contacts API v3 Batch Update using email as Unique Id

[DSmith95]

I am trying to batch update hubspot using the email as the id (as refered to in the batch update API document)

Setting id as the email doesn't work, nor does adding idproperty: "email" to the same level as id.

Changing id : xxx to email : xxx returns a validation error

{

  "inputs": [

    {

      "id": "I Want This to be the email address",

      "properties": {

        "someproperty":"updated"

      }

    },

    {

      "id": "this would be another email address",

      "properties": {

        "someproperty":"updatedalso"

      }

    },

  ]

}

the best error I get that's not a validation failure is

"OBJECT_NOT_FOUND"

"Could not get some CONTACT objects, they may be deleted or not exist. Check that ids are valid"

this is when setting id to the email address

I know these accounts exist - I have checked via the Hubspot UI.

I cannot update using the RecordID as I will not have this available.

Any help would be very appreciated

[CSewell1 · Accepted solution]

@Jaycee_Lewis

Since email was not working as a unique field, I explicitly made another unique field `emailCopy` and then tried hitting the endpoint using that field, but still got the following error message.

Request:
curl --request POST \
--url https://api.hubapi.com/crm/v3/objects/contacts/batch/update \
--header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'content-type: application/json' \
--data '{
"inputs": [
{
"idProperty": "emailCopy",
"id": "test@hello.com",
"properties": {
"role": "user"
}
}
]
}'

Response:

HTTP 400

"message": "Invalid property(ies) supplied as unique properties for upsert operation: [PropertyCoordinates{portalId=7192871, objectTypeId=ObjectTypeId{legacyObjectType=CONTACT}, propertyName=emailCopy}]"

I verified that `emailCopy` is a unique property.

Seems like this endpoint DOES NOT WORK with any unique fields except for `id`.

Also, the documentation on this page is incorrect. The request body (one on the right) is malformed JSON.

[CSewell1 · Accepted solution]

@DSmith95 HERE IS THE SOLUTION ✌🏻

Try this using the v1 APIs. They are quite stable and still supported. The page itself quotes:

"Our APIs are in the midst of a transition. As part of our effort to improve API consistency and completeness, we launched the next generation of HubSpot’s API in early 2020. However, not every endpoint or API has been updated to the latest version, and our older endpoints are still stable and supported."

Use this v1 batch contacts endpoint:

https://legacydocs.hubspot.com/docs/methods/contacts/batch_create_or_update

Use the following example request body

[
    // assume existing email
    {
        "email": "test+old@hello.com",
        "properties": [
            {
                "property": "email",
                "value": "test+old@hello.com"
            },
            {
                "property": "firstname",
                "value": "User"
            },
            {
                "property": "lastname",
                "value": "Old Updated"
            }
        ]
    },
    // new email
    {
        "email": "test+new@hello.com",
        "properties": [
            {
                "property": "email",
                "value": "test+new@hello.com"
            },
            {
                "property": "firstname",
                "value": "User"
            },
            {
                "property": "lastname",
                "value": "New"
            }
        ]
    }
]

CC: @Jaycee_Lewis - I see a lot of users in the community suffering from the same issue. Maybe you can suggest them with using this.

[SBasile]

I would really like to know when HubSpot intends to fix this. The v1 batch interface only reples with a 202 and provides no token or route which you can use in order to track the request's completion. That makes it difficult to get the ids of newly created contacts. The v3 upsert route will create the contact but will only add the email address and ignores all other contact properties passed with the POST request. It does reply with the ids of the newly created contact records. So you then have to use that information and do a separate batch update to get the remaining information into the record.

[CSewell1 · Accepted solution]

@Jaycee_Lewis

Since email was not working as a unique field, I explicitly made another unique field `emailCopy` and then tried hitting the endpoint using that field, but still got the following error message.

Request:
curl --request POST \
--url https://api.hubapi.com/crm/v3/objects/contacts/batch/update \
--header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'content-type: application/json' \
--data '{
"inputs": [
{
"idProperty": "emailCopy",
"id": "test@hello.com",
"properties": {
"role": "user"
}
}
]
}'

Response:

HTTP 400

"message": "Invalid property(ies) supplied as unique properties for upsert operation: [PropertyCoordinates{portalId=7192871, objectTypeId=ObjectTypeId{legacyObjectType=CONTACT}, propertyName=emailCopy}]"

I verified that `emailCopy` is a unique property.

Seems like this endpoint DOES NOT WORK with any unique fields except for `id`.

Also, the documentation on this page is incorrect. The request body (one on the right) is malformed JSON.

[RChen10]

Not sure it will help. How about adding `"idProperty": "email",` in request payload?

[CSewell1]

@Jaycee_Lewis Adding to this, it does NOT work with any unique properties.

Consider `emailCopy` as a unique property.

I tried following request:

curl --request POST \
  --url https://api.hubapi.com/crm/v3/objects/contacts/batch/update \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "inputs": [
    {
      "idProperty": "emailCopy",
      "id": "test@hello.com",
      "properties": {
        "role": "user"
      }
    }
  ]
}'

and got following response

HTTP 400

{
  "status": "error",
  "message": "Invalid property(ies) supplied as unique properties for upsert operation: [PropertyCoordinates{portalId=7192871, objectTypeId=ObjectTypeId{legacyObjectType=CONTACT}, propertyName=emailCopy}]",
  "correlationId": "<id>",
  "category": "VALIDATION_ERROR"
}

Also, the sample request body (the one on the right) in the documentation provided here is invalid. It has a malformed JSON structure:

[zach_threadint]

@RChen10 👋 Thanks for the idea, but unfortunately this does not work at the moment.

Example request

POST /crm/v3/objects/CONTACTS/batch/update

{
    "inputs": [
        {
            "id": "test@test.com",
            "idProperty": "email",
            "properties": {
                "firstname": "Example 1"
            }
        },
        {
            "id": "example@example.com",
            "idProperty": "email",
            "properties": {
                "firstname": "Example 2"
            }
        }
    ]
}

Example response (status code 400)

{
    "status": "error",
    "message": "Unable to perform update/upsert by non-unique 0-1 property email in portal ID 25377334",
    "correlationId": "6ab7356a-d80f-4284-bd48-54183fc235d0",
    "category": "VALIDATION_ERROR"
}

[Jaycee_Lewis]

Hey, @DSmith95 and @zach_threadint 👋 I submitted this to the dev doc team with an increased urgency. I'll post here as soon as I get a working example or get it confirmed that this specific endpoint won't work using email as a unique property. 

[Jaycee_Lewis]

Hey y'all. I have an update — this is confirmed not possible. 

I worked with the docs team to get the documentation updated. Next, I need to track down the team that owns the endpoints tab examples and get that updated. But we have our long-awaited confirmation. I know this is not the answer we were hoping for, and I am grateful that the documentation won't send anyone else on a wild goose chase using a method that isn't possible.

Thank you for your patience.

Best,

Jaycee

[zach_threadint]

Thanks for the update @Jaycee_Lewis 🙂

[zach_threadint]

Hi @DSmith95 👋

I've been able to replicate the issue you've described.

While it does say within the relevant API documentation, that "You can update contacts individually or in batches. For existing contacts, email and record ID are both unique values, so you can use id or email to update contacts via API", it doesn't actually supply an example of how this can be achieved on the Batch Update Contacts operation. I know it's possible to achieve on the Update Contact (single) operation, but, unfortunately, it looks like it's not possible on the Batch Update Contacts operation.

You may have to first use the CRM Search API to find the relevant internal HubSpot Contact IDs before batch updating the Contacts.

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

[Jaycee_Lewis]

Hey, @DSmith95 thanks for flagging this. And thanks to @zach_threadint for reproducing the issue. I'm going to make an example of my own, and I'll see if I can get us a definite answer or a documentation update, if needed. 

Talk soon! — Jaycee