> ## Documentation Index
> Fetch the complete documentation index at: https://docs.northbeam.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Upsert one or multiple hourly spend records

> Create or update hourly spend records. Same matching behavior as the daily endpoint, at hourly granularity. Batches of up to 1000 per call.

<div className="nb-api-tables nb-field-table">
  ## Headers

  | Header | Description |
  | :- | :- |
  | `Authorization` <span className="nb-req">required</span> | Your Northbeam API key |
  | `Data-Client-ID` <span className="nb-req">required</span> | Your Northbeam client ID |
  | `Content-Type` <span className="nb-req">required</span> | `application/json` |

  ## Body

  <div className="nb-table-wrap"><table className="nb-main-table"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr className="nb-has-children"><td><code>data</code> <span className="nb-req">required</span></td><td>object\[]</td><td /></tr><tr className="nb-children-row"><td /><td /><td colSpan={1}><div className="nb-toggle nb-children"><label><input type="checkbox" /><span>Show child attributes</span></label><div className="nb-toggle-body"><div className="nb-child-table"><div className="nb-ct-head"><div>Field</div><div>Type</div><div>Description</div><div>Example</div></div><div className="nb-ct-row"><div><code>hour\_start\_iso</code> <span className="nb-req">required</span></div><div>string (date-time)</div><div>The date-time of spend entry to upsert in UTC, required</div><div><code className="nb-ex">"1970-01-01T00:00:00-0000"</code></div></div><div className="nb-ct-row"><div><code>platform\_account\_id</code></div><div>string</div><div>The Ad Platform Account ID to upsert, used for segregating ad objects per ad platform account<br />Default: <code>""</code></div><div><code className="nb-ex">"12345"</code></div></div><div className="nb-ct-row"><div><code>platform\_name</code> <span className="nb-req">required</span></div><div>string</div><div>The Ad Platform Name to upsert, required</div><div><code className="nb-ex">"Facebook"</code></div></div><div className="nb-ct-row"><div><code>campaign\_id</code> <span className="nb-req">required</span></div><div>string</div><div>The Ad Platform's Campaign ID (utm\_campaign, if known) to upsert, required</div><div><code className="nb-ex">"12345"</code></div></div><div className="nb-ct-row"><div><code>campaign\_name</code> <span className="nb-req">required</span></div><div>string</div><div>The Ad Platform Campaign Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as <code>campaign\_id</code></div><div><code className="nb-ex">"Banana Festival Awareness Campaign"</code></div></div><div className="nb-ct-row"><div><code>adset\_id</code></div><div>string</div><div>The Ad Platform's Adset ID (utm\_term, if known) to upsert, defaults to '' if empty (not all platforms support adsets)<br />Default: <code>""</code></div><div><code className="nb-ex">"12345"</code></div></div><div className="nb-ct-row"><div><code>adset\_name</code></div><div>string</div><div>The Ad Platform Adset Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as <code>adset\_id</code> - defaults to '' if empty<br />Default: <code>""</code></div><div><code className="nb-ex">"Banana Adset"</code></div></div><div className="nb-ct-row"><div><code>ad\_id</code></div><div>string</div><div>The Ad Platform's Ad ID (utm\_content, if known) to upsert, defaults to '' if empty (not all platforms support ads)<br />Default: <code>""</code></div><div><code className="nb-ex">"12345"</code></div></div><div className="nb-ct-row"><div><code>ad\_name</code></div><div>string</div><div>The Ad Platform Ad Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as <code>adset\_id</code> - defaults to '' if empty<br />Default: <code>""</code></div><div><code className="nb-ex">"Banana Ad"</code></div></div><div className="nb-ct-row"><div><code>spend</code> <span className="nb-req">required</span></div><div>number</div><div>Amount (in currency) spent on ad object to upsert, defaults to 0 if empty<br />Required range: <code>x >= 0</code></div><div><code className="nb-ex">123.5</code></div></div><div className="nb-ct-row"><div><code>spend\_currency</code> <span className="nb-req">required</span></div><div>string</div><div>The Currency of the Spend per ISO 4217 to upsert, required<br />Required string length: <code>3 - 3</code></div><div><code className="nb-ex">"USD"</code></div></div><div className="nb-ct-row"><div><code>impressions</code></div><div>number</div><div>The amount of impressions the ad object received on a given date, defaults to 0 if empty<br />Required range: <code>x >= 0</code><br />Default: <code>0</code></div><div><code className="nb-ex">299</code></div></div><div className="nb-ct-row"><div><code>clicks</code></div><div>number</div><div>The amount of clicks the ad object received on a given date, defaults to 0 if empty<br />Required range: <code>x >= 0</code><br />Default: <code>0</code></div><div><code className="nb-ex">0</code></div></div></div></div></div></td></tr></tbody></table></div>

  ## Responses

  | Status | Description |
  | :- | :- |
  | `201` | The hourly spend records were successfully upserted. |
  | `401` | Authentication failed. |
  | `422` | The request body is invalid. |
  | `4XX` | An unexpected error occurred. |
  | `5XX` | An unexpected error occurred. |

  ### `201` response body

  <div className="nb-table-wrap"><table className="nb-main-table"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr className="nb-has-children"><td><code>data</code> <span className="nb-req">required</span></td><td>object\[]</td><td /></tr><tr className="nb-children-row"><td /><td /><td colSpan={1}><div className="nb-toggle nb-children"><label><input type="checkbox" /><span>Show child attributes</span></label><div className="nb-toggle-body"><div className="nb-child-table"><div className="nb-ct-head"><div>Field</div><div>Type</div><div>Description</div><div>Example</div></div><div className="nb-ct-row"><div><code>hour\_start\_iso</code> <span className="nb-req">required</span></div><div>string (date-time)</div><div>The date-time of spend entry to upsert in UTC, required</div><div><code className="nb-ex">"1970-01-01T00:00:00-0000"</code></div></div><div className="nb-ct-row"><div><code>platform\_account\_id</code></div><div>string</div><div>The Ad Platform Account ID to upsert, used for segregating ad objects per ad platform account<br />Default: <code>""</code></div><div><code className="nb-ex">"12345"</code></div></div><div className="nb-ct-row"><div><code>platform\_name</code> <span className="nb-req">required</span></div><div>string</div><div>The Ad Platform Name to upsert, required</div><div><code className="nb-ex">"Facebook"</code></div></div><div className="nb-ct-row"><div><code>campaign\_id</code> <span className="nb-req">required</span></div><div>string</div><div>The Ad Platform's Campaign ID (utm\_campaign, if known) to upsert, required</div><div><code className="nb-ex">"12345"</code></div></div><div className="nb-ct-row"><div><code>campaign\_name</code> <span className="nb-req">required</span></div><div>string</div><div>The Ad Platform Campaign Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as <code>campaign\_id</code></div><div><code className="nb-ex">"Banana Festival Awareness Campaign"</code></div></div><div className="nb-ct-row"><div><code>adset\_id</code></div><div>string</div><div>The Ad Platform's Adset ID (utm\_term, if known) to upsert, defaults to '' if empty (not all platforms support adsets)<br />Default: <code>""</code></div><div><code className="nb-ex">"12345"</code></div></div><div className="nb-ct-row"><div><code>adset\_name</code></div><div>string</div><div>The Ad Platform Adset Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as <code>adset\_id</code> - defaults to '' if empty<br />Default: <code>""</code></div><div><code className="nb-ex">"Banana Adset"</code></div></div><div className="nb-ct-row"><div><code>ad\_id</code></div><div>string</div><div>The Ad Platform's Ad ID (utm\_content, if known) to upsert, defaults to '' if empty (not all platforms support ads)<br />Default: <code>""</code></div><div><code className="nb-ex">"12345"</code></div></div><div className="nb-ct-row"><div><code>ad\_name</code></div><div>string</div><div>The Ad Platform Ad Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as <code>adset\_id</code> - defaults to '' if empty<br />Default: <code>""</code></div><div><code className="nb-ex">"Banana Ad"</code></div></div><div className="nb-ct-row"><div><code>spend</code> <span className="nb-req">required</span></div><div>number</div><div>Amount (in currency) spent on ad object to upsert, defaults to 0 if empty<br />Required range: <code>x >= 0</code></div><div><code className="nb-ex">123.5</code></div></div><div className="nb-ct-row"><div><code>spend\_currency</code> <span className="nb-req">required</span></div><div>string</div><div>The Currency of the Spend per ISO 4217 to upsert, required<br />Required string length: <code>3 - 3</code></div><div><code className="nb-ex">"USD"</code></div></div><div className="nb-ct-row"><div><code>impressions</code></div><div>number</div><div>The amount of impressions the ad object received on a given date, defaults to 0 if empty<br />Required range: <code>x >= 0</code><br />Default: <code>0</code></div><div><code className="nb-ex">299</code></div></div><div className="nb-ct-row"><div><code>clicks</code></div><div>number</div><div>The amount of clicks the ad object received on a given date, defaults to 0 if empty<br />Required range: <code>x >= 0</code><br />Default: <code>0</code></div><div><code className="nb-ex">0</code></div></div><div className="nb-ct-row"><div><code>created\_at</code> <span className="nb-req">required</span></div><div>string (date-time)</div><div /><div /></div><div className="nb-ct-row"><div><code>updated\_at</code> <span className="nb-req">required</span></div><div>string (date-time)</div><div /><div /></div></div></div></div></td></tr></tbody></table></div>

  ### `401` response body

  <div className="nb-table-wrap"><table className="nb-main-table"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>errors</code></td><td>object\[], nullable</td><td /></tr><tr><td><code>message</code> <span className="nb-req">required</span></td><td>string</td><td /></tr><tr><td><code>request\_id</code></td><td>string (uuid), nullable</td><td /></tr></tbody></table></div>

  ### `422` response body

  <div className="nb-table-wrap"><table className="nb-main-table"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>errors</code></td><td>object\[], nullable</td><td /></tr><tr><td><code>message</code> <span className="nb-req">required</span></td><td>string</td><td /></tr><tr><td><code>request\_id</code></td><td>string (uuid), nullable</td><td /></tr></tbody></table></div>

  ### `4XX` response body

  <div className="nb-table-wrap"><table className="nb-main-table"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>errors</code></td><td>object\[], nullable</td><td /></tr><tr><td><code>message</code> <span className="nb-req">required</span></td><td>string</td><td /></tr><tr><td><code>request\_id</code></td><td>string (uuid), nullable</td><td /></tr></tbody></table></div>

  ### `5XX` response body

  <div className="nb-table-wrap"><table className="nb-main-table"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>errors</code></td><td>object\[], nullable</td><td /></tr><tr><td><code>message</code> <span className="nb-req">required</span></td><td>string</td><td /></tr><tr><td><code>request\_id</code></td><td>string (uuid), nullable</td><td /></tr></tbody></table></div>
</div>


## OpenAPI

````yaml openapi/spend-v1.json POST /spend_hourly
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)
security:
  - api_key: []
    client_id: []
tags: []
paths:
  /spend_hourly:
    post:
      summary: Upsert hourly spend records
      description: >-
        Create or update hourly spend records. Same matching behavior as the
        daily endpoint, at hourly granularity. Batches of up to 1000 per call.
      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
components:
  schemas:
    SpendHourlyUpsertInputPayload:
      properties:
        data:
          items:
            $ref: '#/components/schemas/SpendHourlyUpsertInput'
          type: array
          title: Data
      type: object
      required:
        - data
      title: Spend Entries
    SpendHourlyDefaultOutputPayload:
      properties:
        data:
          items:
            $ref: '#/components/schemas/SpendHourlyDefaultOutput'
          type: array
          title: Data
      type: object
      required:
        - data
      title: Spend Entries Return
    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
    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
    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
    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
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
    client_id:
      type: apiKey
      name: Data-Client-ID
      in: header

````