---
title: "DataUpload"
description: "<p>APIs for collecting or uploading data.  There are two main APIs, one for uploading</p><p>Large files (bulk, millions of records) and another for sending real-time, or slightly batched</p><p>events (Less than 10MB).</p><p>**stream**</p><p>A stream name is like a table in database, each stream is a differnt _Type_ of data.</p><p>You assign a name to your data uploads to identify each stream/type.</p><p>However, it should be consistent across uploads of same type of data.</p><p>**Timestamp Fields**</p><p>When uploading historical, or event data you may have a time/date at which</p><p>an event occured.  Normal event uploads get an event timestamp at the server time</p><p>but you can over-ride this behavior so the timestamp is defined in the event you upload.</p><p>This is a _timestamp_field_ parameter in api's below.   The formatting for this is very, very</p><p>lenient with over 50 format's supported.</p>"
url: "https://www.contentstack.com/docs/developers/apis/lytics-api/v1/dataupload"
product: "Contentstack"
doc_type: "guide"
audience:
  - developers
  - admins
version: "current"
last_updated: "2026-11-05"
---

# DataUpload

APIs for collecting or uploading data. There are two main APIs, one for uploading

Large files (bulk, millions of records) and another for sending real-time, or slightly batched

events (Less than 10MB).

\*\*stream\*\*

A stream name is like a table in database, each stream is a differnt \_Type\_ of data.

You assign a name to your data uploads to identify each stream/type.

However, it should be consistent across uploads of same type of data.

\*\*Timestamp Fields\*\*

When uploading historical, or event data you may have a time/date at which

an event occured. Normal event uploads get an event timestamp at the server time

but you can over-ride this behavior so the timestamp is defined in the event you upload.

This is a \_timestamp\_field\_ parameter in api's below. The formatting for this is very, very

lenient with over 50 format's supported.

## BulkCSVUpload

### BulkCSVUpload

**POST** `/collect/bulk/{stream}`

Upload CSV files (may be gzipped). They MUST contain headers: either

in first row (by default) OR in \*\*headers\*\* querystring field.

If the file contains a timestamp field you want us to use

see \*\*timestamp\_field\*\* querystring parameter for how we extract it.

\*Note Domain\* this api is on a different domain \*https://bulk.lytics.io\* because the \*api.lytics.io\* domain

is limited to 10MB file uploads.

\`\`sh

\# the "user\_regdata" is the STREAM (ie Type) of data, if there

\# is multiple different types of data (userdata, emaildata, events)

\# they would have different streams.

\# user data

export LIODATAKEY="YOURKEY"

curl -s -H "Authorization: $LIOKEY" \\

\-H 'Content-type: application/csv' \\

\--data-binary @users.csv \\

"https://bulk.lytics.io/collect/bulk/user\_regdata?timestamp\_field=register\_date" \\

| jq '.'

\# only do a dry-run to see if it is formatted correctly

curl -s "https://bulk.lytics.io/collect/bulk/user\_regdata?access\_token=$LIODATAKEY&timestamp\_field=register\_date&dryrun=true" \\

\--data-binary @users.csv -H 'Content-type: application/csv' | jq '.'

\# append fields to each row

\# where append = urlencode({"source":"crm"})

\# often used when file-name contains information

curl -s "https://bulk.lytics.io/collect/bulk/user\_regdata?append=%7B%22source%22%3A%22crm%22%7D&access\_token=$LIODATAKEY" \\

\--data-binary @users.csv -H 'Content-type: application/csv' | jq '.'

\# full example uploading gzipped file

echo 'user\_id,email,reg\_date,item\_count

7456,email@email.com,"2012-10-17T17:29:39.738Z",82

1234,email2@email.com,"2012-12-11T19:53:31.547Z",82' > users.csv

gzip users.csv

curl -s "https://bulk.lytics.io/collect/bulk/user\_regdata?access\_token=$LIODATAKEY&timestamp\_field=reg\_date&dryrun=true&filename=users.csv" \\

\--data-binary @users.csv.gz \\

\-H 'Content-type: application/csv' | jq '.'

\`\`

#### URL Parameters

- **stream** (required)
  The DataType aka Table of type of data being uploaded. See Data, Streams in web admin.

#### Query Parameters

- **account_id** (optional)
  Your Lytics account ID.
- **access_token** (optional)
  The Lytics DATA API key. Not the management key. Or use Authorization Header.
- **dryrun** (optional)
- **timestamp_field** (optional)
  The name of the column or field in file that contains event timestamp.
- **headers** (optional)
  CSV only, Comma delimited list of header columns for csv (if not first row)
- **delimiter** (optional)
  CSV only, if not the default comma, either t=tab, or | may be accepted
- **append** (optional)
  CSV only, JSON encoded object of additional name-value pairs to append to each record.
- **droperrors** (optional)
- **filename** (optional)
  Just for record-keeping in our event - stream.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "status": 200,
  "message": "success",
  "data": {
    "message_count": 2,
    "rejected_count": 0,
    "content-type": "application/json",
    "droperrors": false,
    "dryrun": false,
    "timestamp_field": "event_created",
    "filename": "myfile.csv"
  }
}
```

## BulkJSONUpload

### BulkJSONUpload

**POST** `/collect/bulk/{streamname}`

JSON formatting info.

This JSON is ok:

\`\`json

{"order\_ids":\[1,2,3\]}

\`

This is not valid because it has objects nested inside arrays:

\`json

{"orders":\[{"id":1,"price":22},{"id":2,"price":23}\]}

\`\`

#### URL Parameters

- **streamname** (required)
  The DataType, or "Table" of type of data being uploaded

#### Query Parameters

- **account_id** (optional)
  Your Lytics account ID.
- **access_token** (optional)
  The Lytics DATA API key. Not the management key. Or use Authorization Header.
- **dryrun** (optional)
- **timestamp_field** (optional)
  The name of the column or field in file that contains event timestamp.
- **filename** (optional)
  Just for record-keeping in our event - stream.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "status": 200,
  "message": "success",
  "data": {
    "message_count": 2,
    "rejected_count": 0,
    "content-type": "application/json",
    "droperrors": false,
    "dryrun": false,
    "timestamp_field": "event_created",
    "filename": "myfile.json"
  }
}
```

## Data JSON Upload

### Data JSON Upload

**POST** `/collect/json/{stream}`

#### URL Parameters

- **stream** (required)
  The DataType, or "Table" of type of data being uploaded

#### Query Parameters

- **account_id** (optional)
  Your Lytics account ID.
- **access_token** (required)
  The Lytics DATA API key (not management key)
- **dryrun** (optional)
- **timestamp_field** (optional)
  The name of the column or field in file that contains event timestamp.
- **filename** (optional)
  Just for record-keeping in our event - stream.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "status": 200,
  "message": "success",
  "data": {
    "message_count": 2,
    "rejected_count": 0,
    "content-type": "application/json",
    "droperrors": false,
    "dryrun": false,
    "timestamp_field": "event_created",
    "filename": "myfile.json"
  }
}
```