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`

Survey

This endpoint retrieves a list of available surveys. It returns the survey ID, name, description, and details about each screen/question in the survey.

javascript
GET https://api.1flow.app/v1/survey

javascript
[
    {
      "survey_id": "string",
      "name": "string",
      "description": "string",
      "trigger_event_name": "string",
      "screens": [
        {
          "screen_id": "string",
          "title": "string",
          "message": "string",
          "input": {
            "input_type": "string",
            "choices": "array",
            "other_option_id": "string | null"
          }
        }
      ]
    }
 ]

Response Fields:

survey_id: The unique identifier for the survey.

name: The name of the survey.

description: The description of the survey.

screens: A list of questions/screens in the survey. Each screen includes:

screen_id: The unique identifier for the question.
title: The title of the question.
message: The description or prompt for the question.
input: The input configuration (e.g., type of question, possible choices)

Possible input types:

Each screen in the survey contains a field called input_type, which denotes the type of question being asked. Below is a list of possible screen types and their descriptions:

text: A question that expects a text response (e.g., open-ended questions).

mcq: Multiple Choice Question (single answer).

rating: A general question with a 1-5 scale.

thank_you: A screen shown after completing the survey to thank the participant.

rating-numerical: A numerical rating question used for calculating Detractors (0-6), Passives (7-8), and Promoters (9-10).

rating-5-star: A 5-star rating question.

rating-emojis: A rating system using emojis, where the ratings are calculated on a 1-5 scale.

checkbox: A question allowing multiple answers with checkboxes.

nps: Net Promoter Score (NPS) question (usually asking on a scale from 0-10).

short-text: A short text answer question (for brief responses).

welcome-screen: A welcome screen displayed at the beginning of the survey.

end-screen: A final screen that marks the end of the survey.

Add Response

This endpoint allows users to submit survey responses. Responses are tied to a specific survey ID and user ID.

Here’s what the add response request looks like:

javascript
POST https://api.1flow.app/v1/survey/add/response

Payload:

javascript
{
    "survey_id":"string",
    "user_id":"string",
    "os":"string",
    "answers":[
        {
            "screen_id":"string",
            "answer": "string or choice_id",
            "other_option_value":"string"
        },
        .
        .
        .
        ....

    ]

}

Field		Type	Description
`survey_id`	required	String	The unique identifier for the survey
`user_id`	required	String	Unique identifier for the user in your database.
`os`	required	String	This field is now required and can have one of the following values:1. iOS2. android3. windows4. mac
`answers`	required	Array	A list of answers, where each answer includes:screen_id: The ID of the question being answered.answer: The answer to the question (can be single or multiple options, or text).other_option_value: The value for the "Other" option, if applicable.

Note:

For multiple choice questions, the answer should be choice_id corresponding to the selected option.

For checkbox questions, if multiple options are selected, send a comma-separated list of choice_ids representing the selected options.

You can find the choice_id in the choices listing.

Survey Impression Event(Optional)

When a response is added through the API, the survey_impression event is automatically logged. This event tracks the total view count of the survey on the responses page. Logging the impression is optional but encouraged.

Event Logging

Event Name: survey_impression

This event helps track how many users interacted with the survey.

Properties for survey_impression Event Here are the key properties associated with the survey_impression event: survey_id: The unique identifier of the survey being viewed.

Example survey_impressioncall:

javascript
POST https://api.1flow.app/v1/track

javascript
{
  "user_id": "62c678adad2302d24ac5e291",
  "event": "survey_impression",
  "properties": {
    "survey_id": "survey_id"
  },
  "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.survey_id`	required	Object	The unique identifier of the survey being viewed.
`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.