Some endpoints (i.e. Get a specific workflow) don’t explicitly specify what data get returned. An example of returned data is given, but the data returned in the example and the data returned when I make an actual request don’t quite match up. I’d like to know exactly what JSON fields will be returned, as is listed for the Calendar API endpoints. Is this information out there somewhere?
Typically the API documentation includes an example URL at the very bottom of the article. You can hit the endpoint to see the full response.
In the case of the Calendar API there are no example endpoints, but there is a list of the fields returned in a response.
How is the response you are getting different from the example? Can you please post the response?
The data returned from https://api.hubapi.com/automation/v3/workflows/10900?hapikey=demo&stats=true&errors=true doesn’t return a “goalListIds” field, but that field is shown in the example response. There may be other mismatches as well, but that’s the one that stood out to me.
As an aside, the Calendar API does include example endpoints, they’re included above the example response.
Some of the endpoints will only include parameters in the response if they are not null.
I added a goal criteria to the workflow and it now displays the corresponding goal list Id. It looks like the
goalListIds param is in the example to show that it might be included in the response.
If an example URL sometimes omits parameters in the response if they are null, and sometimes example responses aren’t included in the docs, is there any way to be assured that I’ve accounted for all possible return parameters when it comes to an endpoint that doesn’t include an example response?
In most cases unlisted params will be custom properties that are returnedfrom the Contacts API, but any system params that may or may not be included in all responses should be listed in the examples.
I’m going to flag this as a Docs suggestion, but if you find any params that should be included in the Docs and are not please submit feedback on the page so we can get them updated. We’re constantly updating our APIs, so this is an ongoing task.
Thanks for the response. I’d say around 1/4 of the API docs don’t include example return data – I’m not sure if this is because those example don’t have any ambiguity in terms of what is returned or because the docs are still being developed. I’ll start making more use of the feedback button when I see something like that. Overall though I would say that the number one difficulty I’m having with the APIs so far is not knowing exactly what will be returned. It makes it hard to design a parser.
Aside from not knowing exactly what parameters are returned, a lot of the arrays and JSON objects are empty in the provided examples. Not knowing what they contain contributes to the parsing difficulty too.
Thanks for responding to my questions so quickly!