Skip to main content

Data Exports

Every day, DialStack takes a snapshot of every account on your platform and publishes it as a data export: one download per object type, covering all your accounts at once. Load it into your warehouse and compare one day with the next to see what changed, for example 6 users at an account yesterday and 7 today.

An export is a record of what existed, taken from the same data the API serves. Use it to keep your own systems up to date and to explain changes between invoices. Your billing files remain what you are charged.

What an export holds​

Each day from 10:00 UTC, DialStack reads all your accounts at one instant and writes four files:

FileOne line per
accounts.jsonl.gzaccount
locations.jsonl.gzlocation of an account
phone_numbers.jsonl.gzphone number of an account
users.jsonl.gzuser of an account

All four come from the same snapshot, so they always agree with each other: every location, user and phone number belongs to an account in accounts.jsonl.gz.

Each file is gzipped JSON Lines: one JSON object per line. Each object is exactly what the matching list endpoint returns for it (GET /v1/accounts, GET /v1/locations, GET /v1/users and GET /v1/phone-numbers, without filters), so it parses with the same code. A location, user or phone number line also carries one field the API object doesn't have:

FieldTypeDescription
accountstringThe ID of the account the object belongs to.
Text
{"account":"acct_01h2xcejqtf2nbrexx3vqjhp41","id":"user_01h2xcejqtf2nbrexx3vqjhp4f","name":"Dana Whitfield","location":"loc_01h2xcejqtf2nbrexx3vqjhp4r", ...}

Like the unfiltered list, phone_numbers.jsonl.gz includes numbers that are not active, with their status. Something deleted before the snapshot is not in it.

A user's or phone number's location is the location set on it, or null when none is.

Live and sandbox​

Each day, your live accounts and your sandbox accounts are exported separately. Your live secret key lists the live exports and your sandbox secret key the sandbox ones, as with every other resource. Build and test your import against the sandbox exports, then switch to the live key.

Fetching exports​

Exports are read with your platform's secret key, and kept for seven days. Each day appears as a data_export:

Bash
curl "https://api.dialstack.ai/v1/data_exports" \
-H "Authorization: Bearer sk_live_..."
JSON
{
"object": "list",
"url": "/v1/data_exports",
"next_page_url": null,
"previous_page_url": null,
"data": [
{
"id": "dexp_01h2xcejqtf2nbrexx3vqjhp4k",
"object": "data_export",
"date": "2026-11-13",
"created_at": "2026-11-13T10:00:04Z",
"files": [
"file_01h2xcejqtf2nbrexx3vqjhp4m",
"file_01h2xcejqtf2nbrexx3vqjhp4n",
"file_01h2xcejqtf2nbrexx3vqjhp4p",
"file_01h2xcejqtf2nbrexx3vqjhp4q"
]
}
]
}

The list is newest day first. To download, retrieve the export with expand[]=files: each file then carries a filename and a signed url, valid for a few minutes, so download right after you ask.

Bash
curl -G "https://api.dialstack.ai/v1/data_exports/dexp_01h2xcejqtf2nbrexx3vqjhp4k" \
-d "expand[]=files" \
-H "Authorization: Bearer sk_live_..."

Knowing when a day is ready​

Either:

  • Subscribe to data_export.created, sent when a day's export is ready, and fetch it then.
  • Poll the list on a schedule, for example once a day after 12:00 UTC.

A webhook can be missed, so if you trigger your job from the event, also poll as a backstop. A day can't be exported after the fact: an export is a snapshot of that day, so download each one within its seven days and keep your own history.

Example: users per account and location​

With jq, count each account's users by location from a downloaded users.jsonl.gz:

Bash
gunzip -c users.jsonl.gz \
| jq -s 'group_by([.account, .location]) | map({account: .[0].account, location: .[0].location, users: length})'

Loading the files into a warehouse table gives the same answer with a GROUP BY account, location, and comparing two days' tables shows what was added and removed in between.