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

# Northbeam - Integration Instructions

> Export Northbeam measurement into Cloud Storage, then load it into BigQuery. Self-serve on a dedicated project; request setup on a shared one.

<Note>Raw data only. Northbeam lands as warehouse tables. It is not modeled in dashboards or Uni yet, and it does not replace the Northbeam app.</Note>

Northbeam is a measurement platform. SourceMedium lands Northbeam data through **Google Cloud Storage**: Northbeam writes export files into a GCS bucket, then those files are loaded into BigQuery.

Northbeam's own guidance for BigQuery is the same shape: export to a GCS bucket, then load from GCS into BigQuery. See [Which export should I use?](https://docs.northbeam.io/docs/exporting-data) (FAQ: "How can I get Northbeam data into BigQuery?").

This is a GCS destination, not an ad-account OAuth connect. Creating Data Export API jobs uses a Northbeam API key. Granting the bucket does not.

**Who can self-serve:** **Pro**, which delivers a dedicated Google Cloud project you administer. On **Foundation**, the shared project, you cannot grant bucket access, so use **Request integration** in Connect and SourceMedium picks it up. See [Foundation and Pro](/docs/data-activation/managed-data-warehouse/overview#foundation-and-pro).

## Vendor documentation

| What                                                             | Northbeam / Google doc                                                                                       |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Which export to pick                                             | [Which export should I use?](https://docs.northbeam.io/docs/exporting-data)                                  |
| Data Export API (pipeline): reports, auth, destinations, polling | [Data Exports](https://docs.northbeam.io/docs/northbeam-api-data-exports-overview)                           |
| Grant Northbeam write access on your GCS bucket                  | [Exporting to GCS](https://docs.northbeam.io/docs/northbeam-api-data-export-gcs-export-1)                    |
| Sales Attribution report                                         | [Sales Attribution Export](https://docs.northbeam.io/docs/northbeam-api-data-export-1)                       |
| Orders report                                                    | [Orders Export](https://docs.northbeam.io/docs/northbeam-api-orders-export)                                  |
| Dashboard Table Values → GCS                                     | [Sales page export](https://docs.northbeam.io/docs/sales-page-export#export-to-google-cloud-storage)         |
| API key and client ID                                            | [Authentication](https://docs.northbeam.io/docs/authentication)                                              |
| Load GCS files into BigQuery                                     | [Loading CSV data from Cloud Storage](https://cloud.google.com/bigquery/docs/loading-data-cloud-storage-csv) |

SourceMedium's warehouse path is **GCS**, then load to BigQuery. We do not use Northbeam's S3 destination or MCP server for this connector.

## Foundation: request integration

Foundation delivers a shared project, so you do not have project-level Cloud Storage or BigQuery access and cannot grant Northbeam's exporter on a bucket yourself.

1. In SourceMedium, open **Connect a data source** and find **Northbeam**.
2. Click **Request integration**.
3. SourceMedium is notified. The card shows **Setting up** until the team completes it.

Do not email a separate thread unless we ask.

## Pro: self-serve export, then load into BigQuery

Pro delivers a dedicated Google Cloud project you administer. You create a bucket, grant Northbeam, point the export at it, then load the CSVs into BigQuery. Connect shows the project ID.

### What you need

* An active Northbeam account
* Access to your dedicated GCP project (Connect shows the project ID)
* For Data Export API jobs: a Northbeam API key and Data-Client-ID ([Authentication](https://docs.northbeam.io/docs/authentication))

### 1. Create a bucket and grant Northbeam

<Steps>
  <Step title="Create a GCS bucket in your dedicated project">
    In Google Cloud Storage, create a bucket in the same project as your BigQuery datasets. Use a name you will pass to Northbeam (for example `your-brand-northbeam-export`).
  </Step>

  <Step title="Grant Northbeam write access">
    In the bucket IAM, add `nb-data-export@north-beam-io.iam.gserviceaccount.com` with **Storage Object Admin**. This is the address Northbeam documents for both the [Data Export API GCS destination](https://docs.northbeam.io/docs/northbeam-api-data-export-gcs-export-1) and the [Sales page GCS export](https://docs.northbeam.io/docs/sales-page-export#export-to-google-cloud-storage).
  </Step>

  <Step title="Point Northbeam at the bucket">
    **Pipeline (typical):** use the [Data Export API](https://docs.northbeam.io/docs/northbeam-api-data-exports-overview). Pass `bucket_name` on the create request for [Sales Attribution](https://docs.northbeam.io/docs/northbeam-api-data-export-1) and/or [Orders](https://docs.northbeam.io/docs/northbeam-api-orders-export). Poll `GET /v1/exports/data-export/result/{export_id}` until `status` is `SUCCESS`. Files are CSV. A `200 OK` on create does not mean the file is ready.

    **Dashboard:** on the [Sales page](https://dashboard.northbeam.io/sales), **Export → Table Values → Google Cloud Storage**, enter the bucket, click **Validate**. Chart Values cannot go to GCS.
  </Step>
</Steps>

### 2. Hook GCS into BigQuery

Northbeam does not write BigQuery tables. After files land in GCS, load them with Google's [Cloud Storage CSV load](https://cloud.google.com/bigquery/docs/loading-data-cloud-storage-csv).

<Steps>
  <Step title="Confirm files arrived">
    In Cloud Storage, open the bucket and confirm a CSV (or a prefix of CSVs) from the Northbeam export. Note the URI, for example `gs://your-brand-northbeam-export/*.csv`.
  </Step>

  <Step title="Create a dataset (once)">
    In BigQuery, create a dataset for this source (for example `northbeam_export`) in your dedicated project.
  </Step>

  <Step title="Load the CSV into a table">
    In BigQuery: **Create table** → source **Google Cloud Storage** → paste the `gs://` URI → file format **CSV**. Use autodetect for a first load, or supply a schema once you know the columns. Google's [load guide](https://cloud.google.com/bigquery/docs/loading-data-cloud-storage-csv) covers options (skip header rows, quoted newlines, hive partitioning).

    From the `bq` CLI:

    ```bash theme={null}
    bq load --source_format=CSV --autodetect --skip_leading_rows=1 \
      PROJECT:northbeam_export.sales_attribution \
      gs://your-brand-northbeam-export/*.csv
    ```
  </Step>

  <Step title="Schedule the load if the export is recurring">
    A one-off load is enough to confirm the path. For a scheduled Northbeam export, add a matching BigQuery load (scheduled query that runs `LOAD DATA`, or [Cloud Storage transfers](https://cloud.google.com/bigquery/docs/dts-introduction)). SourceMedium can confirm tables are arriving once the first load succeeds.
  </Step>

  <Step title="Confirm in SourceMedium">
    Click **Connect** on Northbeam in SourceMedium so we can mark the source as in setup.
  </Step>
</Steps>

## What data syncs

Depends on the report:

| Report            | What it contains                                                                                                           |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Sales Attribution | Performance metrics (attributed revenue, transactions, CAC, and related) by attribution model, window, and accounting mode |
| Orders            | One row per order, with product information                                                                                |

Grain and columns follow the export you create. First release is those files loaded as warehouse tables.

### Notes

* Northbeam stores exports in its own GCS by default. This connector uses an **external bucket** in your dedicated project.
* Format today is CSV. Result download links expire; re-fetch the result if a link dies.
* Attribution model, window, and accounting mode change the numbers. Set them on the export to match how you read Northbeam in the product.
* First release is tables you query, not a dashboard replacement.