Query Hubspot with GraphQL

Here's how to query Hubspot with GraphQL.

What is GraphQL

GraphQL is a query language for fetching and writing data. For web applications, there's usually a single endpoint available over HTTP where available data can be queried. As a query language, it has a syntax kind of like json, showing just the keys but not the values. It is nice to use when you want to go to a single endpoint for all your data. And to pull back just those fields that are required for your custom query (ie, as opposed to REST, where you request the whole resource whether you need it all or not).

What is GraphiQL

GraphiQL is a web GUI that allows you to see what resources are available in a GraphQL schema. You can easily discover and use these fields when crafting your query. Then you can execute and test your query against the live endpoint.

What is Hubspot

Hubspot is a Customer Relationship Management tool, or CRM. It's the kid brother of Salesforce. It has an extensive HTTP API. You can usually fetch and write what you need to. It has this Associations API to make jumps between related resources. Often this leads to n + 1 HTTP requests. It was nice to discover that all this is queryable in Hubspot via GraphQL.

Hubspot GraphQL Endpoint

The main endpoint for the CRM API in GraphQL is available at:

https://api.hubspot.com/collector/graphql

This might feel like a silly thing to document. But the official GraphQL documentation at the moment is very sparse, and even basic facts like this can be hard to find.

Hubspot GraphiQL Endpoint

The main endpoint for the GraphiQL GUI interface is

https://app.hubspot.com/graphiql/:myPortalId

To find your portal id, follow these instructions.

Authorize Your API Token

All requests to Hubspot APIs require an private app token. GraphiQL endpoints are no different in this regard. Additionally, however, you'll need to add an authorization scope to your token, allowing it to make GraphiQL requests.

For help adding a scope, follow this doc.

Example Query with fetch

There are so many libraries and strategies built up around using GraphQL. But let's keep it simple, shall we? Let's use the fetch API.

Let's say that we're fetching a deal. We can do so like this:

async function fetchDeal(dealId) {
  const result = await fetchGraphql(`
query aDeal {
  CRM {
    deal(uniqueIdentifier: "id", uniqueIdentifierValue: "${dealId}") {
      hs_object_id
    }
  }
}`)
  return result
}

async function fetchGraphql(
  query,
  apiToken = process.env.HUBSPOT_PRIVATE_APP_TOKEN
) {
  const res = await fetch("https://api.hubspot.com/collector/graphql", {
    method: "post",
    headers: {
      Accept: "application/json",
      "Content-Type": "application/json",
      Authorization: `Bearer ${apiToken}`,
    },
    body: JSON.stringify({
      query,
    }),
  });
  const json = await res.json();
  if (!res.ok) {
    console.error("Failed graphql request", res.status, res.json);
  }
  return { ok: res.ok, json: json.data };
}

We're not returning anything interesting for deal fields. We're not making association jumps. But all the code pieces for making a GraphQL request are there. Now jump into GraphiQL, and build out a useful query for yourself.