Attribution Documentation
Docs

Importing historical data

Load events and identities from before your install through the HTTP API

❗️

Imported data cannot be deleted!

Once you import data, it cannot be deleted. We recommend that you set up a new project for testing prior to importing your data into production. You can set up a new project on paid plans by clicking on your avatar on the top right of the Dashboard and clicking the "New Project" button.

It is important to note, importing is only useful when capturing events that were missed before Attribution was installed. Once Attribution is properly installed importing will be completely unnecessary.

What an import can and cannot do

Attribution sorts traffic into ad channels by the tracking parameters it adds to your ad platforms once they are connected, and it creates the filters for your campaigns with their spend. None of that applies to data from before the connection, so imported visits land in the default sources unless you create filters for their UTM parameters yourself and enter the spend by hand. For that reason:

  • Import the last 90 days at most; older data rarely changes a model.
  • Expect to create filters and spend manually for the imported period, or accept that imported visits are not attributed to ad channels.
  • Visitor cookies and the links or UTM parameters behind a visit cannot be reconstructed after the fact; a visit is imported as the URL and referrer you send.

If your events already flow through Segment, its replay does the same import; see the Segment page's historical data import notes.

How to import

For a one-off file of up to a few thousand rows, the Events CSV upload does this without code. For larger imports, send the data through the HTTP API: export or collect the data to be imported, then post it in batches from any server-side library to the endpoint for each kind of record.

Rules to keep in mind:

  1. Every page view or event needs anonymousId, userId or both; otherwise Attribution cannot tie it to a person. anonymousId is the cookie id the snippet generates; for data from before the install, userId is usually the only identifier you have.
  2. Page views go to the page endpoint, not as track events with a page-like name.
  3. Set timestamp in ISO 8601 to the time the event happened; without it the record is dated at import time.
  4. Give every page view and event a unique messageId, so a batch can be retried without creating duplicates.
  5. For page views, properties.url and properties.referrer are what Attribution reads to decide the traffic source: the UTM parameters in the URL and the referring domain. Without them a visit can only land in Direct.

Example page view:

{
  "type": "page",
  "anonymousId": "23adfd82-aa0f-8383-a756-24f2a7a4c895",
  "messageId": "2015-12-12-page-000001",
  "timestamp": "2015-12-12T19:11:01.249Z",
  "properties": {
    "url": "https://www.domain.com/collections/mens-bottoms-sweatpants",
    "referrer": "https://www.domain.com/cart"
  }
}

Example conversion event:

{
  "type": "track",
  "event": "Order Paid",
  "userId": "12345",
  "messageId": "order-88123",
  "timestamp": "2015-12-14T19:09:17.542Z",
  "properties": {
    "revenue": 59.99
  }
}

Example identify:

{
  "type": "identify",
  "userId": "12345",
  "anonymousId": "23adfd82-aa0f-8383-a756-24f2a7a4c895",
  "traits": {
    "email": "[email protected]",
    "name": "Jane Doe"
  }
}

Identify calls are not tied to a timestamp and can be sent anytime you want to create or update a record. Sending anonymousId together with userId is what binds the anonymous visits to the known user, so include it whenever the imported visits carried one.

Updated 2 minutes ago