Notify


Export API

The export API allows raw export of User and Account data to flat files. It has the same querying capabilities as the Search API and Segments definition.

Data can be exported as CSV or JSON files and the result of the export can be either sent via email (containing a link to download the generated export file) or programatically sent to as an HTTP POST to a receiving endpoint.

You can also define a list of traits that will be included in the exported file. Please note that Events cannot be included in the Users export, only Traits are part of the extracted data.

You can find more details about the Export API and all available options in our API reference documentation

Manual exports to connectors & What the dashboard does

The dashboard allows to trigger a manual export of a specific query or segment to a specific Connector. In the background, it uses the Export API to start an export job that will notify a receiver endpoint on the Connector.

Data changes notifications

The last step of the data ingestion in Hull, when new information is captured on an Entity (User or Account) whether it’s an Attribute change, a Segment change or a new Event tracked, results in an outgoing Notification.

Notifications are queued and sent to listening Connectors that use them to propagate the new information or changes to the 3rd party services they integrate with.

Here are the different types of notifications and examples of payloads. See Compute section for a descriptions of the changes object.

user:update

{
  "user": {
    "id": "5a7b32a5d57fdbde8f000007",    
    "accepts_marketing": false,
    "created_at": "2018-02-07T17:08:53Z",
    "indexed_at": "2018-02-12T10:17:24+01:00",    
    "domain": "hull.io",
    "email": "stephane@hull.io",
    "external_id": "1",
    "has_password": false,
    "is_approved": false,
    "segment_ids": ["5a815a3fd57fdbb78a000004"],
    "traits_hello": "world"
  },
  "segments": [{
    "id": "5a815a3fd57fdbb78a000004",
    "name": "Users with Email",
    "type": "users_segment",
    "created_at": "2018-02-12T09:11:42Z",
    "updated_at": "2018-02-12T09:16:33Z"
  }],
  "account": {
    "id": "5a7b32a5d57fdbde8f000005",    
    "created_at": "2018-02-07T17:08:53Z",
    "updated_at": "2018-02-07T17:08:53Z",
    "external_id": "account-1",
    "domain" : "hull.io",
    "name" : "Hull inc"
  },
  "account_segments": [{
    "id": "5a815a3fd56fceb79a000001",
    "name": "Accounts with Domain",
    "type": "accounts_segment",
    "created_at": "2018-02-12T09:11:42Z",
    "updated_at": "2018-02-12T09:16:33Z"
  }],
  "events": [
    {
      "properties": { "foo" : "bar" },
      "event_id": "5ad078db8463ba4a550002dd",
      "user_id": "561fba41450f34efa5000019",
      "event_source": "track",
      "app_name": "Shopify",
      "event": "page",
      "event_type": "track",
      "context": {
        "browser": {
          "name": "Safari",
          "version": "11.0.3",
          "major": 11
        },
        "campaign": {
          "name": null,
          "source": null,
          "medium": null,
          "term": null,
          "content": null
        },
        "device": {
          "name": "Other"
        },
        "ip": "10.52.8.14",
        "os": {
          "name": "Mac OS X",
          "version": "10.13.3"
        },
        "page": {
          "url": "https://example.com/account",
          "host": "example.com",
          "path": "/account"
        },
        "referrer": {
          "url": "https://example.com/",
          "host": "example.com",
          "path": "/",
          "campaign": {
            "name": null,
            "source": null,
            "medium": null,
            "term": null,
            "content": null
          }
        },
        "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_3) AppleWebKit/604.5.6 (KHTML, like Gecko) Version/11.0.3 Safari/604.5.6"
      },
      "anonymous_id": "1519364950-b671ca2b-e54a-4700-a39f-e60f280a89a8",
      "created_at": "2018-04-13 09:30:52 UTC",
      "session_id": "1523611741-5f7a0160-fe87-4577-956a-ae3834ccc18e",
      "app_id": "561fb665450f34b1cf00000f"
    }
  ],
  "changes": {
    "user": {
      "accepts_marketing": [true, false],
      "email": [null, "stephane@hull.io"],
      "is_approved": [null, false],
      "traits_hello": [null, "world"]
    },
    "segments": {
      "left" : [{
        "id": "5a815a3fd57fdbb78a000003",
        "name": "Anonymous Users",
        "type": "users_segment",
        "created_at": "2018-02-12T09:11:42Z",
        "updated_at": "2018-02-12T09:16:33Z"
      }],
      "entered": [{
        "id": "5a815a3fd57fdbb78a000004",
        "name": "Users with Email",
        "type": "users_segment",
        "created_at": "2018-02-12T09:11:42Z",
        "updated_at": "2018-02-12T09:16:33Z"
      }]
    },
    "account": {
      "name": ["Hull", "Hull inc"],
      "updated_at": ["2018-01-10T09:00:09Z", "2018-02-12T09:22:37Z"]
    },
    "account_segments": {
      "left": [{
        "id": "5a815a3fd56fceb78a000009",
        "name": "Recently updated accounts",
        "type": "accounts_segment",
        "created_at": "2018-02-12T09:11:42Z",
        "updated_at": "2018-02-12T09:16:33Z"      
      }],
      "entered": [{
        "id": "5a815a3fd56fceb79a000001",
        "name": "Accounts with Domain",
        "type": "accounts_segment",
        "created_at": "2018-02-12T09:11:42Z",
        "updated_at": "2018-02-12T09:16:33Z"      
      }]
    },
    "is_new": false
  }
}

account:update

{
  "account": {
    "id": "59367d6ff3829c7dfd000001",
    "external_id": "123",
    "created_at": "2017-06-06T10:01:39Z",
    "updated_at": "2018-04-18T12:22:34Z",
    "name": "Hull",
    "domain": "hull.io",
    "foo": "BAR",
    "is_customer": true,
    "clearbit/domain": "hull.io",
    "clearbit/geo_city": "Atlanta",
    "clearbit/linkedin_handle": "company/hull-io",
    "clearbit/name": "Hull",
    "clearbit/phone": "+1 617-832-1731",
    "clearbit/site_title": "Hull",
    "clearbit/site_url": "http://hull.io",
    "clearbit/tags": [ "SAAS", "Technology", "B2B", "Information Technology & Services" ],
    "clearbit/time_zone": "America/New_York",
  },
  "account_segments": [
    {
      "id": "5a6f3036bf7d83932600003a",
      "name": "Product Qualified Lead",
      "type": "accounts_segment",
      "created_at": "2018-01-29T14:31:18Z",
      "updated_at": "2018-01-29T14:31:18Z"
    }
  ],
  "changes": {
    "account": {
      "name": [ "Hull.io", "Hull" ]
    },
    "account_segments": {
      "left": [{
        "id": "5a6f3036bf7d83932600002b",
        "name": "Marketing Qualified Lead",
        "type": "accounts_segment",
        "created_at": "2018-01-29T14:31:18Z",
        "updated_at": "2018-01-29T14:31:18Z"
      }],
      "entered": [{
        "id": "5a6f3036bf7d83932600003a",
        "name": "Product Qualified Lead",
        "type": "accounts_segment",
        "created_at": "2018-01-29T14:31:18Z",
        "updated_at": "2018-01-29T14:31:18Z"
      }]    
    },
    "is_new": false
  }
}

Workspace change notifications

Segment updates

When a UsersSegment or AccountsSegment are created and updated a users_segment:update or accounts_segment:update Notification is sent to all listening connectors. users_segment:delete and accounts_segment:delete are also sent when a Segment is deleted.

example payload :

{
  "id": "5a6f3036bf7d83932600003a",
  "name": "Product Qualified Lead",
  "type": "accounts_segment",
  "created_at": "2018-01-29T14:31:18Z",
  "updated_at": "2018-01-29T14:31:18Z"
}

ship:update

A ship:update notification is sent only to the instance of the Connector when the Ship (or Connector) object is updated.

example payload:

{
  "id": "5abe0899e1948d31bd000002",    
  "created_at": "2018-03-30T09:51:22Z",
  "updated_at": "2018-04-18T12:20:17Z",
  "name": "Testing kraken install",
  "description": null,
  "picture": "https://example.connectors.hullapp.net/picture.png",
  "secret": "xxxxxxxxx",
  "tags": [],
  "manifest_url": "https://example.connectors.hullapp.net/manifest.json",
  "source_url": "https://example.connectors.hullapp.net/",
  "private_settings": {
    "foo": "bar"
  },
  "settings": {},
  "type": "ship",
  "status": { "status": "ok", "messages": [] },
  "manifest": {
    "name": "Example",
    "description": "Example connector",
    "tags": ["batch", "kraken"],
    "private_settings": [{
      "name": "foo",
      "title": "Example setting",
      "type": "string"
    }],
    "subscriptions": [{ "url": "/smart-notifier" }],
    "ui": false,
    "picture": "picture.png",
    "readme": "readme.md"
  }
}

Logging

logging formats

(incoming|outgoing).(user|account|event).(start|skip|success|error)

user|account ids, emails, anonymous IDs etc

connector_name, connector_id