HTTP Tracking API Specifications

The Plainflow HTTP Tracking API lets you record data from any website or application.

⚠️ We suggest to use the native libraries if it’s possible, because they are built for high-performance.

Requirements

The API endpoints only accept data formatted in JSON with a valid authentication header. So you must set both Content-Type and Authorization headers along with your requests.

The Content-Type header must be set to application/json.

About the request authentication, Plainflow uses HTTP Basic Auth, which involves a ‘username:password’ string that is base64 encoded and prepended with the string ‘Basic ‘.

YOUR_SECRET_KEY (e.g. 'superSecretKey1234') will be the username, the password field must be left empty. Once you have the ‘username:password’ string ready (e.g. 'superSecretKey1234:'), you must base64 encode it.

The final result will be 'Authorization: Basic c3VwZXJTZWNyZXRLZXkxMjM0Og=='.

Limitations

There isn’t any hard rate limit, but we suggest you not to send more than 100 requests per second.

We strongly encourage the usage of the batch method to send a huge amount of data.

The Max Request Size for each API call is 15kb. The batch endpoint accepts a maximum of 500kb per batch instead.

Plainflow’s API will respond with 400 Bad Request if these limits are exceeded.

HTTP API calls

Identify

identify lets you tie a user to their actions and record traits about them. It includes a unique User ID and any optional traits you know about them.

We recommend calling identify a single time when the user’s account is first created, and only identifying again later when their traits change.

Example identify call:

POST https://pipe.plainflow.net/v1/identify
{
  "userId": "pfl00123",
  "traits": {
    "email": "mark.twain@plainflow.com",
    "name": "Mark Twain",
    "industry": "Publishing"
  },
  "context": {
    "ip": "20.17.2.9"
  },
  "timestamp": "2017-02-09T01:02:08.123Z"
}

This call is identifying the user by his unique User ID (the one you know him by in your database) and labeling him with email, name, and industrytraits.

anonymousId optionalStringA pseudo-unique substitute for a User ID, for cases when you don’t have an absolutely unique identifier. See the Identities docs for more detail
context optionalObjectDictionary of extra information that provides useful context about a message, but is not directly related to the API call like ip address or locale. See the Context field docs for more detail
timestamp optionalDateTimestamp when the message itself took place, defaulted to the current time by the Segment Tracking API. It is an ISO-8601 date string. If the event just happened, leave it out and we’ll use the server’s time. If you’re importing data from the past, make sure you to provide a timestamp. See the Timestamps fields docs for more detail.
traits optionalObjectFree-form dictionary of traits of the user, like email or name. See the Traits field docs for a list of reserved trait names
userId requiredStringUnique identifier for the user in your databaseA userIdoranonymousIdis requiredSee the Identities docs for more detail

Find details on the identify method payload in our Identify doc page.

Track

track lets you record the actions your users perform. Every action triggers what we call an “event”, which can also have associated properties.

You’ll want to track events that are indicators of success for your site, like Signed Up, Item Purchased or Article Bookmarked.

To get started, we recommend tracking just a few important events. You can always add more later!

Example track call:

POST https://pipe.plainflow.net/v1/track


{
  "userId": "pfl00123",
  "event": "Referral Invitation",
  "properties": {
    "discount": "50%",
    "referral_id": "ref13456"
  },
  "context": {
    "ip": "20.17.2.9"
  },
  "timestamp": "2017-02-09T01:02:08.123Z"
}

track event properties can be anything you want to record. In this case, discount and referral_id.

The track call has the following fields:

anonymousId optionalStringA pseudo-unique substitute for a User ID, for cases when you don’t have an absolutely unique identifier. See the Identities docs for more detail
context optionalObjectDictionary of extra information that provides useful context about a message, but is not directly related to the API call like ip address or locale. See the Context field docs for more detail
event requiredStringName of the action that a user has performed. See the Event field docs for more detail
properties optionalObjectFree-form dictionary of properties of the event, like referral_id. See the Properties docs for a list of reserved property names
timestamp optionalDateTimestamp when the message itself took place, defaulted to the current time by the Plainflow Tracking API. It is an ISO-8601 date string. If the event just happened, leave it out and we’ll use the server’s time. If you’re importing data from the past, make sure you to provide a timestamp. See the Timestamps fields docs for more detail.
userId requiredStringUnique identifier for the user in your database. A userId or anonymousId is required. See the Identities docs for more detail

Find details on best practices in event naming as well as the track method payload in our Track Spec.

Page

The page method lets you record page views on your website, along with optional extra information about the page being viewed.

Example page call:

POST https://pipe.plainflow.net/v1/page
{
  "userId": "pfl00123",
  "name": "Tracking HTTP API",
  "timestamp": "2017-02-09T01:02:08.123Z"
}

The page call has the following fields:

anonymousId optionalStringA pseudo-unique substitute for a User ID, for cases when you don’t have an absolutely unique identifier. See the Identities docs for more detail
context optionalObjectDictionary of extra information that provides useful context about a message, but is not directly related to the API call like ip address or locale. See the Context field docs for more detail
name optionalStringName of the page. For example, most sites have a “Signup” page that can be useful to tag, so you can see users as they move through your funnel.
properties optionalObjectFree-form dictionary of properties of the page, like url and referrer. See the Properties field docs for a list of reserved property names
timestamp optionalDateTimestamp when the message itself took place, defaulted to the current time by the Segment Tracking API. It is anISO-8601 date stringIf the event just happened, leave it out and we’ll use the server’s time. If you’re importing data from the past, make sure you to provide a timestamp. See the Timestamps fields docs for more detail.
userId requiredStringUnique identifier for the user in your database. A userId or anonymousId is required. See the Identities docs for more detail

Find details on the page payload in our Page Spec.

Screen

The screen method let you record whenever a user sees a screen of your mobile app.

You’ll want to send the screen message whenever a user requests a page of your app.

Example screen call:

POST https://pipe.plainflow.net/v1/screen
{
  "userId": "pfl00123",
  "name": "Tracking HTTP API",
  "timestamp": "2017-02-09T01:02:08.123Z"
}

The screen call has the following fields:

anonymousId optionalStringA pseudo-unique substitute for a User ID, for cases when you don’t have an absolutely unique identifier. See the Identities docs for more detail
context optionalObjectDictionary of extra information that provides useful context about a message, but is not directly related to the API call like ip address or locale. See the Context field docs for more detail
name optionalStringName of the screen. See the Name field docs for more detail
properties optionalObjectFree-form dictionary of properties of the screen, like name. See the Properties field docs for a list of reserved property names
timestamp optionalDateTimestamp when the message itself took place, defaulted to the current time by the Segment Tracking API. It is anISO-8601 date string. If the event just happened, leave it out and we’ll use the server’s time. If you’re importing data from the past, make sure you to provide a timestamp. See the Timestamps fields docs for more detail.
userId requiredStringUnique identifier for the user in your database. A userId or anonymousId is required. See the Identities docs for more detail

Find details on the screen payload in our Screen Spec.

Alias

alias is how you associate one identity with another. This advanced method is used to associate an anonymous user with an identified user once they sign up.

Example alias call:

POST https://pipe.plainflow.net/v1/alias
{
  "previousId": "39239-239239-239239-23923",
  "userId": "pfl00123",
  "timestamp": "2017-02-09T01:02:08.123Z"
}

The alias call has the following fields:

context optionalObjectDictionary of extra information that provides useful context about a message, but is not directly related to the API call like ip address or locale. See the Context field docs for more detail
previousId requiredStringPrevious unique identifier for the user. See the Previous ID field docs for more detail
timestamp optionalDateTimestamp when the message itself took place, defaulted to the current time by the Segment Tracking API. It is an ISO-8601 date string. If the event just happened, leave it out and we’ll use the server’s time. If you’re importing data from the past, make sure you to provide a timestamp. See the Timestamps fields docs for more detail.
userId requiredStringUnique identifier for the user in your database. A userId or anonymousId is required. See the Identities docs for more detail.

For more details on the alias call and payload, check out our Alias Spec.

Historical Import

You can import historical data by adding the timestamp argument to any of your method calls. This can be helpful if you’ve just switched to Segment.

Historical imports can only be done into destinations that can accept historical timestamp’ed data.

Note: If you’re tracking things that are happening right now, leave out the timestamp and our servers will timestamp the requests for you.

Batch

The batch method lets you send a series of identify, group, track, page and screen requests in a single batch, saving on outbound requests. Our server-side and mobile clients make use of this method automatically for higher performance.

There is a maximum of 500kb per batch request and 32kb per call.

Here’s the what the batch request signature looks like:

POST https://pipe.plainflow.net/v1/batch
{
  "batch": [
    {
      "type": "identify",
      "userId": "pfl00123",
      "traits": {
        "email": "john@example.net",
        "name": "John Doe",
        "age": 23
      },
      "timestamp": "2017-02-09T01:02:08.123Z"
    },
    {
      "type": "track",
      "userId": "pfl00123",
      "event": "Video Played",
      "properties": {
        "name": "Goodbye Cassini",
        "artist": "NASA"
      },
      "timestamp": "2017-02-10T01:02:08.123Z"
    },
    {
      "type": "identify",
      "userId": "971mj8mk7p",
      "traits": {
        "email": "jane@doe.com",
        "name": "Jane Doe",
        "age": 32
      },
      "timestamp": "2017-02-11T01:02:08.123Z"
    },
    {
      "type": "track",
      "userId": "971mj8mk7p",
      "event": "Video Played",
      "properties": {
        "name": "The Fundamentals Of Startups",
        "artist": "Paul Graham"
      },
      "timestamp": "2017-03-09T01:02:08.123Z"
    }
  ],
  "context": {
    "device": {
      "type": "phone",
      "name": "Apple iPhone X"
    }
  }
}
batch ArrayAn array of identify, group, track, page and screen method calls. Each call must have an type property with a valid method name.
context Object, optionalThe same as Contextfor other calls, but it will be merged with any context inside each of the items in the batch.

Collecting IP

When sending a HTTP call from a user’s device, you can collect the IP address by setting context.direct to true.


Not using Plainflow yet? Get your free account here. 👈