HTTP API Source

Overview

The Firstparty Event HTTP API is the lowest-level way of sending Events to Firstparty. SDKs, including Firstparty.js, rely on the HTTP API as their method of sending data to Firstparty.

This HTTP Source is useful when you want to send data directly to Firstparty without relying on an existing library or when a library in your language doesn't exist. It's also helpful for debugging, testing, and prototyping new integrations.

The Firstparty Event collection API has only two endpoints: /events/track for sending a single Event, and /events/track/bulk for sending multiple Events in one payload. This may be different from what you've seen with other analytics or measurement providers, and is designed to make data collection flexible and customizable for anyone to configure at any time, rather than always requiring updates to code to make data collection changes.

Base URL

In order to collect Events with the HTTP Source, your client will make HTTP requests to the Domain you've configured for your Source.

For example, if the Domain you've configured is fp.rosebudmotels.com you'll make an HTTP POST request to fp.rosebudmotels.com/events/track to collect a new Event.

Authentication

No authentication is required to collect Events with the HTTP API (unlike most other requests to the Firstparty API).

Request Requirements

  • The content-type header must be set to 'application/json'.
  • A Write Key is required to be sent with every Event (more below).

Debugging

Every request to the /events/track endpoint will result in a 200 OK response. To debug your requests, use the Debugger tab within the Source you're sending data to in the Firstparty UI.

Measurement Methods

The HTTP API Source only collects Events via the /events/track and/events/track/bulk endpoints.

Track a Single Event

To send a single Event to Firstparty, make an HTTP POST request to /events/track that meets the requirements above, along with a JSON object with the keys outlined below as necessary.

POST https://fp.rosebudmotels.com/events/track

{
  "profile_id": "PR123456789012345678901234567890",
  "event": "Form Completed",
  "properties": {
    "email": "stevie@rosebudmotels.com",
    "name": "Stevie Budd"
  },
  "context": {
    "ip": "12.34.56.78"
  }
}

The track endpoint accepts a JSON object with these fields:

Item KeyRequirementDescription
namerequiredThe required name of the Event to collect
profile_idoptionalThe ID of the Profile generating the Event. If no Profile ID is provided, Firstparty will create a new Profile and return the new Profile ID in the HTTP response.
session_idoptionalThe ID of the Session associated with the Event. If a Session ID is not provided, Firstparty may create a new Session and return the new Session ID in the HTTP response, depending on your Firstparty configuration.
propertiesoptionalAn optional key-value object of Properties to collect along with the Event. If the Event name was "Form Completed", one property may be "email_address"
contextoptionalAn optional key-value object of context to describe where the Event was generated. Read more about Context on the Event docs.
On This Page