APIs & Integrations

mwelch
Exmiembro de HubSpot
Exmiembro de HubSpot

CRM API v3 Developer Preview is Now Available

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.

31 Respuestas 31
mchanner
Participante

CRM API v3 Developer Preview is Now Available

Love the new API, how much longer till Engagements get added?

0 Me gusta
Voyager2
Miembro

CRM API v3 Developer Preview is Now Available

Is there a way to get deleted deals with the new API? It looks like it is not possible for the current version, one can only get deals with isDeleted: false

0 Me gusta
Seth_Israel
Colaborador

CRM API v3 Developer Preview is Now Available

We were told this upgrade would help our customer association in Chat:

https://community.hubspot.com/t5/APIs-Integrations/How-to-identify-a-contact-in-the-chat/td-p/228672

Although since we don't use the API and instead use Segment to connect HubSpot, would we even see these upgrades on our end?

It looks like the last Segment HubSpot API upgrade was 16 months ago?
https://github.com/segmentio/analytics.js-integrations/tree/master/integrations/hubspot

0 Me gusta
fndicu
Equipo de producto de HubSpot
Equipo de producto de HubSpot

CRM API v3 Developer Preview is Now Available

Hi Seth, 

 

Thanks for reaching out. When this functionality is in stable General Release (approx. end of q1) it will be ready for use in production environments. I recommend providing feedback to segment's development team. 

0 Me gusta
allantl
Miembro

CRM API v3 Developer Preview is Now Available

Very excited with the v3 API. The API seems more standardized.

I tried the Batch create contacts API /crm/v3/objects/contacts/batch/create.
I found a bug on the implementation.

Creating a contact with an email that already exists always returns an "id": "0". The same thing happens with single creation. If I remember correctly, it will throw an error "Email already exists" with v1?

Also, would it be possible to increate the Batch operation limits? 10 seems too little. What about increasing it to something like 25 or 50?

Another question that I have. According to the docs, this is a possible response.

{
  "results": [
    {
      "createdAt": "2019-10-30T03:30:17.883Z",
      "archived": false,
      "id": "512"
    }
  ],
  "status": "PENDING",
  "requestedAt": "2020-02-17T05:11:56.589Z",
  "startedAt": "2020-02-17T05:11:56.589Z",
  "completedAt": "2020-02-17T05:11:56.589Z"
}

How do we poll the status to check that it is COMPLETED? Do we need to rely on the webhook to get events (This would be so troublesome....)?

0 Me gusta
fndicu
Equipo de producto de HubSpot
Equipo de producto de HubSpot

CRM API v3 Developer Preview is Now Available

0 Me gusta
allantl
Miembro

CRM API v3 Developer Preview is Now Available

Hi fndicu,

Thanks for the response. I have another question for the batch creation API  /crm/v3/objects/contacts/batch/create

 

Based on the response json from the documentation, this means that some result can return an error? Or do you fail the whole batch if there's a validation error like the previous batch api in v1?

If some request can fail, how do I know which one of my request payload results in an error. Since there's no way for me to cross check in the `errors` object below. As a comparison, from Salesforce API .
What about returning the response based on the request payload order. Then, the success/error reason should be inside each object.

{
  "results": [
    {
      "createdAt": "2019-10-30T03:30:17.883Z",
      "archived": false,
      "id": "512",
      "properties": {
        "property_number": "17",
        "property_dropdown": "choice_b",
        "property_radio": "option_1",
        "property_string": "value",
        "property_multiple_checkboxes": "chocolate;strawberry",
        "property_checkbox": "false",
        "property_date": "1572480000000"
      },
      "updatedAt": "2019-12-07T16:50:06.678Z"
    }
  ],
  "numErrors": 0,
  "errors": [
    {
      "message": "Invalid input (details will vary based on the error)",
      "correlationId": "aeb5f871-7f07-4993-9211-075dc63e7cbf",
      "category": "VALIDATION_ERROR",
      "links": {
        "knowledge-base": "https://www.hubspot.com/products/service/knowledge-base"
      }
    }
  ],
  "status": "PENDING",
  "requestedAt": "2020-03-04T05:04:22.596Z",
  "startedAt": "2020-03-04T05:04:22.596Z",
  "completedAt": "2020-03-04T05:04:22.596Z"
}

 

 

0 Me gusta
fndicu
Equipo de producto de HubSpot
Equipo de producto de HubSpot

CRM API v3 Developer Preview is Now Available

That is correct. The entire batch should run and we return an error for each of the specific objects that failed. 

0 Me gusta
riwern
Participante

CRM API v3 Developer Preview is Now Available

Under the search endpoint there are some listed limitations. Are they planned limitations or just current limitations while the v3 API is under development ("unfinished")?

 

Archived CRM objects won’t appear in any search results.

 

In particular, I'm looking for a way to view contacts deleted ("archived=true") without pulling all contacts.

 

Secondary question: Will restore contacts be exposed within the API?

0 Me gusta
fndicu
Equipo de producto de HubSpot
Equipo de producto de HubSpot

CRM API v3 Developer Preview is Now Available

Thanks for reaching out!
 
1) You can get a list of all archived contacts with GET /crm/v3/objects/contacts?archived=true, but archived contacts won’t appear as results when POST /crm/v3/objects/contacts/search is invoked.
 
 So you can list archived (deleted) contacts, but you can’t search for them (among other things, like update).
 
 
2) Yes, we plan to add this functionality as an update in the future!
0 Me gusta
Ferseb
Miembro

CRM API v3 Developer Preview is Now Available

Hi people,

 

I am new to the Hubspot API and I'm currently having a look at the V3 endpoints using the (rather good) Ruby gem. I can't seem to find anything related to the subscription of users to emails just like there was in v1 : https://api.hubapi.com/email/public/v1/subscriptions/MY_EMAIL?hapikey=KEY

 

Is it implemented yet?

 

Thanks for your help

0 Me gusta
fndicu
Equipo de producto de HubSpot
Equipo de producto de HubSpot

CRM API v3 Developer Preview is Now Available

Hi Ferb, 

 

Glad to hear you are enjoying the experience so far! At this time we don't have that functionality implemented yet. Can you provide some more detail on your use case? Feel free to DM the details. 

0 Me gusta
rossfairbairn
Participante

CRM API v3 Developer Preview is Now Available

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.

0 Me gusta
fndicu
Equipo de producto de HubSpot
Equipo de producto de HubSpot

CRM API v3 Developer Preview is Now Available

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!

 

0 Me gusta
lukemelia
Participante

CRM API v3 Developer Preview is Now Available

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?

 

0 Me gusta
fndicu
Equipo de producto de HubSpot
Equipo de producto de HubSpot

CRM API v3 Developer Preview is Now Available

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. 

0 Me gusta
nadendav
Miembro

CRM API v3 Developer Preview is Now Available

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.

0 Me gusta
nadendav
Miembro

CRM API v3 Developer Preview is Now Available

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 

0 Me gusta
fndicu
Equipo de producto de HubSpot
Equipo de producto de HubSpot

CRM API v3 Developer Preview is Now Available

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. 

0 Me gusta
nadendav
Miembro

CRM API v3 Developer Preview is Now Available

Awesome! Can't wait...

0 Me gusta