API documentation


You authenticate to the API by providing your Connector ID and Secret in the request. You can find it in any connector settings pane.

Additionally you can authenticate “As a User” by passing a JWT token in Hull-Access-Token - This is the way you can submit Events and Attributes on a given user.

  • When you authenticate as a user from the Client-side within Hull.js, the library passes this JWT token in every call. You have limited access to the API, and can only perform tracking calls, traits, and access your own profile.
  • When you authenticate as an admin (with a Connector ID & Secret) Server-side, you have full access to the API

Authenticated requests

curl -X DELETE http://ORGANIZATION_NAMESPACE.hullapp.io/api/v1/:id \
     -H "Hull-App-Id: CONNECTOR_ID" \
     -H "Hull-Access-Token: JWT_OR_CONNECTOR_SECRET" \

From a server, set up Hull-App-Id and Hull-Access-Token HTTP headers to provide the Connector Id and Access Token.

The Hull-Access-Token is either the Connector Secret you can find in your Connector’s Settings, or a User-scoped token generated by the library.

The Hull JS Node library handles all of this for you.

curl -X DELETE http://ORGANIZATION_NAMESPACE.hullapp.io/api/v1/:id?app_id=CONNECTOR_ID&access_token=JWT_OR_CONNECTOR_SECRET

You can also send your App ID and the Access Token as parameters, although we discourage it.

Beware to never expose your CONNECTOR_SECRET on the client side, only use these authenticated methods from your own server !

Making requests on behalf of a user

curl -X PUT http://NAMESPACE.hullapp.io/api/v1/:id/traits \
     -H "Hull-App-Id: CONNECTOR_ID" \
     -H "Hull-Access-Token: JWT_OR_CONNECTOR_SECRET" \
     -H "Hull-User-Id: USER_ID"

When you do server-to-server calls, you will frequently want to perform calls as one of the end-users. To do that, provide the user id in the Hull-User-Id header.

The easiest way to do this from the server-side is to use our Hull Node library