HTTP API | RudderStack Docs

It is recommended to use 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.

RudderStack offers an easy-to-use HTTP API that you can use to send your events if you cannot use the SDKs.

The RudderStack HTTP API is fully Segment-compatible.

This document details various aspects of the HTTP API.

1. Prerequisites

The following prerequisites must be met to send events via the HTTP API:

The RudderStack HTTP server must be accessible from your HTTP client. Refer to the Data Plane Setup guide.
Set up a source and destination in RudderStack by following the steps from Adding a Source and Adding a Destination guides.
Import the Postman collection using using this URL and edit the variables source_write_key and data_plane_urlwith the source write key and the Data Plane URL.

If you are using RudderStack Cloud, set the Data Plane URL to https://hosted.rudderlabs.com.

2. Authorization

RudderStack uses Basic Authentication for authenticating all the HTTP requests.

All the 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:

The username is the source write key
The 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==

Use the Basic Authentication Header Generator to generate the HTTP header.

To send the events via the RudderStack HTTP API, the Content-Type header must be set to application/json.

3. 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. Some possible invalid requests include:
- Request size too large
- Invalid JSON
- Missing Authorization Header
- Invalid Authorization Header

In case of the Invalid Authorization Header error, verify if the source write key and the Basic Auth Header is valid.

4. 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 if these limits are exceeded.

5. Identify

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

Request Type: POST
Request Format:

<DATA_PLANE_URL>/v1/identify

5.1. Sample payload

"identify.json"

{
  "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"
}

5.2. 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

5.3. Accepted fields

Field	Type	Presence	Description
`anonymousId`	String	Optional	Sets the user ID for cases where there is no unique identifier for the user. Either `userId` or `anonymousId` is required.
`userId`	String	Required, if `anonymousId` is not present.	Unique identifier for a particular user in your database.
`context`	Object	Optional	Dictionary of information that provides context about a message. However, it is not directly related to the API call.
`integrations`	Object	Optional	A dictionary containing the destinations to be either enabled or disabled.
`timestamp`	DateTime	Optional	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`	Object	Optional	Dictionary of the traits associated with the user, such as `name`or `email`

6. Track

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

Request Type: POST
Request Format:

<DATA_PLANE_URL>/v1/track

6.1. Sample payload

"track.json"

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

6.2. 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

6.3. Accepted fields

Field	Type	Presence	Description
`anonymousId`	String	Optional	Sets the user ID for cases where there is no unique identifier for the user. Either `userId` or `anonymousId` is required.
`userId`	String	Required, if `anonymousId` is not present.	Unique identifier for a particular user in your database.
`context`	Object	Optional	Dictionary of information that provides context about a message. However, it is not directly related to the API call.
`event`	String	Required	Name of the event being performed by the user
`properties`	Object	Optional	Dictionary of the properties associated with a particular event.
`integrations`	Object	Optional	A dictionary containing the destinations to be either enabled or disabled.
`timestamp`	DateTime	Optional	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`

7. Page

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

Request Type: POST
Request Format:

<DATA_PLANE_URL>/v1/page

7.1. Sample payload

"page.json"

{
  "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"
}

7.2. 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

7.3. Accepted fields

Field	Type	Presence	Description
`anonymousId`	String	Optional	Sets the user ID for cases where there is no unique identifier for the user. Either `userId` or `anonymousId` is required.
`userId`	String	Required, if `anonymousId` is not present.	Unique identifier for a particular user in your database.
`context`	Object	Optional	Dictionary of information that provides context about a message. However, it is not directly related to the API call.
`integrations`	Object	Optional	A dictionary containing the destinations to be either enabled or disabled.
`name`	String	Required	Name of the page being viewed.
`properties`	Object	Optional	Dictionary of the properties associated with the page being viewed, such as `url` and `referrer`
`timestamp`	DateTime	Optional	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`

8. Screen

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

The screen call is the mobile equivalent of the page call.

Request Type: POST
Request Format:

<DATA_PLANE_URL>/v1/screen

8.1. Sample payload

"screen.json"

{
  "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"
}

8.2. 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

8.3. Accepted fields

Field	Type	Presence	Description
`anonymousId`	String	Optional	Sets the user ID for cases where there is no unique identifier for the user. Either `userId` or `anonymousId` is required.
`userId`	String	Required, if `anonymousId` is not present.	Unique identifier for a particular user in your database.
`context`	Object	Optional	Dictionary of information that provides context about a message. However, it is not directly related to the API call.
`integrations`	Object	Optional	A dictionary containing the destinations to be either enabled or disabled.
`name`	String	Required	Name of the screen being viewed.
`properties`	Object	Optional	Dictionary of the properties associated with the page being viewed, such as `url` and `referrer`
`timestamp`	DateTime	Optional	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`

9. 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.

Request Type: POST
Request Format:

<DATA_PLANE_URL>/v1/group

9.1. Sample payload

"group.json"

{
  "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"
}

9.2. 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

9.3. Accepted fields

Field	Type	Presence	Description
`anonymousId`	String	Optional	Sets the user ID for cases where there is no unique identifier for the user. Either `userId` or `anonymousId` is required.
`userId`	String	Required, if `anonymousId` is not present.	Unique identifier for a particular user in your database.
`context`	Object	Optional	Dictionary of information that provides context about a message. However, it is not directly related to the API call.
`integrations`	Object	Optional	A dictionary containing the destinations to be either enabled or disabled.
`groupId`	String	Required	Unique identifier of the group, as present in your database.
`traits`	Object	Optional	Dictionary of the properties or traits associated with the group, such as `email` or `name`.
`timestamp`	DateTime	Optional	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`

10. 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.

Request Type: POST
Request Format:

<DATA_PLANE_URL>/v1/alias

10.1. Sample payload

"alias.json"

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

10.2. 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

10.3. Accepted fields

Field	Type	Presence	Description
`userId`	String	Required, if `anonymousId` is not present.	Unique identifier for a particular user in your database.
`context`	Object	Optional	Dictionary of information that provides context about a message. However, it is not directly related to the API call.
`integrations`	Object	Optional	A dictionary containing the destinations to be either enabled or disabled.
`previousId`	String	Required	The previous unique identifier of the user.
`traits`	Object	Optional	Dictionary of the properties or traits associated with the group, such as `email` or `name`.
`timestamp`	DateTime	Optional	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`

11. Merge

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

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

For more information on using the merge API, refer to the Identity Resolution guide.

Request Type: POST
Request Format:

<DATA_PLANE_URL>/v1/merge

11.1 Sample Payload

"merge.json"

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

11.2 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

11.3 Accepted fields

Field	Type	Presence	Description
`userId`	String	Required, if `anonymousId` is not present.	The unique user identifier.
`anonymousId`	String	Required, if `userId` is not present.	The anonymous ID associated with a user or visitor.
`mergeProperties`	Object	Required	The user properties to be merged and connected to a given user profile.

12. 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.

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

Request Type: POST
Request Format:

<DATA_PLANE_URL>/v1/batch

12.1. Sample payload

"batch.json"

{
    "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"
        }

    ]
}

12.2. 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

12.3. Accepted fields

Field	Type	Presence	Description
`batch`	Array	Required	An array of `identify`, `track`, `page`, `group` and `screen` calls. Each call must have a `type` property and a valid method name.

13. 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.

Video Events

Contact us

For more information on the topics covered on this page, email us or start a conversation in our Slack community.