CRM API v3 Developer Preview is Now Available

Develop, Build & Integrate APIs & Integrations
1

HubSpot API consistency and completeness has been a major point in feedback from our developer community for some time now. You spoke, and we listened! We are excited to announce the launch of a refreshed CRM API and documentation, available today in developer preview.

The CRM API v3 is the first milestone in a larger concerted effort to level up HubSpot’s APIs. These new APIs are more consistent than the current generation and are on their way to becoming more complete.
CRM Search, Imports, Owners, Pipelines, Properties, Associations, Objects (contacts, companies, deals, etc.)

Here’s what’s new:

Search, Filter and Sort:
This brand-new endpoint allows developers to filter, sort, and search across all CRM objects (contacts, companies, deals, etc). These new capabilities will allow for more effective data retrieval across the CRM.

You might use this API for:

  • Getting a list of contacts for a specific account
  • Retrieving a list of all open deals
  • Searching for contacts by custom properties

CRM Imports Endpoint:
This brand-new endpoint allows developers to import CSV files for creating or updating objects in their HubSpot accounts. These objects include contacts, companies, deals, tickets, products, and notes. The Imports API allows your integration to use the same powerful features that are supported by the in app import tools in HubSpot.

The Imports API allows you to:

  • Import files directly
  • Retrieve information on any past imports
  • Cancel any incomplete imports

Learn once, apply everywhere:
All CRM objects now have more in common. Defining properties, associating objects to one another, assigning ownership and defining pipelines (where applicable) are all the same regardless of the objects you’re working with.

  • CRM Object Properties
  • CRM Associations
  • CRM Owners
  • CRM Pipelines

What this means for developers:

  • Start testing out these endpoints. Developer preview is the perfect time to let us know what you think. We’ll be collecting and iterating quickly on your feedback, which could mean breaking changes. It’s not recommended to use these endpoints in a production environment yet, but we’ll let you know when they’re ready.
  • Continue to use the existing stable CRM API, which will remain available for production use as we build out our platform with improved consistency and capability.

FAQ

CRM Search:

  • Search functionality is limited to one request per second
  • “engagements”, including “tasks”, “calls”, “emails”, and “notes” aren’t supported in Search

Coming Soon

  • We are missing the Engagements and Contact Lists endpoints - use the existing ones for now.
  • Secondary Identifiers - we’ll be adding this shortly—hang tight.

Please provide your feedback about these new APIs in this thread.

2

I just wanted to say I’m very very very happy with this new API, it simply solved half our ELT problems, thanks so much

3

Does “Filter, sort, and search” work with custom properties on Companies?

Under Use Cases it specifies “Searching for contacts by custom properties” so I would assume this also means it would work for Companies but want to confirm.

thank you

4

Hi @JGSurge thanks for the feedback. The “filter, sort, and search” functionality works for custom properties on all CRM objects (Contacts, Companies, Deals, Tickets, Line Items, and Quotes.)

We have updated the documentation to read more clearly!

5

How long do these updates usually stay in Developer Preview? This update could solve most of our problems with syncing CRM data.

6

Thanks for reaching out! We are aiming for an early q2 release date for these APIs pending the feedback we receive during the public beta period. We will make an announcement on the HubSpot developer changelog once the CRM v3 APIs are in stable release!

7

Hi,

I know that this is still a beta version, but I just wanted to know if there will be a possibility to get historical values for each property, similar to the “propertiesWithHistory” parameter of the current API?

8

Hi Bernado, thank you for the feedback. Support for this feature is on our road map. I will follow-up in this thread once it has been implemented!

9

I’m testing the search API and it appears that the EQ operator is case-sensitive such that values with capitalization are never matched.
If there’s a Company with name “Company Name”, the following search works:

{
 "propertyName": "name",
 "operator": "CONTAINS_TOKEN",
 "value": "Company Name"
}

But this search does not:

{
 "propertyName": "name",
 "operator": "EQ",
 "value": "Company Name"
}

It looks like it’s doing column = lower(input) instead of lower(column) = lower(input).

10

Hi @erikm I’ve been able to record to same behavior and shared your feedback with the team. I’ll post a response in this thread once the issue has been resolved. Thank you for reaching out!

11

Can we use these APIs in production?

Are any major changes are anticipated from these endpoints?

12

Hi @SoumS these APIs are in developer preview (otherwise referred to as public beta). All portals are ungated for the functionality. That being said, Items with a “preview” tag should be considered a non-stable release that will be subject to bugs and breaking changes while under development. Please take this into account as you build against a release.

13

Thank you, Thank you, Thank you for the v3 Contacts API. I had been banging my head against a wall trying to get my iPAAS solution to generate the v1 JSON mesasge body with no luck. It looks like I got the v3 to work yesterday! More testing today…

I am also interested in the new v3 Imports Endpoint but soi far I haven’t been able to put 2 and 2 together. I think I’ve studied the content at the links provided already and I can’t find a specification for the importRequest and files parameters. The link at “See this page for more on the required format.” for the importRequest does not go anywhere, it simply returns the same page. Thanks

14

We are glad to hear you are enjoying the new API!

Thank you for the feedback on Imports. We are currently working on a fix that will provide the sample import post body in-line with the overview documentation.

15

Awesome! Can’t wait…

16

The v3 Contacts Batch Endpoint does not appear to be performing an Upsert as I believe is described for the v1. I understand this to be related to de-duping based on existence of an E-mail address.

17

In trying out the v3 contact search API, I am able to match a user by “email”, but not by “id”. e.g.

curl https://api.hubapi.com/crm/v3/objects/contacts/search\?hapikey\=APIKEY \
 --request POST \
 --header "Content-Type: application/json" \
 --data '{
 "filterGroups":[
 {
 "filters": [
 {
 "propertyName": "email",
 "operator": "EQ",
 "value": "luke@lukemelia.com"
 }
 ]
 }
 ],
 "properties": ["email", "firstname", "id"]
 }'
{
 "total": 1,
 "results": [
 {
 "id": "790301",
 "properties": {
 "email": "luke@lukemelia.com",
 "firstname": "Luke",
 "id": "d15231c3-7580-43c5-9ee7-5a7dc7a37707"
 },
 "createdAt": "2019-02-13T18:28:48.982Z",
 "updatedAt": "2020-02-14T01:03:19.448Z",
 "archived": false
 }
 ]
}

curl https://api.hubapi.com/crm/v3/objects/contacts/search\?hapikey\=APIKEY \--request POST \--header "Content-Type: application/json" \--data '{"filterGroups":[{"filters": [{"propertyName": "id","operator": "EQ","value": "d15231c3-7580-43c5-9ee7-5a7dc7a37707"}]}],"properties": ["email", "firstname", "id"]}'{"status": "error","message": "There was a problem with the request.","correlationId": "7533e820-6dbe-43a0-8155-d03c9783c05b","requestId": "2f034108-5bba-4c7e-851f-ebb8f4f4cb25"}

Is this a bug or am I missing something?

18

Hi Luke, I’ll shoot you a dm to dig in a little further. The only strange thing I notice here is that it seems like we have two properties with the name “id” and two different formats.

19

Hi, firstly I just wanted to saying I’m generally loving the new API - thanks!

Something that is a bit of an issue, and please correct me if I’m wrong here but it doesn’t seem possible to return associations when filtering tickets.

My user case: I need a list of tickets created in the last 7 days and for each ticket I need to know the company it’s associated with.

Previously I had these two problems:

  1. I had to get every ticket ever from the API and then filter down in my own script
  2. I then had to get all the company → ticket associations

This meant a lot of requests!

It seems you’ve solved both of these problems separately but not together. I can now return associations with tickets when getting all tickets but I can’t return associations when using the new filter/search functionality.

20

That is fantastic to hear! At this time that is correct, we can’t return an object’s associations in the same call. That being said, you can use the batch associations endpoint to return associations for a list of objects.

I have passed along your feedback and will get it on the team’s radar.

Thanks!