Bucket HTTP Tracking API

May 27, 2021

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