logo

Introduction

Use the HTTP API to send data directly from your server to 1Flow. This includes live events, historical imports, and user profile data.
💡
Events tracked using this API can be used to define target audience for surveys. However, they cannot trigger front-end surveys since the user is not present in the product. Whenever possible, please track events on the frontend instead of using this API.

Headers

Authentication

Authenticate to the HTTP API by sending your project’s API Key in the request headers.

Content-Type

To send data to 1Flow’s Public API, a content-type header must be set to 'application/json'.
javascript
api_key: {{API_KEY}} Content-Type: application/json

Rate Limits

The 1Flow API has no hard rate limit. However, 1Flow recommends not exceeding 500 requests per second.

Max Request Size

There is a maximum of 32KB per standard API request. The batch API endpoint accepts a maximum of 500KB per request. The API responds with 413 Payload Too Large if these limits are exceeded.

Errors

401 Unauthorized
400 Bad Request
413 Payload Too Large
429 Too Many Requests

Identify

identify lets you add or update users to their actions and record traits about them. It includes a unique User ID and any optional characteristics that you know.
1Flow recommends calling identify a single time when the user is first created, and only identifying again later when their traits change.
Example identify call:
javascript
POST https://api.1flow.app/v1/identify
json
{ "user_id": "4f25f8f5c23b41bd93679692", "traits":{ "email": "test@gmail.com" }, "timestamp": "2022-09-30T03:26:24.894Z" }
Field
Type
Description
user_id
required
String
Unique identifier for the user in your database.
traits
optional
Object
Free-form dictionary of traits of the user, like email  or name
timestamp
optional
Date
Timestamp when the message itself took place, defaulted to the current time by the 1Flow Public API, as an ISO-8601  format date string. You must use ISO-8601 date strings that include timezones. If timezone offset is not provided, it is assumed to be in the same timezone as described in your 1Flow project settings.

Delete user trait

You can delete a user trait for any user by passing in null in identify() call. The user trait with null value will be removed from this user’s profile.

Track

track lets you record the actions your users perform. Every action triggers an “event”, which can also have associated properties.
You’ll want to track events that are indicators of success for your site or app. like page viewed, click, or purchase
To get started, try tracking just a few important events. You can always add more later.
Example track call:
javascript
POST https://api.1flow.app/v1/track
json
{ "user_id": "62c678adad2302d24ac5e291", "event": "Page viewed", "properties": { "page": "homePage" }, "timestamp": "2022-09-30T04:54:56.396Z" }
Field
Type
Description
user_id
required
String
Unique identifier for the user in your database.
event
required
String
Name of the action that a user has performed.
properties
optional
Object
Free-form dictionary of properties of the event like revenue
timestamp
optional
Date
Timestamp when the message itself took place, defaulted to the current time by the 1Flow Public API, as an ISO-8601  format date string. You must use ISO-8601 date strings that include timezones. If timezone offset is not provided, it is assumed to be in the same timezone as described in your 1Flow project settings.

Batch

The batch method lets you send a series of identify and track requests in a single batch, saving on outbound requests.
Here’s what the batch request looks like:
javascript
POST https://api.1flow.app/v1/batch
javascript
{ "batch": [ { "type": "identify", "user_id": "019mr8mf4r", "traits": { "email": "jake@yahoo.com", "name": "Jake Peterson", "age": 26 }, "timestamp": "2012-12-02T00:30:08.276Z" }, { "type": "track", "user_id": "019mr8mf4r", "event": "Song Played", "properties": { "name": "Fallin for You", "artist": "Dierks Bentley" }, "timestamp": "2012-12-02T00:30:12.984Z" }, ] }
Field
Type
Description
batch
required
Array
An array of identify and track  method calls. Each call must  have a type  property with valid method names identify or track