Northbeam API
★ Only Publicly Available OpenAPI DocumentAnalyticsProduct AnalyticsapiKey6 EndpointsREST
For 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.
Use for: Upsert yesterday's TikTok ad spend into Northbeam, Push hourly Meta spend records for the last 24 hours, List the daily spend records Northbeam has for our account this week, Delete a corrected Google Ads spend record from Northbeam
Not supported: Does not handle attribution model results, dashboarding, or order ingestion - use for ad-spend record upsert and deletion only.
Jentic publishes the only available OpenAPI specification for Northbeam API, keeping it validated and agent-ready. 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.
Install Jentic One Beta
Connect the Northbeam API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Northbeam API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fnorthbeam.io%2Fnorthbeam" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fnorthbeam.io%2Fnorthbeam" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Northbeam API.
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
Patterns agents use Northbeam API for, with concrete tasks.
★ 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.
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.
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.
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.
Through Jentic, search 'upsert ad spend records', load POST /spend, and execute with the weekly spend records
Key Endpoints
6 endpoints — jentic publishes the only available openapi specification for northbeam api, keeping it validated and agent-ready.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Northbeam API through Jentic.
Why is there no official OpenAPI spec for Northbeam API?
Northbeam does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Northbeam API via structured tooling. It is validated against the live API and kept up to date. 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.
GET STARTED