JSON Files as an External Data Source

ou can import .json files into Sandstorm to import data into your account. We’ll accept both one-time uploads and a recurring import of .json files from your Amazon S3 Bucket.

We recommend you read People, Events, and Properties and Common Methods before getting started here.

File Format

We accept files with the .json extension with this caveat: each line of the file must be a valid JSON object. For example:

Valid

JSON

{"_n":"visited site","_p":"[e-mail]","_t":1393344604}
{"url":"www.example.com/","_n":"visited","_p":"[e-mail]","_t":1393344607}
{"url":"www.example.com/","_n":"visited site","_p":"[e-mail]","_t":1393344609}
{"_p":"[e-mail]","_p2":"[e-mail]","_t":1393344614}

Invalid

JSON

{"links":
  [
    {"_n":"visited site","_p":"[e-mail]","_t":1393344604},
    {"url":"www.example.com/","_n":"visited","_p":"[e-mail]","_t":1393344607},
    {"_p":"[e-mail]","_p2":"[e-mail]","_t":1393344614},
  ]
}

JSON object requirements

Names will have the bold titles. These are the two required fields:

• “_p” (required): _p corresponds to a KM Identity. We will accept both new identities and identities already in our database.

• “_t” (required): A timestamp of when the event/property occurred. The time format is in seconds as a UTC Unix epoch. If you are using dates in Excel, you may need to convert those dates to Unix timestamps. See this answer on Stack Overflow. Be aware that Unix timestamps are calculated based on GMT, which may affect the way you convert times to Unix timestamps.

Then include at least one of these three names, depending on what type of data you’re importing:

• “_n” (optional): _n corresponds to the name of a KM Event. You can add an event name, such as Signed Up. It does not matter if you currently have data for this event, or if this is a completely new event.

• “_p2” (optional): _p2 corresponds to an Alias. In the rare case you are uploading aliases, you can add additional aliases to the KM identity.

• “any value” (optional): Any other Name:Value pairs will be treated as properties.

Examples

Importing only events (record command)

JSON

{"_p":"1", "_t":1328044149, "_n":"Subscribed"}

Importing events with optional properties (record command with properties)

JSON

{"_p":"1", "_t":1328044149, "_n":"Subscribed", "Age":32, "Gender":"Male"}

Importing only properties (set command)

JSON

{"_p":"1", "_t":1328044149, "Email Address":"[e-mail]"}

Importing optional aliases (alias command)

It’s uncommon to upload aliases, but this is the format if you absolutely need to:

JSON

{"_p":"1", "_t":1328044149, "_p2":"bob"}

Sample .json file

Here's a sample .json file for reference.