API Reference

REST over HTTPS, JSON in and out. All requests require a bearer API key and the Northbound-User-Id header identifying the end-user.

Getting started

Base URL: https://api.northbound.dev/v1
Auth: Authorization: Bearer <key>
Versioning: URI-versioned (/v1). Breaking changes ship as /v2.
Rate limits: 100 req/sec per key. 429 on excess.

Endpoints

GET/partners/accounts

List connected accounts

Returns all accounts the end-user has linked through your partner integration, normalized across Plaid and Flinks.

Request

curl https://api.northbound.dev/v1/partners/accounts \
  -H "Authorization: Bearer nb_live_••••" \
  -H "Northbound-User-Id: usr_8fA2…"

Response · 200 OK

{
  "data": [
    {
      "id": "acc_01H8…",
      "institution": { "id": "chase", "name": "Chase", "region": "US" },
      "provider": "plaid",
      "name": "Total Checking",
      "mask": "4421",
      "type": "depository",
      "subtype": "checking",
      "currency": "USD",
      "balance": { "current": 4820.55, "available": 4720.55 },
      "updated_at": "2026-06-30T12:14:08Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/partners/transactions

List normalized transactions

Paginated, cursor-based feed of transactions across all linked accounts. Amounts use sign convention: positive = inflow, negative = outflow.

Request

curl "https://api.northbound.dev/v1/partners/transactions?account_id=acc_01H8…&limit=50" \
  -H "Authorization: Bearer nb_live_••••" \
  -H "Northbound-User-Id: usr_8fA2…"

Response · 200 OK

{
  "data": [
    {
      "id": "txn_01H9…",
      "account_id": "acc_01H8…",
      "posted_at": "2026-06-29",
      "merchant_name": "Loblaws",
      "description": "LOBLAWS #1042 TORONTO ON",
      "category": "groceries",
      "amount": -82.41,
      "currency": "CAD",
      "pending": false
    }
  ],
  "has_more": true,
  "next_cursor": "eyJvZmZzZXQiOjUwfQ=="
}

DELETE/partners/accounts/:id

Revoke an account connection

Immediately stops serving data for this account. Use this to honor a user's revocation request — required for SOC2 and PIPA compliance.

Request

curl -X DELETE https://api.northbound.dev/v1/partners/accounts/acc_01H8… \
  -H "Authorization: Bearer nb_live_••••" \
  -H "Northbound-User-Id: usr_8fA2…"

Response · 200 OK

{
  "id": "acc_01H8…",
  "deleted": true,
  "revoked_at": "2026-06-30T12:15:22Z"
}

POST/link/tokens

Create a Link token

Returns a short-lived token your frontend uses to open the Northbound connection bridge. Region routing is handled server-side.

Request

curl -X POST https://api.northbound.dev/v1/link/tokens \
  -H "Authorization: Bearer nb_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_8fA2…",
    "region": "CA",
    "products": ["accounts", "transactions"]
  }'

Response · 200 OK

{
  "link_token": "link-sandbox-9c8a…",
  "expires_at": "2026-06-30T13:14:08Z",
  "provider": "flinks"
}

Webhooks

Northbound POSTs JSON to your configured webhook URL when data changes. Verify the Northbound-Signature HMAC header before processing.

Event types

transaction.updated — new or modified transactions
account.updated — balance or metadata change
connection.revoked — user disconnected an institution
connection.error — re-auth required

Example payload

{
  "id": "evt_01H9…",
  "type": "transaction.updated",
  "created_at": "2026-06-30T12:14:08Z",
  "data": {
    "account_id": "acc_01H8…",
    "transaction_ids": ["txn_01H9…", "txn_01H9…"],
    "change": "posted"
  }
}