Bucket HTTP Tracking API

By Rasmus Makwarth

Bucket is designed for the B2B SaaS use case. The API has three methods: user, company and events. This maps nicely to how most B2B SaaS companies work: A user is part of an organization, and the user does certain interactions (events). Each method supports custom properties, e.g. a company can have custom name and monthly_spend property.

Content-Type

The API only accepts JSON, so the content-type header must be set to application/json

Errors

The API will return 200 status code when calls are successful, and 400 if there's any errors, including an invalid request body.

App ID

To associate your calls with your Bucket app, include the Bucket app ID in the URL, like so https://ingest.bucket.so/{app id}/{api method}

User

The User method is used to track individual users in your application. This method will create a user, if it doesn't exist already. For existing users, it will just update any custom attributes. Use a unique identifier that won't change for userId, e.g. the database ID.

Call this method when a user signs in.

Here's an example:

https://ingest.bucket.so/v67332e7-eb33-1234-9bde-d8f1bf397690/user

{
  "userId": 1234567890,
  "attributes": {
    "name": "Rasmus Makwarth",
    "custom_property": true,
    "some_number": 12
  }
}
field required Type
userId Required String
attributes Optional Object
timestamp Optional ISO 8601
attributesOverwrite Optional Boolean (false)

Company

The Company method is used to track companies (organizations) in your SaaS application. Use a unique identifier that won't change for companyId, e.g. the database ID.

You can associate a user to a company by providing userId. This is important as most features in Bucket will look at company-level data. In other words, if a user isn't associated with a company, the users' events will not be included in most of the results. The Bucket UI will let you know if you have unassociated events.

Call this method when a user signs in.

https://ingest.bucket.so/v67332e7-eb33-1234-9bde-d8f1bf397690/company

{
  "companyId": 101112231415,
  "attributes": {
    "name": "Acme Corp",
    "monthly_spend": 99,
    "activated": true
  },
  "userId": 1234567890
}
field required Type
companyId Required String
attributes Optional Object
timestamp Optional ISO 8601
userId Optional String
attributesOverwrite Optional Boolean (false)

Event

Events are used to track user interactions within your application. We recommened tracking a handful of key features and features you're currently working on. Events are lower cased on ingestion.

To track an event, call this method when users interact with a feature.

https://ingest.bucket.so/v67332e7-eb33-1234-9bde-d8f1bf397690/event

{
  "event": "created report",
  "userId": 1234567890,
  "attributes": {
    "position": "popover",
    "version": 3
  },

}
field required Type
event Required String
userId Required String
attributes Optional Object
timestamp Optional ISO 8601