API reference
API reference
The API reads a brand's attributed performance as CSV exports, and takes in orders, spend and matched views that MTA does not collect itself. Every request is for one brand.
Overview#
https://mta.growthdept.ai/api/v1The data export API is compatible with Northbeam's Data Export API: the same endpoints, request bodies, headers and file columns, so an existing client works once its base URL points here. Files are downloaded from the links in the export result; writing to your own GCS or S3 bucket is not offered, and hourly granularity is refused. Everything MTA adds is a new field, header, query parameter or path, so no existing response changes shape.
- Paths below are relative to the base URL. Request and response bodies are JSON; send
Content-Type: application/jsonwith a body. - Dates are business dates in the brand's time zone, written
YYYY-MM-DD. Times are ISO 8601. - Money in exports is in the brand's currency. Orders and spend you send may be in any currency the European Central Bank quotes; MTA converts them.
- No endpoint pages through results with a cursor. Files and pagination explains how large exports arrive.
Data export API#
Read the brand's attributed performance as CSV files. Exports are asynchronous: create one, poll its result until the status is SUCCESS, then download the files from the signed links in the result.
| Endpoint | Scope | What it does |
|---|---|---|
GET/exports/account | any valid key | Read the account |
GET/exports/attribution-models | export:read | List attribution models |
GET/exports/metrics | export:read | List metrics |
GET/exports/breakdowns | export:read | List breakdowns |
POST/exports/data-export | export:read | Create an export |
GET/exports/data-export/result/{id} | export:read | Get an export result |
GET/exports/data-export/download/{brandId}/{id}/{file} | none (signed link) | Download an export file |
Orders API#
For stores that are not on Shopify, or orders sent from your own backend.
| Endpoint | Scope | What it does |
|---|---|---|
POST/orders | orders:write | Send orders |
Spend API#
Daily spend for platforms MTA has no connector for.
| Endpoint | Scope | What it does |
|---|---|---|
POST/spend | spend:write | Send spend |
Matched views API#
Ad views a partner has matched to the orders they led to, for Clicks + Deterministic Views.
| Endpoint | Scope | What it does |
|---|---|---|
POST/views | views:write | Send matched views |
Authentication#
Every request sends the API key in Authorization and the brand id in Data-Client-ID. An owner or admin creates keys under Settings > API Keys and ticks each key's scopes: export:read, orders:write, spend:write and views:write. A key is shown once. Details, and the difference between 401 and 403, are on Authentication.
Errors and limits#
Every endpoint puts the reason for an error in detail. The orders, spend and views endpoints repeat it in error, their older field, and add issues for a body that is not valid. Each key may make 100 export requests a second and create 60 exports a minute; a refused request gets 429 with Retry-After. See Errors and Rate limits.
Webhooks#
MTA sends no webhooks to your systems today. To learn when an export is ready, poll its result; an export of up to 31 days has usually finished by the time the create request returns.
Questions about the API: support@growthdept.ai.