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

A 401 indicates an Invalid or Corrupt API key. Check the response for the error message.

javascript
{
    "statusCode": 401,
    "message": "Unauthorized",
    "error": "Unauthorized"
}

400 Bad Request

A 400 indicates an invalid upload request, check the response for the error message.

javascript
{
    "statusCode": 400,
    "message": [
        "user_id should not be empty"
    ],
    "error": "Bad Request"
}

413 Payload Too Large

A 413 indicates the payload has exceeded the limit. Check the response for the error message.

javascript
{
    "statusCode": 413,
    "message": "Payload Too Large"
}

429 Too Many Requests

A 429 indicates too many requests. Several calls have exceeded the limit. Check the response for the error message.

javascript
{
    "statusCode": 429,
    "message": "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`