canonical: https://jentic.com/apis/northbeam.io/northbeam

# Northbeam API

This page describes a curated, agent-optimized Jentic OpenAPI specification covering 6 Northbeam spend operations. Northbeam publishes its own OpenAPI documents inside its developer reference, embedded per operation page rather than offered as a single downloadable file, and its spend document covers the same operation set. The Jentic variant consolidates that surface into one validated document so an agent can load the whole operation set at once. Northbeam is a marketing attribution platform used by direct-to-consumer brands to model paid media spend against revenue across Meta, Google, TikTok, and other channels. The API focuses on spend ingestion at daily and hourly granularity, letting brands push ad-spend data from offline channels into Northbeam so the attribution model can blend it with directly-tracked spend. The endpoint set is small and focused: list, upsert, and delete spend records on /spend and /spend_hourly.

## For AI agents

Push, list, and delete daily and hourly ad-spend records to Northbeam so its attribution model can blend offline spend with tracked digital channels.

## Scope

Does not handle attribution model results, dashboarding, or order ingestion - use for ad-spend record upsert and deletion only.

## Capabilities

- Upsert one or many daily ad-spend records into Northbeam in a single call
- Upsert hourly ad-spend records for high-velocity channels that need finer granularity
- List existing spend records to verify ingestion before reporting
- Delete a daily spend record when a channel reports a correction
- Delete an hourly spend record when sub-day data is restated
- Authenticate with both the apiKeyAuth Authorization header and the Data-Client-ID header for multi-tenant access

## Use cases

### Offline media spend ingestion

DTC brands running TV, podcast, and out-of-home alongside paid digital need to feed offline spend into Northbeam so the attribution model can credit those channels. POST /spend accepts an array of records with channel, date, and amount, so an agent reading a media plan spreadsheet can push a month of OOH spend in a single batched call. This closes the blind spot where Northbeam undercredits offline channels because it never saw the spend.

Example prompt: POST /spend with an array of records for channel='OOH', date covering the last 7 days, and the per-day spend amount

### Hourly spend for fast-moving channels

Brands running aggressive TikTok or paid social cycles where spend swings sharply within a day push hourly spend via /spend_hourly so attribution can correlate hourly conversion lifts with the actual media flight. The agent runs a cron job pulling hourly spend from the channel's API and upserts to Northbeam every hour, keeping attribution within an hour of real-time.

Example prompt: Every hour, pull TikTok spend for the last hour and POST /spend_hourly to Northbeam with the channel and amount

### Spend reconciliation and corrections

When Meta or Google issues a billing correction days after the fact, the previously-pushed Northbeam record needs to be restated. DELETE /spend on the original record followed by a fresh POST /spend with the corrected amount keeps the attribution model accurate. An agent can detect a delta between the platform's bill and Northbeam's stored spend and apply the correction automatically.

Example prompt: Compare Meta billing for last week against Northbeam /spend listings and delete and re-post any record where the amount differs by more than 1%

### AI agent for media-mix maintenance

An AI agent that owns weekly media-mix maintenance can pull spend from each channel's reporting API, normalise the rows, and push to Northbeam through Jentic. The agent searches Jentic for 'upsert ad spend records', loads POST /spend, and executes - without holding the Northbeam API key or the Data-Client-ID in code.

Example prompt: Through Jentic, search 'upsert ad spend records', load POST /spend, and execute with the weekly spend records

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/spend` | List daily spend records |
| POST | `/spend` | Upsert one or many daily spend records |
| DELETE | `/spend` | Delete a daily spend record |
| GET | `/spend_hourly` | List hourly spend records |
| POST | `/spend_hourly` | Upsert hourly spend records |
| DELETE | `/spend_hourly` | Delete an hourly spend record |

## Key resources

- **Spend** — Daily-granularity ad-spend records: list, upsert, delete
- **Spend Hourly** — Hourly-granularity ad-spend records for fast-moving channels

## Why Jentic

- **Setup:** Wiring Northbeam by hand means sending both its Authorization API key and a Data-Client-ID header on every request to api.northbeam.io/v1 and managing that pair yourself across the spend endpoints. Through Jentic you install once, import the Northbeam API from the API Directory, store both values once, and your agent calls it.
- **Permission scoping:** Northbeam takes the spend records in the request body rather than a resource id in the URL path, so scope the agent to the operations it needs, such as reading and upserting spend. You choose that set, so a destructive DELETE /spend or DELETE /spend_hourly is not included unless you add it.
- **Credential handling:** Your Northbeam Authorization key and Data-Client-ID are stored once, encrypted, by your own Jentic One instance and injected at execution time as both headers. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'upsert ad spend records' or 'read hourly spend', and Jentic returns the matching Northbeam operation with its input schema so the agent posts to /spend without browsing the reference docs.

## Related APIs

- **Amplitude API** — Amplitude tracks product analytics events that complement Northbeam's marketing attribution.
- **Mixpanel API** — Mixpanel covers funnel and retention analytics that pair with Northbeam's spend view.
- **Segment API** — Segment routes event data into multiple analytics destinations including attribution tools.
- **Klaviyo API** — Klaviyo provides email and SMS revenue data that DTC brands run alongside Northbeam.

## FAQ

### Which OpenAPI specification does this Northbeam API page describe?

A curated, agent-optimized Jentic specification covering 6 Northbeam spend operations. Northbeam also publishes its own OpenAPI documents, embedded inside each developer reference page rather than offered as one downloadable file: its spend document is titled 'API - Spend - V1' at version 1.0.0 and appears on pages such as https://docs.northbeam.io/reference/post_spend.md, while the whole reference set is indexed at https://docs.northbeam.io/llms.txt. Because the vendor documents are sliced per operation page and split across separate surfaces for spend, orders, and data export, the Jentic variant bundles the six spend operations into one validated document an agent can load in a single step. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Northbeam API use?

Northbeam uses two API key headers: Authorization for the secret API key and Data-Client-ID for the tenant identifier. Both are required on every request. Through Jentic, both keys are held in the encrypted vault and presented by the runtime.

### Can I push hourly ad spend to Northbeam?

Yes. POST /spend_hourly accepts an array of hourly records, each with a timestamp, channel, and amount. Use this endpoint for channels like Meta and TikTok where same-day spend swings are large enough to matter for attribution; use /spend for daily channels.

### What are the rate limits for the Northbeam API?

Northbeam does not encode hard rate limits in the spec. The endpoints are designed for batch upsert, so prefer arrays of records over per-record calls. For hourly ingestion, run one upsert per hour per channel rather than per-row.

### How do I upload daily spend through Jentic?

Install with pip install jentic, then search 'upsert ad spend records', load POST /spend, and execute with an array of records. Each record includes the channel, date, and spend amount; Northbeam dedupes by channel + date so re-running a job replaces existing values.

### Does the Northbeam API expose attribution results or only spend ingestion?

This API surface focuses on spend ingestion only - list, upsert, and delete on /spend and /spend_hourly. Attribution reporting outputs are surfaced through Northbeam's UI and separate exports rather than this endpoint set.

### Can I limit what my agent is allowed to do with the Northbeam API?

Yes. Because Jentic One is self-hosted, you decide which Northbeam operations your agent can call, so you can allow it to list and upsert spend on /spend and /spend_hourly while withholding the destructive DELETE /spend and DELETE /spend_hourly operations. Since Northbeam takes spend records in the request body rather than a resource id in the URL, scoping is set at the operation level under your own rules. Your Authorization key and Data-Client-ID are held by your own instance and injected only when the agent runs an operation you have permitted.