REST API for uploading daily and hourly spend records from ad platforms Northbeam does not integrate with natively, so those channels can be attributed. Rows are upserted on the platform/campaign/adset/ad natural key, which must match the customer's UTM tagging.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/spend-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.1.0
info:
title: API - Spend - V1
termsOfService: https://www.northbeam.io/terms
version: 1.0.0
servers:
- url: https://api.northbeam.io/v1
description: Production Endpoint
- url: https://api-uat.northbeam.io/v1
description: User Acceptance Testing (UAT), Production Equivalent (provided for Customer Testing ONLY, spend submitted here does not get used in attribution)
paths:
/spend:
get:
summary: List spend records
parameters:
- required: false
deprecated: false
style: form
explode: false
schema:
type: string
format: date
description: The date of spend entries to search for - provide this OR the Date Start/End ONLY
examples:
- '1970-01-01'
name: date
in: query
allowEmptyValue: false
allowReserved: false
- required: false
deprecated: false
style: form
explode: false
schema:
type: string
format: date
description: The date range of a spend entries to search for - provide this or and a end date OR a date ONLY
examples:
- '1970-01-01T00:00:00Z'
name: date_start
in: query
allowEmptyValue: false
allowReserved: false
- required: false
deprecated: false
style: form
explode: false
schema:
type: string
format: date
description: The date range of a spend entries to search for - provide this or and a start date OR a date ONLY
examples:
- '1970-01-01T00:00:00Z'
name: date_end
in: query
allowEmptyValue: false
allowReserved: false
- required: false
deprecated: false
style: form
explode: false
schema:
type: string
description: The Ad Platform Account ID to search for, required
examples:
- '12345'
name: platform_account_id
in: query
allowEmptyValue: false
allowReserved: false
- required: false
deprecated: false
style: form
explode: false
schema:
type: string
description: The Ad Platform's Campaign ID to search for
examples:
- '12345'
name: campaign_id
in: query
allowEmptyValue: false
allowReserved: false
- required: false
deprecated: false
style: form
explode: false
schema:
type: string
description: The Ad Platform's Adset ID to search for
examples:
- '12345'
name: adset_id
in: query
allowEmptyValue: false
allowReserved: false
- required: false
deprecated: false
style: form
explode: false
schema:
type: string
description: The Ad Platform's Ad ID to search for
examples:
- '12345'
name: ad_id
in: query
allowEmptyValue: false
allowReserved: false
- required: false
deprecated: false
style: form
explode: false
schema:
type: integer
minimum: 1
description: If Paginating - supply page number
default: 1
examples:
- 1
name: page
in: query
allowEmptyValue: false
allowReserved: false
- required: false
deprecated: false
style: form
explode: false
schema:
type: integer
description: Results per page - Maximum of 1000 results per page
default: 1000
examples:
- 1000
name: page_size
in: query
allowEmptyValue: false
allowReserved: false
responses:
'200':
description: List of spend records.
content:
application/json:
schema:
$ref: '#/components/schemas/SpendListOutputPayload'
'401':
description: Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'422':
description: The request body is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
4XX:
description: An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
5XX:
description: An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
deprecated: false
post:
summary: Upsert one or multiple spend records
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SpendUpsertInputPayload'
required: true
responses:
'201':
description: The spend records were successfully upserted.
content:
application/json:
schema:
$ref: '#/components/schemas/SpendDefaultOutputPayload'
'401':
description: Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'422':
description: The request body is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
4XX:
description: An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
5XX:
description: An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
deprecated: false
delete:
summary: Delete a spend record
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SpendDeleteInputPayload'
required: true
responses:
'200':
description: The spend record was successfully deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/SpendDefaultOutputPayload'
'401':
description: Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'422':
description: The request body is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
4XX:
description: An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
5XX:
description: An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
deprecated: false
/spend_hourly:
get:
summary: List spend records
parameters:
- required: false
deprecated: false
style: form
explode: false
schema:
type: string
format: date-time
description: The date range of a spend entries to search for - provide this or and a end date OR a date ONLY
examples:
- 1970-01-01T00:00:00-0000
name: hour_start_iso_begin
in: query
allowEmptyValue: false
allowReserved: false
- required: false
deprecated: false
style: form
explode: false
schema:
type: string
format: date-time
description: The date range of a spend entries to search for - provide this or and a start date OR a date ONLY
examples:
- 1970-01-01T01:00:00-0000
name: hour_start_iso_end
in: query
allowEmptyValue: false
allowReserved: false
- required: false
deprecated: false
style: form
explode: false
schema:
type: string
description: The Ad Platform Account ID to search for, required
examples:
- '12345'
name: platform_account_id
in: query
allowEmptyValue: false
allowReserved: false
- required: false
deprecated: false
style: form
explode: false
schema:
type: string
description: The Ad Platform's Campaign ID to search for
examples:
- '12345'
name: campaign_id
in: query
allowEmptyValue: false
allowReserved: false
- required: false
deprecated: false
style: form
explode: false
schema:
type: string
description: The Ad Platform's Adset ID to search for
examples:
- '12345'
name: adset_id
in: query
allowEmptyValue: false
allowReserved: false
- required: false
deprecated: false
style: form
explode: false
schema:
type: string
description: The Ad Platform's Ad ID to search for
examples:
- '12345'
name: ad_id
in: query
allowEmptyValue: false
allowReserved: false
- required: false
deprecated: false
style: form
explode: false
schema:
type: integer
minimum: 1
description: If Paginating - supply page number
default: 1
examples:
- 1
name: page
in: query
allowEmptyValue: false
allowReserved: false
- required: false
deprecated: false
style: form
explode: false
schema:
type: integer
description: Results per page - Maximum of 1000 results per page
default: 1000
examples:
- 1000
name: page_size
in: query
allowEmptyValue: false
allowReserved: false
responses:
'200':
description: List of spend records.
content:
application/json:
schema:
$ref: '#/components/schemas/SpendHourlyListOutputPayload'
'401':
description: Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'422':
description: The request body is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
4XX:
description: An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
5XX:
description: An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
deprecated: false
post:
summary: Upsert one or multiple hourly spend records
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SpendHourlyUpsertInputPayload'
required: true
responses:
'201':
description: The hourly spend records were successfully upserted.
content:
application/json:
schema:
$ref: '#/components/schemas/SpendHourlyDefaultOutputPayload'
'401':
description: Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'422':
description: The request body is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
4XX:
description: An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
5XX:
description: An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
deprecated: false
delete:
summary: Delete a spend record
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SpendHourlyDeleteInputPayload'
required: true
responses:
'200':
description: The spend record was successfully deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/SpendHourlyDefaultOutputPayload'
'401':
description: Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'422':
description: The request body is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
4XX:
description: An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
5XX:
description: An unexpected error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
deprecated: false
components:
schemas:
ErrorLoc:
properties:
loc:
type: string
title: Loc
msg:
type: string
title: Msg
type:
type: string
title: Type
type: object
required:
- loc
- msg
- type
title: ErrorLoc
RequestError:
properties:
errors:
anyOf:
- items:
$ref: '#/components/schemas/ErrorLoc'
type: array
- type: 'null'
title: Errors
message:
type: string
title: Message
request_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Request Id
type: object
required:
- message
title: RequestError
SpendDefaultOutput:
properties:
date:
type: string
format: date
title: Date
description: The date of spend entry to upsert, required
examples:
- '1970-01-01'
platform_account_id:
type: string
title: Platform Account Id
description: The Ad Platform Account ID to upsert, used for segregating ad objects per ad platform account
default: ''
examples:
- '12345'
platform_name:
type: string
title: Platform Name
description: The Ad Platform Name to upsert, required
examples:
- Facebook
campaign_id:
type: string
title: Campaign Id
description: The Ad Platform's Campaign ID (utm_campaign, if known) to upsert, required
examples:
- '12345'
campaign_name:
type: string
title: Campaign Name
description: The Ad Platform Campaign Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as `campaign_id`
examples:
- Banana Festival Awareness Campaign
adset_id:
type: string
title: Adset Id
description: The Ad Platform's Adset ID (utm_term, if known) to upsert, defaults to '' if empty (not all platforms support adsets)
default: ''
examples:
- '12345'
adset_name:
type: string
title: Adset Name
description: The Ad Platform Adset Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as `adset_id` - defaults to '' if empty
default: ''
examples:
- Banana Adset
ad_id:
type: string
title: Ad Id
description: The Ad Platform's Ad ID (utm_content, if known) to upsert, defaults to '' if empty (not all platforms support ads)
default: ''
examples:
- '12345'
ad_name:
type: string
title: Ad Name
description: The Ad Platform Ad Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as `adset_id` - defaults to '' if empty
default: ''
examples:
- Banana Ad
spend:
type: number
minimum: 0
title: Spend
description: Amount (in currency) spent on ad object to upsert, defaults to 0 if empty
examples:
- '123'
spend_currency:
type: string
maxLength: 3
minLength: 3
title: Spend Currency
description: The Currency of the Spend per ISO 4217 to upsert, required
examples:
- USD
- CAD
impressions:
type: number
minimum: 0
title: Impressions
description: The amount of impressions the ad object received on a given date, defaults to 0 if empty
default: 0
examples:
- 299
clicks:
type: number
minimum: 0
title: Clicks
description: The amount of clicks the ad object received on a given date, defaults to 0 if empty
default: 0
examples:
- 0
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
type: object
required:
- date
- platform_name
- campaign_id
- campaign_name
- spend
- spend_currency
- created_at
- updated_at
title: Spend Entry Return
SpendDefaultOutputPayload:
properties:
data:
items:
$ref: '#/components/schemas/SpendDefaultOutput'
type: array
title: Data
type: object
required:
- data
title: Spend Entries Return
SpendDeleteInput:
properties:
date:
type: string
format: date
title: Date
description: The date of spend entry to delete, required
examples:
- '1970-01-01'
platform_account_id:
type: string
title: Platform Account Id
description: The Ad Platform Account ID to delete, required
default: ''
examples:
- '12345'
campaign_id:
type: string
title: Campaign Id
description: The Ad Platform's Campaign ID to delete, required
examples:
- '12345'
adset_id:
type: string
title: Adset Id
description: The Ad Platform's Adset ID to delete, defaults to '' if empty
default: ''
examples:
- '12345'
ad_id:
type: string
title: Ad Id
description: The Ad Platform's Ad ID to delete, defaults to '' if empty
default: ''
examples:
- '12345'
type: object
required:
- date
- campaign_id
title: Deletion Parameters
SpendDeleteInputPayload:
properties:
data:
$ref: '#/components/schemas/SpendDeleteInput'
type: object
required:
- data
title: Deletion Parameters Object
SpendHourlyDefaultOutput:
properties:
hour_start_iso:
type: string
format: date-time
title: Hour Start Iso
description: The date-time of spend entry to upsert in UTC, required
examples:
- 1970-01-01T00:00:00-0000
platform_account_id:
type: string
title: Platform Account Id
description: The Ad Platform Account ID to upsert, used for segregating ad objects per ad platform account
default: ''
examples:
- '12345'
platform_name:
type: string
title: Platform Name
description: The Ad Platform Name to upsert, required
examples:
- Facebook
campaign_id:
type: string
title: Campaign Id
description: The Ad Platform's Campaign ID (utm_campaign, if known) to upsert, required
examples:
- '12345'
campaign_name:
type: string
title: Campaign Name
description: The Ad Platform Campaign Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as `campaign_id`
examples:
- Banana Festival Awareness Campaign
adset_id:
type: string
title: Adset Id
description: The Ad Platform's Adset ID (utm_term, if known) to upsert, defaults to '' if empty (not all platforms support adsets)
default: ''
examples:
- '12345'
adset_name:
type: string
title: Adset Name
description: The Ad Platform Adset Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as `adset_id` - defaults to '' if empty
default: ''
examples:
- Banana Adset
ad_id:
type: string
title: Ad Id
description: The Ad Platform's Ad ID (utm_content, if known) to upsert, defaults to '' if empty (not all platforms support ads)
default: ''
examples:
- '12345'
ad_name:
type: string
title: Ad Name
description: The Ad Platform Ad Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as `adset_id` - defaults to '' if empty
default: ''
examples:
- Banana Ad
spend:
type: number
minimum: 0
title: Spend
description: Amount (in currency) spent on ad object to upsert, defaults to 0 if empty
examples:
- 123.5
spend_currency:
type: string
maxLength: 3
minLength: 3
title: Spend Currency
description: The Currency of the Spend per ISO 4217 to upsert, required
examples:
- USD
- CAD
impressions:
type: number
minimum: 0
title: Impressions
description: The amount of impressions the ad object received on a given date, defaults to 0 if empty
default: 0
examples:
- 299
clicks:
type: number
minimum: 0
title: Clicks
description: The amount of clicks the ad object received on a given date, defaults to 0 if empty
default: 0
examples:
- 0
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
type: object
required:
- hour_start_iso
- platform_name
- campaign_id
- campaign_name
- spend
- spend_currency
- created_at
- updated_at
title: Spend Entry Return
SpendHourlyDefaultOutputPayload:
properties:
data:
items:
$ref: '#/components/schemas/SpendHourlyDefaultOutput'
type: array
title: Data
type: object
required:
- data
title: Spend Entries Return
SpendHourlyDeleteInput:
properties:
hour_start_iso:
type: string
format: date-time
title: Hour Start Iso
description: The date of spend entry to delete, required
examples:
- 1970-01-01T00:00:00-0000
platform_account_id:
type: string
title: Platform Account Id
description: The Ad Platform Account ID to delete, required
default: ''
examples:
- '12345'
campaign_id:
type: string
title: Campaign Id
description: The Ad Platform's Campaign ID to delete, required
examples:
- '12345'
adset_id:
type: string
title: Adset Id
description: The Ad Platform's Adset ID to delete, defaults to '' if empty
default: ''
examples:
- '12345'
ad_id:
type: string
title: Ad Id
description: The Ad Platform's Ad ID to delete, defaults to '' if empty
default: ''
examples:
- '12345'
type: object
required:
- hour_start_iso
- campaign_id
title: Spend Hourly Deletion Parameters
SpendHourlyDeleteInputPayload:
properties:
data:
$ref: '#/components/schemas/SpendHourlyDeleteInput'
type: object
required:
- data
title: Deletion Parameters Object
SpendHourlyListOutputPayload:
properties:
data:
items:
$ref: '#/components/schemas/SpendHourlyDefaultOutput'
type: array
title: Data
page:
type: integer
title: Page
page_size:
type: integer
title: Page Size
total_pages:
type: integer
title: Total Pages
total_count:
type: integer
title: Total Count
type: object
required:
- data
- page
- page_size
- total_pages
- total_count
title: Spend Entries Return Metadata
SpendHourlyUpsertInput:
properties:
hour_start_iso:
type: string
format: date-time
title: Hour Start Iso
description: The date-time of spend entry to upsert in UTC, required
examples:
- 1970-01-01T00:00:00-0000
platform_account_id:
type: string
title: Platform Account Id
description: The Ad Platform Account ID to upsert, used for segregating ad objects per ad platform account
default: ''
examples:
- '12345'
platform_name:
type: string
title: Platform Name
description: The Ad Platform Name to upsert, required
examples:
- Facebook
campaign_id:
type: string
title: Campaign Id
description: The Ad Platform's Campaign ID (utm_campaign, if known) to upsert, required
examples:
- '12345'
campaign_name:
type: string
title: Campaign Name
description: The Ad Platform Campaign Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as `campaign_id`
examples:
- Banana Festival Awareness Campaign
adset_id:
type: string
title: Adset Id
description: The Ad Platform's Adset ID (utm_term, if known) to upsert, defaults to '' if empty (not all platforms support adsets)
default: ''
examples:
- '12345'
adset_name:
type: string
title: Adset Name
description: The Ad Platform Adset Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as `adset_id` - defaults to '' if empty
default: ''
examples:
- Banana Adset
ad_id:
type: string
title: Ad Id
description: The Ad Platform's Ad ID (utm_content, if known) to upsert, defaults to '' if empty (not all platforms support ads)
default: ''
examples:
- '12345'
ad_name:
type: string
title: Ad Name
description: The Ad Platform Ad Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as `adset_id` - defaults to '' if empty
default: ''
examples:
- Banana Ad
spend:
type: number
minimum: 0
title: Spend
description: Amount (in currency) spent on ad object to upsert, defaults to 0 if empty
examples:
- 123.5
spend_currency:
type: string
maxLength: 3
minLength: 3
title: Spend Currency
description: The Currency of the Spend per ISO 4217 to upsert, required
examples:
- USD
- CAD
impressions:
type: number
minimum: 0
title: Impressions
description: The amount of impressions the ad object received on a given date, defaults to 0 if empty
default: 0
examples:
- 299
clicks:
type: number
minimum: 0
title: Clicks
description: The amount of clicks the ad object received on a given date, defaults to 0 if empty
default: 0
examples:
- 0
type: object
required:
- hour_start_iso
- platform_name
- campaign_id
- campaign_name
- spend
- spend_currency
title: Spend Hourly Entry
SpendHourlyUpsertInputPayload:
properties:
data:
items:
$ref: '#/components/schemas/SpendHourlyUpsertInput'
type: array
title: Data
type: object
required:
- data
title: Spend Entries
SpendListOutputPayload:
properties:
data:
items:
$ref: '#/components/schemas/SpendDefaultOutput'
type: array
title: Data
page:
type: integer
title: Page
page_size:
type: integer
title: Page Size
total_pages:
type: integer
title: Total Pages
total_count:
type: integer
title: Total Count
type: object
required:
- data
- page
- page_size
- total_pages
- total_count
title: Spend Entries Return Metadata
SpendUpsertInput:
properties:
date:
type: string
format: date
title: Date
description: The date of spend entry to upsert, required
examples:
- '1970-01-01'
platform_account_id:
type: string
title: Platform Account Id
description: The Ad Platform Account ID to upsert, used for segregating ad objects per ad platform account
default: ''
examples:
- '12345'
platform_name:
type: string
title: Platform Name
description: The Ad Platform Name to upsert, required
examples:
- Facebook
campaign_id:
type: string
title: Campaign Id
description: The Ad Platform's Campaign ID (utm_campaign, if known) to upsert, required
examples:
- '12345'
campaign_name:
type: string
title: Campaign Name
description: The Ad Platform Campaign Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as `campaign_id`
examples:
- Banana Festival Awareness Campaign
adset_id:
type: string
title: Adset Id
description: The Ad Platform's Adset ID (utm_term, if known) to upsert, defaults to '' if empty (not all platforms support adsets)
default: ''
examples:
- '12345'
adset_name:
type: string
title: Adset Name
description: The Ad Platform Adset Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as `adset_id` - defaults to '' if empty
default: ''
examples:
- Banana Adset
ad_id:
type: string
title: Ad Id
description: The Ad Platform's Ad ID (utm_content, if known) to upsert, defaults to '' if empty (not all platforms support ad
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/northbeam/refs/heads/main/openapi/northbeam-spend-v1-openapi.yml