APIs & Integrations


Searching deals (PHP)

I'm trying to do a simple search of deals: find all deals with a dealstage of closed won. This is proving surprisingly difficult.


The documentation is not very helpful - the UI forces you to see everything through a very small portion of the window, and it keeps losing its scroll position and jumping to irrelevant positions. While various properties are present, there is no explanation what each field does. The default values for most of them is "string", which appears to break some things, and it's unclear why it's needed at all.


Searching has led me to posts like this one: https://community.hubspot.com/t5/APIs-Integrations/Deals-API-Search-deal-using-property/m-p/385225


Unfortunately following that example doesn't find anything (well, it shows a result count with no content). It does however reveal that the examples are incorrect – it shows that the value searched on is the "query" property, not the "value" property inside the filter as it describes; changing the query property changes the result count, but changing the filter value does not. Suggesting limit = 0 seems unlikely to be helpful, and I have no idea what sorts and properties are meant to contain.


I can't try searches on the page because it says my key is invalid, though the same key works for me locally.


I found the docs on deals from the user side: https://knowledge.hubspot.com/crm-deals/hubspots-default-deal-properties but that does not show what the properties are called in the API, or what values they might contain. There doesn't seem to be a consistent policy on naming so it's hard to guess – some fields are all lower case like "dealstage", others use underscores like "hubspot_owner_id", others use mixed case, like "createdAt" (though that one varies).


I want to search on deal stage. I see that these are customisable, but I've not found where in the API I should get all possible values to validate against.


Are there other docs that I've missed?

4 Replies 4

Searching deals (PHP)

Thanks for the pointer. Unfortunately the example code provided in the docs fails with a cryptic message. The code:

$client = Factory::createWithAccessToken(config('hubspot.api_key'));
try {
  $apiResponse = $client
} catch (ApiException $e) {
  echo "Exception when calling pipelines_api->get_all: ", $e->getMessage();

The error:

HubSpot\Client\Crm\Pipelines\ApiException with message '[400] Client error: `GET https://api.hubapi.com/crm/v3/pipelines/objectType` resulted in a `400 Bad Request` response:
{"status":"error","message":"Unable to infer object type from: objectType","correlationId":"036421fe-b201-4aa6-b35b-f56d (truncated...)

I don't know why this would fail, or what this error means.

Community Manager
Community Manager

Searching deals (PHP)

Hey, @MarcusBB 👋 A great place to get stared is the Pipelines API. It allows you to get the labels and values for stages of a specific pipeline.  You can include the internal values for pipeline and stage in your search query — Search API.


Have fun building! — Jaycee


Jaycee Lewis

Developer Community Manager

Community | HubSpot

Member | Diamond Partner
Member | Diamond Partner

Searching deals (PHP)

Hey @MarcusBB


Hey check this PHP curl code pasted below for searching deals, you can modify the body section according to your properties in the hubspot CRM:




$curl = curl_init();


curl_setopt_array($curl, array(

  CURLOPT_URL => 'https://api.hubapi.com/crm/v3/objects/deals/search?hapikey=your-hubspot-key',










                "propertyName": "hs_object_id",

                "operator": "EQ",






    'Content-Type: application/json'




$response = curl_exec($curl);



echo $response;

Hope this helps!

If we were able to answer your query, kindly help the community by marking it as a solution.

Thanks and Regards.


Searching deals (PHP)

Unfortunately this doesn't help either. I'm trying to use Hubspot's own client classes, not raw curl, and the docs give no indication at all of what any of the parameters do, or make any attempt to explain the structure of these queries. I've not found any docs on what the values you've used in the POST body can be, and in your example you're using some cryptic number instead of something meaningful.


I am massively unimpressed with the HubSpot API. It's an inconsistent, incoherent mess with terrible docs and no meaningful feedback. How is anyone supposed to do anything productive with it when even the most rudimentary requests simply fail with cryptic, meaningless, unexplained errors? I was expecting this to take no more than a few minutes to get working, like many other APIs I work with, but it's just catastrophically unusable, wasting weeks of effort.