Rest API Reference

Introduction

Even if the API is fully supported, there’s more to using Hull than this. We recommend you consume the API through a Hull client or Connector. Those are easy to build and they package the entire request/response flow for you, subscribe to realtime updates from the platform and more.

Read a the 5 minutes intro on connectors.

The Hull API is a Flat API. You access objects by their Object ID, like this:

GET /:id

The Hull API lets you retrieve, add, modify and remove application data. We use standard HTTP methods for each of those actions.

  • GET to retrieve,
  • POST to create,
  • PUT to modify
  • DELETE to remove.
Conventions
GET /api/v1/51122a9841a1bc52b4000006

Raw HTTP

Hull.api('/51122a9841a1bc52b4000006', function(response){
  console.log('response')
});

Javascript

  • EVERY CALL starts with /api/v1. You can omit this prefix when using the Hull SDKs. We’ll add it for you.
  • Every object in your organization has a unique id. You access it by requesting http://ORGANIZATION_NAME.hullapp.io/api/v1/ID where ORGANIZATION_NAME is the namespace of your organization (You can find it in your dashboard).

Authentication

You authenticate to the API by providing your Ship ID and Secret in the request. You can find it in your admin.

Additionnally 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 Ship ID & Secret) Server-side, in Ships, you have full access to the API

Authenticated requests

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

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

The Hull-Access-Token is either the App Secret you can find in your Ship’s Advanced 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=SHIP_ID&access_token=JWT_OR_SHIP_SECRET

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

Beware to never expose your SHIP_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: SHIP_ID" \
     -H "Hull-Access-Token: JWT_OR_SHIP_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


Status Codes

Hull conform to standards regarding HTTP status codes to indicate success or failure of a request:

  • 200: OK, The requested object exist.
  • 201: Created, the object has been created.
  • 400: Bad Request, required parameters are missing.
  • 401: Unauthorized, Your App ID, Access Token and/or User ID are missing or invalid.
  • 404: Not Found, the requested object doesn’t exist.
  • 405: Method Not Allowed, the called method doesn’t exist.
  • 500, 503: Server Errors, something went wrong on our side.

Pagination

GET /api/v1/51122a9841a1bc52b4000006/comments?per_page=10&page=2

curl

Hull.api('/api/v1/51122a9841a1bc52b4000006/comments', {
  "per_page":10,
  "page":2
},function(response){
  console.log('response')
});

Javascript

Any request that returns a collection has a page based pagination.

To navigate through the pages, add a per_page and a page parameter to your request.

  • per_page, number of item to display per page. 30 by default.
  • page, the page to retrieve. 1 by default.

Users

Each of your Users is defined by this object. This is a central part of the API, since most calls expect a User to be logged in to associate the action.

Get Current User

ACCESS: User
GET /api/v1/me
EXAMPLE REQUEST
Hull.api('/me', 'get').then(function(response) {
 console.log(response);
});
    curl -X GET 'https://hull-demos.hullapp.io/api/v1/me'
         -H 'Hull-App-Id: 5113eca4fc62d87574000096'
         \
     -H 'Hull-User-Id: USER_ID' 
         
EXAMPLE RESPONSE
{
  "id": "5147729a255226c974000019",
  "updated_at": "2015-09-02T16:26:09Z",
  "created_at": "2013-03-18T20:01:30Z",
  "name": "hull",
  "description": null,
  "extra": "{ Extra Hash }",
  "stats": "{ Stats Hash }",
  "tags": "[ Tags Array ]",
  "picture": "http://a0.twimg.com/profile_images/2640633138/7d994113743b9ad76982f6dbcaaf5e1e_normal.jpeg",
  "type": "user",
  "first_name": "hull",
  "last_name": null,
  "approved": true,
  "username": null,
  "profile": {
  },
  "email": null,
  "contact_email": null,
  "phone": null,
  "address": {
  },
  "confirmed": false,
  "accepts_marketing": false,
  "domain": null,
  "is_admin": true,
  "main_identity": "twitter",
  "access_token": "xxxxxxxxxxxxxxxxxxxxxx",
  "settings": {
    "notifications": {
    }
  },
  "identities": "[ Social Network Identities Array ]",
  "last_seen_at": "2015-09-02T16:26:39Z",
  "sign_in": null,
  "traits": {
  }
}

Returns data for the currently logged in User - This format will be different from the one returned by the Connectors notifications

Search Users

ACCESS: Admin
POST /api/v1/search/user_report
EXAMPLE REQUEST
Hull.api('/search/user_report', 'post',{
  "query": {
    "multi_match": {
      "type": "phrase_prefix",
      "query": "user@host.com",
      "operator": "and",
      "fields": [
        "email.exact^2"
      ]
    }
  },
  "sorting": {
    "created_at": "asc"
  },
  "raw": true,
  "page": 1,
  "per_page": 2
}).then(function(response) {
 console.log(response);
});
    curl -X POST 'https://hull-demos.hullapp.io/api/v1/search/user_report'
         -H 'Hull-App-Id: 5113eca4fc62d87574000096'
         
          \
     -d '{
           "query": {
             "multi_match": {
               "type": "phrase_prefix",
               "query": "user@host.com",
               "operator": "and",
               "fields": [
                 "email.exact^2"
               ]
             }
           }
         }' \
     -d '{
           "sorting": {
             "created_at": "asc"
           }
         }' \
     -d raw='true' \
     -d page='1' \
     -d per_page='2'

Performs an Elasticsearch Query on the User DB. You can filter based on Events with the with_child predicate. The Dashboard will let you explore queries. You can see them with the Chrome Console

QUERY PARAMETERS
  • queryHashoptional

    Elasticsearch Query

  • sortingHashoptional

    Sort direction

  • rawBooleanoptional

    Raw format (only this is supported today)

  • pagenumberoptional

    Page number

  • per_pageStringoptional

    Items per page

Search Events

ACCESS: Admin
POST /api/v1/search/event
EXAMPLE REQUEST
Hull.api('/search/event', 'post',{
  "query": {
    "multi_match": {
      "type": "event",
      "query": "Email Open",
      "operator": "and",
      "fields": [
        "event"
      ]
    }
  },
  "sorting": {
    "created_at": "asc"
  },
  "raw": true,
  "page": 1,
  "per_page": 2
}).then(function(response) {
 console.log(response);
});
    curl -X POST 'https://hull-demos.hullapp.io/api/v1/search/event'
         -H 'Hull-App-Id: 5113eca4fc62d87574000096'
         
          \
     -d '{
           "query": {
             "multi_match": {
               "type": "event",
               "query": "Email Open",
               "operator": "and",
               "fields": [
                 "event"
               ]
             }
           }
         }' \
     -d '{
           "sorting": {
             "created_at": "asc"
           }
         }' \
     -d raw='true' \
     -d page='1' \
     -d per_page='2'

Performs an Elasticsearch Query on the Event DB. You can filter based on User Attributes with the with_parent predicate. The Dashboard will let you explore queries. You can see them with the Chrome Console

QUERY PARAMETERS
  • queryHashoptional

    Elasticsearch Query

  • sortingHashoptional

    Sort direction

  • rawBooleanoptional

    Raw format (only this is supported today)

  • pagenumberoptional

    Page number

  • per_pageStringoptional

    Items per page

User Attributes

ACCESS: User
PUT /api/v1/me/traits
EXAMPLE REQUEST
Hull.api('/me/traits', 'put',{
  "name": "number_of_coconuts",
  "operation": "inc",
  "value": "2"
}).then(function(response) {
 console.log(response);
});
    curl -X PUT 'https://hull-demos.hullapp.io/api/v1/me/traits'
         -H 'Hull-App-Id: 5113eca4fc62d87574000096'
         \
     -H 'Hull-User-Id: USER_ID' 
          \
     -d name='number_of_coconuts' \
     -d operation='inc' \
     -d value='2'

Stores an attribute for User, like their Name (See Traits)

QUERY PARAMETERS
  • nameStringrequired

    The attribute name. When a name is used for the first time, It's value defines it's Type. To store Dates, end the trait name with _at, as in created_at or _date.

    When calling this API server-side with admin rights, If the name contains a / it will appear grouped in the UI, and in hull-node.

    I.E.: { 'zendesk/open_tickets': 2 }
    will appear in Hull-node as: { zendesk: { open_tickets: 2 } }

  • operationStringrequired

    The operation to perform. can be set | setIfNull | inc | dec. If inc or dec, counter will be changed of value units

  • valueString/Number/Daterequired

    The trait's value. When a trait already exists, the value HAS TO be of the same type otherwise item will be dropped

User Events

ACCESS: User
POST /api/v1/t

Record an event asociated with the current authenticated user.

QUERY PARAMETERS
  • eventString

    Event name

  • event_idString

    (Optional) Unique identifier for an event. Allows idempotent tracking calls.

  • propertiesHash

    Event properties

  • sourceString

    Event source (defaults to 'track')

  • ipString

    IP Address to record with this event. Defaults to the request's IP

  • useragentString

    User Agent to record with this event. Defaults to the request's Agent

  • latitudeNumber

    (Optional) User geo position - latitude

  • longitudeNumber

    (Optional) User geo position - longitude

  • urlString

    URL to record with this event.

  • refererString

    Referer to record with this event. Defaults to the request's Referer.

  • activeBoolean

    (Optional) flag to mark the current user as active.

  • _sidString

    (Optional) sessionId associated with the event.

  • _bidString

    (Optional) anonymous / device identifier associated with the event.


Bulk

Attribute & Event Firehose

ACCESS: User
POST /api/v1/firehose
EXAMPLE REQUEST
Hull.api('/firehose', 'post',{
  "timestamp": "2017-03-24T11:06:40.150Z",
  "sentAt": "2017-03-24T11:06:40.150Z",
  "batch": [
    {
      "type": "track",
      "timestamp": "2017-03-24T11:06:40.150Z",
      "headers": {
        "Hull-Access-Token": "JWT_TOKEN"
      },
      "body": {
        "ip": null,
        "url": null,
        "referer": null,
        "event": "hello",
        "properties": {
          "who": "world"
        }
      }
    },
    {
      "type": "traits",
      "timestamp": "2017-03-24T11:06:40.150Z",
      "headers": {
        "Hull-Access-Token": "JWT_TOKEN"
      },
      "body": {
        "first_name": "Boby",
        "last_name": "Lapointe"
      }
    }
  ]
}).then(function(response) {
 console.log(response);
});
    curl -X POST 'https://hull-demos.hullapp.io/api/v1/firehose'
         -H 'Hull-App-Id: 5113eca4fc62d87574000096'
         \
     -H 'Hull-User-Id: USER_ID' 
          \
     -d timestamp='2017-03-24T11:06:40.150Z' \
     -d sentAt='2017-03-24T11:06:40.150Z' \
     -d batch='[#<Middleman::Util::EnhancedHash body=#<Middleman::Util::EnhancedHash event="hello" ip=nil properties=#<Middleman::Util::EnhancedHash who="world"> referer=nil url=nil> headers=#<Middleman::Util::EnhancedHash Hull-Access-Token="JWT_TOKEN"> timestamp="2017-03-24T11:06:40.150Z" type="track">, #<Middleman::Util::EnhancedHash body=#<Middleman::Util::EnhancedHash first_name="Boby" last_name="Lapointe"> headers=#<Middleman::Util::EnhancedHash Hull-Access-Token="JWT_TOKEN"> timestamp="2017-03-24T11:06:40.150Z" type="traits">]'

Ingests multple Events and Attributes for multiple users at once. Our Node libraries manage this automatically.

QUERY PARAMETERS
  • timestampDaterequired

    Timestamp

  • sentAtDaterequired

    Timestamp

  • batchStringrequired

    An Array of objects

Import Users

ACCESS: Admin
POST /api/v1/import/users
EXAMPLE REQUEST
Hull.api('/import/users', 'post',{
  "url": "https://example.to/import/file.json",
  "format": "json",
  "overwrite": false,
  "notify": false,
  "emit_event": false,
  "name": "csv_import.csv",
  "description": "First Import",
  "traits": "{ additional: true }"
}).then(function(response) {
 console.log(response);
});
    curl -X POST 'https://hull-demos.hullapp.io/api/v1/import/users'
         -H 'Hull-App-Id: 5113eca4fc62d87574000096'
         
          \
     -d url='https://example.to/import/file.json' \
     -d format='json' \
     -d overwrite='false' \
     -d notify='false' \
     -d emit_event='false' \
     -d name='csv_import.csv' \
     -d description='First Import' \
     -d traits='{ additional: true }'

Imports a JSON file of users, updating or creating them. Checkout implementation details and tutorial

QUERY PARAMETERS
  • urlrequired

    The URL of the file to import.

  • formatrequired

    File format, Only `json` is supported for now

  • overwriteoptional

    Will the import have precedence over existing data if a matching user is found. If False, data in Hull wins in case of a field conflict. Default: false

  • notifyoptional

    Notify connectors of each user that was imported, and trigger them accordingly. Default: false

  • emit_eventoptional

    If true, will we emit a Imported User event for each user in the list, with the following properties:

    - each property found in the traits parameter
    - job_id,
    - job_name, job_description : values of the name and description parameters
    - action: updated if the User was found and updated, new if he was created.

  • nameoptional

    Name to show in the emitted event. Default: filename from URL

  • descriptionoptional

    Optional Description. Default: ''

  • traitsoptional

    A hash of properties to apply to every user in this list - user data in list takes precedence. default: {}

  • schedule_atoptional

    Schedule the import to be run at a future date

Extract Users

ACCESS: Admin
POST /api/v1/extract/user_reports
EXAMPLE REQUEST
Hull.api('/extract/user_reports', 'post',{
  "url": "https://example.to/webhooks/callback",
  "format": null,
  "query": false
}).then(function(response) {
 console.log(response);
});
    curl -X POST 'https://hull-demos.hullapp.io/api/v1/extract/user_reports'
         -H 'Hull-App-Id: 5113eca4fc62d87574000096'
         
          \
     -d url='https://example.to/webhooks/callback' \
     -d format='' \
     -d query='false'

Starts a Bulk user extraction, generates a file and ping the URL of your chose with it's location. Checkout the Intercom Connector Extract method to see how we suggest to use this.

QUERY PARAMETERS
  • urlrequired

    The URL to call when extract is ready.

  • formatrequired

    File format, "csv" and "json" are supported

  • fieldsoptional

    If export is CSV, which attributes to include. in JSON exports, everything is included.

  • queryrequired

    An Elasticsearch query to define who to include in the export. Hint: Build your query in the Dashboard and copy it from the console to make it easier to build. In Notifications, segments also include a copy of the query that defines them (notification.segments[0].query- you can use it.


Identities

Hull can optionally handle Identity Management for you (Contact us for more details)

Create User

ACCESS: Public
POST /api/v1/users
EXAMPLE REQUEST
Hull.api('/users', 'post',{
  "email": "hello@acme.com",
  "password": "s3cr3t"
}).then(function(response) {
 console.log(response);
});
    curl -X POST 'https://hull-demos.hullapp.io/api/v1/users'
         -H 'Hull-App-Id: 5113eca4fc62d87574000096'
         
          \
     -d email='hello@acme.com' \
     -d password='s3cr3t'

Upsert User (Email + Password)

QUERY PARAMETERS
  • usernameoptional

    A username for the User

  • emailrequired

    An email address

  • passwordrequired

    A password

Upsert User (with tokens)

ACCESS: Public
POST /api/v1/users
EXAMPLE REQUEST
Hull.api('/users', 'post',{
  "facebook": {
    "access_token": "FACEBOOK_ACCESS_TOKEN"
  }
}).then(function(response) {
 console.log(response);
});
    curl -X POST 'https://hull-demos.hullapp.io/api/v1/users'
         -H 'Hull-App-Id: 5113eca4fc62d87574000096'
         
          \
     -d '{
           "facebook": {
             "access_token": "FACEBOOK_ACCESS_TOKEN"
           }
         }'

Creates or log a User in with third party tokens

QUERY PARAMETERS
  • facebookoptional

    A hash containing an access_token key

  • twitteroptional

    A hash containing access_token and access_token_secret keys

  • linkedinoptional

    A hash containing access_token and access_token_secret keys

  • instagramoptional

    A hash containing an access_token key

Login

ACCESS: Public
POST /api/v1/users/login
EXAMPLE REQUEST
Hull.api('/users/login', 'post',{
  "login": "hello@acme.com",
  "password": "s3cr3t"
}).then(function(response) {
 console.log(response);
});
    curl -X POST 'https://hull-demos.hullapp.io/api/v1/users/login'
         -H 'Hull-App-Id: 5113eca4fc62d87574000096'
         
          \
     -d login='hello@acme.com' \
     -d password='s3cr3t'

Logs a User in with his email and his password and returns the User if the credentials are valid. (beta)

QUERY PARAMETERS
  • loginrequired

    The email of the User to log in

  • passwordrequired

    The User password

Logout

ACCESS: User
GET /api/v1/logout
EXAMPLE REQUEST
Hull.api('/logout', 'get').then(function(response) {
 console.log(response);
});
    curl -X GET 'https://hull-demos.hullapp.io/api/v1/logout'
         -H 'Hull-App-Id: 5113eca4fc62d87574000096'
         \
     -H 'Hull-User-Id: USER_ID' 
         
EXAMPLE RESPONSE
{
  "ok": true,
  "time": 1498494436
}

Logs the User out

Send email confirmation

ACCESS: Public
POST /api/v1/users/request_confirmation_email
EXAMPLE REQUEST
Hull.api('/users/request_confirmation_email', 'post',{
  "email": "hello@acme.com"
}).then(function(response) {
 console.log(response);
});
    curl -X POST 'https://hull-demos.hullapp.io/api/v1/users/request_confirmation_email'
         -H 'Hull-App-Id: 5113eca4fc62d87574000096'
         
          \
     -d email='hello@acme.com'

Sometimes Users do not receive or delete the confirmation email. They can ask for a new one by providing their email. If a there is a User matching with this email, he will receive an email with a link that allows him to confirm his email.

QUERY PARAMETERS
  • emailrequired

    The email where the confirmation instructions will be resent

Reset password

ACCESS: Public
POST /api/v1/users/request_password_reset
EXAMPLE REQUEST
Hull.api('/users/request_password_reset', 'post',{
  "email": "hello@acme.com"
}).then(function(response) {
 console.log(response);
});
    curl -X POST 'https://hull-demos.hullapp.io/api/v1/users/request_password_reset'
         -H 'Hull-App-Id: 5113eca4fc62d87574000096'
         
          \
     -d email='hello@acme.com'

Users can ask a password reset by providing their email. If there is a user matching this email. He will receive a link to change his password

QUERY PARAMETERS
  • emailrequired

    The email where the reset password link will be sent

Get validations staus

GET /api/v1/:user_id/validation_status
EXAMPLE REQUEST
Hull.api('/5147729a255226c974000019/validation_status', 'get').then(function(response) {
 console.log(response);
});
    curl -X GET 'https://hull-demos.hullapp.io/api/v1/5147729a255226c974000019/validation_status'
         -H 'Hull-App-Id: 5113eca4fc62d87574000096'
         
         
EXAMPLE RESPONSE
{
  "valid": true,
  "validations": {
    "email": "user@email.com",
    "password": "xxxxxxxxxxxxxxxxxxxxxx"
  }
}

Returns a hash containing the validation status of a given user.

Link identity

ACCESS: User
POST /api/v1/:user_id/identities
EXAMPLE REQUEST
Hull.api('/5147729a255226c974000019/identities', 'post',{
  "facebook": {
    "access_token": "FACEBOOK_ACCESS_TOKEN"
  }
}).then(function(response) {
 console.log(response);
});
    curl -X POST 'https://hull-demos.hullapp.io/api/v1/5147729a255226c974000019/identities'
         -H 'Hull-App-Id: 5113eca4fc62d87574000096'
         \
     -H 'Hull-User-Id: USER_ID' 
          \
     -d '{
           "facebook": {
             "access_token": "FACEBOOK_ACCESS_TOKEN"
           }
         }'

Adds an identity to a given User with third party tokens (beta)

QUERY PARAMETERS
  • facebookoptional

    A hash containing an access_token key

  • twitteroptional

    A hash containing access_token and access_token_secret keys

  • linkedinoptional

    A hash containing access_token and access_token_secret keys

  • instagramoptional

    A hash containing an access_token key

Unlink identity

ACCESS: User
DELETE /api/v1/:user_id/identities/:provider
EXAMPLE REQUEST
Hull.api('/5147729a255226c974000019/identities/:provider', 'delete').then(function(response) {
 console.log(response);
});
    curl -X DELETE 'https://hull-demos.hullapp.io/api/v1/5147729a255226c974000019/identities/:provider'
         -H 'Hull-App-Id: 5113eca4fc62d87574000096'
         \
     -H 'Hull-User-Id: USER_ID' 
         

Unlinks a given identity from a given User (beta)

PATH PARAMETERS
  • providerrequired

    The identity provider name