Related Apps

Advanced AI Analytics & Automations

Description

The Custom Events API allows you to capture timestamped data for specific events, like “Offer Made”, “Payment Received”, “Tag Added”, etc.

Status

Featured

Overview

Previously in Streamlined Analytics, if you wanted to see when something happened, you were limited to the basic fields, like contact/opportunity/appointment created at, last updated, etc.

There was no way to track specific events, like when a tag was added or when a contact hit a certain stage in the pipeline.

Now though, we have a dedicated API endpoint and filter builder for these events!

Creating Events

Using the custom events API is easy and free.

Create an API Key

Firstly, you’ll need to create an API key. This can only be done by the team right now, so you’ll need to 💬Get in Touch for us to generate your API key.

Endpoint Basics

We’ll dive into how your events should be structured below. However, the basics are here:

{
	"endpoint_url": "https://receiver.streamlined.so/custom-events/ingestion/v1",
	"headers": "X-API-Key"
}

Use a Workflow to Send Events

The easiest way to send events to Streamlined is using the Webhoook workflow action in CRM.

This Webhook action (not the Custom Webhook) is a free workflow action, and will not incur any additional cost.

Event Payload

Here are the possible event values you can send:

{
	"event_name": "A descriptive name for the event, shown in dashboard",
	"location_id": "The location ID this event corresponds to",
	"distinct_id": "Optional: Something unique to this event, to prevent duplicates",
	"contact_id": "Optional: Allows you to associate this event to a single contact, meaning you can filter on events using contact fields in the dashboard",
	"timestamp": "Optional: One of UNIX timestamp in seconds or milliseconds, or an ISO 8601 string. If no timestamp is provided, the time of the first request will be used",
	"properties": {
		"description": "Optional: You can pass this properties field to store other data about the event. For instance, if you wanted to track every time a payment was collected, you could store the total amount of the transaction. Only strings and finite numbers are accepted.",
		"value": 1
	}
}

The only required fields in this payload are the event_name, distinct_id, and location_id.

This also means that every event must be associated to a single sub-account.

Payload Examples

Here is an example, sending a minimal payload using the Webhook workflow action in the CRM:

Sending Custom Properties

If you wish to send properties along with your event, you may need to use the Custom Webhook workflow action instead (which is billed as a premium action).

Note that these custom properties can’t yet be filtered on or displayed in the dashboard.

Here’s an example of how you might send the event:

Note how we created the distinct_id property here. We used the month and year, like “09/25” - meaning that this will allow us to repeat the event every month, but we can’t send the same event every month.

Displaying Events

In order to display custom events, you can simply add them to your custom metric calculations as shown below:

Other Details

Deleting Events

Currently, there is no dedicated endpoint for deleting custom events that you’ve sent.

If you’d like a specific event or set of events removed, you should 💬Get in Touch.

However, if your events are tied to a specific contact_id, you should be aware that deleting that contact will cascade the deletion to any custom events for that contact as well.

Other Relations

In the future, we plan to add support for relating custom events to other objects, such as opportunities, appointments, tasks, notes, etc.

Please request these if you would like them to be supported.

Distinct Events

If you send two events with the same distinct ID, the event will be updated, but the timestamp will remain the same.

Rate Limits

There are no rate limits as of now, though that may change in the future if there is significant adoption.

Frequent Questions