HTTP API

Send event data from source to destination using our HTTP API.

11 minute read

RudderStack offers an easy-to-use HTTP API that you can use to send your events programmatically. The API is fully Segment-compatible and is helpful in cases where you cannot use the SDKs.

See the HTTP API documentation for details, along with the sample requests and responses.

RudderStack recommends using the RudderStack SDKs for tracking and routing user events from your sources. The SDKs also offer automatic tagging of user context, event batching, and a retry functionality during delivery failure.

Prerequisites

The RudderStack HTTP server must be accessible from your HTTP client. See the Data Plane Setup guide for more information.
Set up a source and destination in RudderStack.
Download (Right click > Save Link As) and import the Postman collection in this URL. Then, edit the variables source_write_key and data_plane_urlwith your source write key and the data plane URL.

Authorization

RudderStack uses Basic Authentication for authenticating all HTTP requests.

All popular HTTP clients (for example, CURL, Postman, HTTPie) have default support for Basic Authentication.

The Basic Authentication for this API requires a username and password where:

Username is the source write key.
Password is an empty string ("").

For example, if the source write key is 1Xk5DChfJAol3xtW7qNnK1apo5p, your HTTP request must have the following HTTP header Authorization: Basic MVhrNURDaGZKQW9sM3h0VzdxTm5LMWFwbzVwOg==

Note that:
To send events via the RudderStack HTTP API, the Content-Type header must be set to application/json.
To generate the HTTP header, you can use the Basic Authentication Header Generator.

Base URL

Use the data plane URLThe data plane URL is the location where events are routed and sent to the RudderStack backend for processing. You can find this URL in the home page of your RudderStack dashboard. as the base URL for your API requests.

Identify

The identify call lets you associate a visiting user to their actions and record any associated traits.

POST

/v1/identify

Sample payload

{
  "userId": "identified user id",
  "anonymousId":"anon-id-new",
  "context": {
    "traits": {
       "trait1": "new-val"  
    },
    "ip": "14.5.67.21",
    "library": {
        "name": "http"
    }
  },
  "timestamp": "2020-02-02T00:23:09.544Z"
}

Usage

curl -u <source_write_key>: -X POST <data_plane_url>/v1/identify \
-d @identify.json \
--header "Content-Type: application/json"

http -a <source_write_key>: <DATA_PLANE_URL>/v1/identify < identify.json

Accepted fields

anonymousId

optional

string

Sets the user ID for cases where there is no unique identifier for the user. Either userId or anonymousId is required.

userId

required, if anonymousId is not present

string

Unique identifier for a particular user in your database.

context

optional

object

Dictionary of information that provides context about a message. However, it is not directly related to the API call.

integrations

optional

object

A dictionary containing the destinations to be either enabled or disabled.

timestamp

optional

datetime

The timestamp of the message’s arrival. If you are passing the timestamp in the event, make sure it conforms to the ISO 8601 date format yyyy-MM-ddTHH:mm:ss.SSSZ. For example: 2022-02-01T19:14:18.381Z

traits

optional

object

Dictionary of the traits associated with the user, such as nameor email

Track

The track call lets you track user actions along with any properties associated with them.

POST

/v1/track

Sample payload

{
  "userId": "identified user id",
  "anonymousId":"anon-id-new",
  "event": "Product Purchased new",
  "properties": {
    "name": "Shirt",
    "revenue": 4.99
  },
  "traits": {
    "email": "alex@example.com"
  }
  "context": {
    "ip": "14.5.67.21",
    "library": {
        "name": "http"
    }
  },
  "timestamp": "2020-02-02T00:23:09.544Z"
}

Usage

curl -u <source_write_key>: -X POST <data_plane_url>/v1/track \
-d @track.json \
--header "Content-Type: application/json"

http -a <source_write_key>: <DATA_PLANE_URL>/v1/track < track.json

Accepted fields

anonymousId

optional

string

Sets the user ID for cases where there is no unique identifier for the user. Either userId or anonymousId is required.

userId

required, if anonymousId is not present

string

Unique identifier for a particular user in your database.

context

optional

object

Dictionary of information that provides context about a message. However, it is not directly related to the API call.

event

required

string

Name of the event being performed by the user.

properties

optional

object

Dictionary of the properties associated with a particular event.

traits

optional

object

Explicitly specified user traits. Note that:

The client-side SDKs automatically add this object persisted from the identify event.
Any traits specified in the track event will override the existing traits persisted from the identify event.
The override will be applicable only for the particular track event where the traits object is specified explicitly. For future events, the user traits persisted from the identify event are used.

integrations

optional

object

A dictionary containing the destinations to be either enabled or disabled.

timestamp

optional

datetime

Page

The page call lets you record your website’s page views with any additional relevant information about the viewed page.

POST

/v1/page

Sample payload

{
  "userId": "identified user id",
  "anonymousId":"anon-id-new",
  "name": "Page View",
  "properties": {
    "title": "Home",
    "path": "/"
  },
  "context": {
    "ip": "14.5.67.21",
    "library": {
        "name": "http"
    }
  },
  "timestamp": "2020-02-02T00:23:09.544Z"
}

Usage

curl -u <source_write_key>: -X POST <data_plane_url>/v1/page \
-d @page.json \
--header "Content-Type: application/json"

http -a <your_write_key>: <DATA_PLANE_URL>/v1/page < page.json

Accepted fields

anonymousId

optional

string

Sets the user ID for cases where there is no unique identifier for the user. Either userId or anonymousId is required.

userId

required, if anonymousId is not present

string

Unique identifier for a particular user in your database.

context

optional

object

Dictionary of information that provides context about a message. However, it is not directly related to the API call.

integrations

optional

object

A dictionary containing the destinations to be either enabled or disabled.

name

required

string

Name of the page being viewed.

properties

optional

object

Dictionary of the properties associated with a particular event.

timestamp

optional

datetime

Screen

The screen call is the mobile equivalent of the page call. It lets you record whenever your user views their mobile screen with any additional relevant information about the screen.

POST

/v1/screen

Sample payload

{
  "userId": "identified user id",
  "anonymousId":"anon-id-new",
  "name": "Screen View",
  "properties": {
    "prop1": "5"
  },
  "context": {
    "ip": "14.5.67.21",
    "library": {
        "name": "http"
    }
  },
  "timestamp": "2020-02-02T00:23:09.544Z"
}

Usage

curl -u <source_write_key>: -X POST <data_plane_url>/v1/screen \
-d @screen.json \
--header "Content-Type: application/json"

http -a <source_write_key>: <DATA_PLANE_URL>/v1/screen < screen.json

Accepted fields

anonymousId

optional

string

Sets the user ID for cases where there is no unique identifier for the user. Either userId or anonymousId is required.

userId

required, if anonymousId is not present

string

Unique identifier for a particular user in your database.

context

optional

object

Dictionary of information that provides context about a message. However, it is not directly related to the API call.

integrations

optional

object

A dictionary containing the destinations to be either enabled or disabled.

name

required

string

Name of the screen being viewed.

properties

optional

object

Dictionary of the properties associated with the page being viewed, such as url and referrer.

timestamp

optional

datetime

Group

The group call lets you link an identified user with a group such as a company, organization, or an account. It also lets you record any custom traits associated with that group, like the name of the company, the number of employees, etc.

POST

/v1/group

Sample payload

{
  "userId": "user123",
  "groupId": "group1",
  "traits": {
    "name": "Company",
    "industry": "Industry",
    "employees": 123
  },
  "context": {
    "traits": {
       "trait1": "new-val"  
    },
    "ip": "14.5.67.21",
    "library": {
        "name": "http"
    }
  },
  "timestamp": "2020-01-21T00:21:34.208Z"
}

Usage

curl -u <source_write_key>: -X POST <data_plane_url>/v1/group \
-d @group.json \
--header "Content-Type: application/json"

http -a <source_write_key>: <DATA_PLANE_URL>/v1/group < group.json

Accepted fields

anonymousId

optional

string

Sets the user ID for cases where there is no unique identifier for the user. Either userId or anonymousId is required.

userId

required, if anonymousId is not present

string

Unique identifier for a particular user in your database.

context

optional

object

Dictionary of information that provides context about a message. However, it is not directly related to the API call.

integrations

optional

object

A dictionary containing the destinations to be either enabled or disabled.

groupId

required

string

Unique identifier of the group, as present in your database.

traits

optional

object

Dictionary of the traits associated with the group, such as nameor email

timestamp

optional

datetime

Alias

The alias call lets you merge different identities of a known user.

alias is an advanced method that lets you change the tracked user’s ID explicitly. This method is useful when managing identities for some of the downstream destinations.

POST

/v1/alias

Sample payload

{
  "userId": "user123",
  "previousId": "previd1",
  "context": {
    "traits": {
       "trait1": "new-val"  
    },
    "ip": "14.5.67.21",
    "library": {
        "name": "http"
    }
  },
  "timestamp": "2020-01-21T00:21:34.208Z"
}

Usage

curl -u <source_write_key>: -X POST <data_plane_url>/v1/alias \
-d @alias.json \
--header "Content-Type: application/json"

http -a <source_write_key>: <DATA_PLANE_URL>/v1/alias < alias.json

Accepted fields

userId

required, if anonymousId is not present

string

Unique identifier for a particular user in your database.

context

optional

object

Dictionary of information that provides context about a message. However, it is not directly related to the API call.

integrations

optional

object

A dictionary containing the destinations to be either enabled or disabled.

previousId

required

string

The previous unique identifier of the user.

traits

optional

object

Dictionary of the traits associated with the group, such as nameor email

timestamp

optional

datetime

Merge

This API is deprecated and will be discontinued soon.

The merge call enables you to merge different user identities and associate them to a single customer profile in the warehouse.

RudderStack supports merge for identity resolution in the BigQuery and Snowflake warehouse destinations.

POST

/v1/merge

Sample Payload

{
  "userId": "1hKOmRA4GRlm",
  "mergeProperties": [{
      "type": "email",
      "value": "alex@example.com"
    },
    {
      "type": "mobile",
      "value": "+1-202-555-0146"
    }
  ]
}

Usage

curl -u <source_write_key>: -X POST <data_plane_url>/v1/merge \
-d @merge.json \
--header "Content-Type: application/json"

http -a <source_write_key>: <DATA_PLANE_URL>/v1/merge < merge.json

Accepted fields

userId

required, if anonymousId is not present

string

Unique identifier for a particular user in your database.

anonymousId

required, if userId is not present

string

Sets the user ID for cases where there is no unique identifier for the user. Either userId or anonymousId is required.

mergeProperties

required

object

The user properties to be merged and connected to a given user profile.

Batch

The batch call allows you to send a series of identify, track, page, group and screen requests in a single batch. This call helps you minimize the number of outbound requests, thus enabling better performance.

RudderStack sets a maximum limit of 4 MB per batch request and 32 KB per call.

POST

/v1/batch

Sample payload

{
    "batch": [{
            "userId": "identified user id",
            "anonymousId": "anon-id-new",
            "type": "identify",
            "context": {
                "traits": {
                    "trait1": "new-val"
                },
                "ip": "14.5.67.21",
                "library": {
                    "name": "http"
                }
            },
            "timestamp": "2020-02-02T00:23:09.544Z"
        },
        {
            "userId": "identified user id",
            "anonymousId": "anon-id-new",
            "event": "Product Purchased new",
            "type": "track",
            "properties": {
                "name": "Shirt",
                "revenue": 4.99
            },
            "context": {
                "ip": "14.5.67.21",
                "library": {
                    "name": "http"
                }
            },
            "timestamp": "2020-02-02T00:23:09.544Z"
        },
        {
            "userId": "identified user id",
            "anonymousId": "anon-id-new",
            "name": "Page View",
            "type": "page",
            "properties": {
                "title": "Home",
                "path": "/"
            },
            "context": {
                "ip": "14.5.67.21",
                "library": {
                    "name": "http"
                }
            },
            "timestamp": "2020-02-02T00:23:09.544Z"
        },
        {
            "userId": "identified user id",
            "anonymousId": "anon-id-new",
            "name": "Screen View",
            "type": "screen",
            "properties": {
                "prop1": "5"
            },
            "context": {
                "ip": "14.5.67.21",
                "library": {
                    "name": "http"
                }
            },
            "timestamp": "2020-02-02T00:23:09.544Z"
        },
        {
            "userId": "user123",
            "type": "group",
            "groupId": "group1",
            "traits": {
                "name": "Company",
                "industry": "Industry",
                "employees": 123
            },
            "context": {
                "traits": {
                    "trait1": "new-val"
                },
                "ip": "14.5.67.21",
                "library": {
                    "name": "http"
                }
            },
            "timestamp": "2020-01-21T00:21:34.208Z"
        },
        {
            "userId": "user123",
            "previousId": "previd1",
            "type":"alias",
            "context": {
                "traits": {
                    "trait1": "new-val"
                },
                "ip": "14.5.67.21",
                "library": {
                    "name": "http"
                }
            },
            "timestamp": "2020-01-21T00:21:34.208Z"
        }

    ]
}

Usage

curl -u <source_write_key>: -X POST <data_plane_url>/v1/batch \
-d @batch.json \
--header "Content-Type: application/json"

http -a <source_write_key>: <DATA_PLANE_URL>/v1/batch < batch.json

Accepted fields

batch

required

array

An array of identify, track, page, group and screen calls. Each call must have a type property and a valid method name.

HTTP responses

The HTTP API returns a 200 response for successful API requests.
The API returns a 400 response for invalid requests with an appropriate error message in the response. Possible invalid requests include:
- Request size too large
- Invalid JSON
- Missing Authorization Header
- Invalid Authorization Header

In case of Invalid Authorization Header error, verify if the source write key and the basic authentication header is valid.

Maximum allowed request size

RudderStack allows messages with a maximum size of 32 KB per call. The batch endpoint accepts a maximum call size of 4 MB per batch, and 32 KB per call. RudderStack responds with a 400 Bad Request error if these limits are exceeded.

Event ordering

To maintain event ordering while using the HTTP API, make sure to include sentAt and anonymousId as a header in every request.

Historical imports

RudderStack lets you import any historical data by simply adding the timestamp argument to any of your API calls. However, this can be done only for the destinations that accept historical time-stamped data, like Amplitude, Mixpanel, etc.

If you are tracking current events, leave out the timestamp field. RudderStack will automatically add the timestamps to the event requests.

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Questions? Contact us by email or on Slack