TBBN Connect — bulk location onboarding

If you run a franchise, a chain, or any Business with more locations than you want to add by hand through business.tbbnetwork.com, TBBN Connect is the bulk path: post your full location list in one call, and TBBN creates or updates each one automatically. Re-posting the same list later — on a schedule, from your own back-office system — updates existing locations instead of creating duplicates, as long as each row carries the same id it had the first time.

This is a bulk create-or-update endpoint, not a one-time import tool. Point your own system's own location export at it on whatever cadence makes sense for you (nightly, weekly, on every change) and TBBN stays in sync without anyone re-entering data by hand.

1. Post your locations

curl -X POST https://api.tbbnetwork.com/v1/businesses/<businessId>/branches/bulk \
  -H "Authorization: Bearer <your session token>" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [
      {
        "externalLocationId": "store-042",
        "name": "Downtown",
        "addressLine1": "1 Main St",
        "city": "Austin",
        "region": "TX",
        "postalCode": "78701",
        "country": "US",
        "amenities": ["wifi", "parking"]
      }
    ]
  }'

externalLocationId is required on every row — it's your own system's own identifier for that location, and it's what makes a re-post safe. TBBN looks up each row by (your Business, externalLocationId): a match updates that location in place, no match creates a new one. Up to 500 locations per request; if you have more, split into multiple calls — there's no downside to batching, since every row is independently safe to re-send.

The response reports what happened to each row:

{
  "results": [
    { "externalLocationId": "store-042", "action": "created", "branchId": "..." },
    { "externalLocationId": "store-043", "action": "updated", "branchId": "..." }
  ]
}

A row that fails (a malformed address, for example) is reported inline with an error field — the rest of the batch still processes. Retry just the failed rows once fixed.

2. Or upload a CSV, no API required

If your locations live in a spreadsheet rather than a system with an export, upload a CSV directly from your Business's Branches page in business.tbbnetwork.com — same idempotent behavior, same externalLocationId column, no code required. A template is available from that page.

Why not XML?

If you're coming from a hospitality or retail platform that speaks XML for this kind of feed, you'll notice TBBN Connect is JSON-only. That's deliberate: XML location feeds are a legacy convention some platforms still carry for backward compatibility with decades-old integrations. TBBN has no such install base to support, so there's no reason to ask you to generate XML when JSON is what every modern system already produces. If your own platform only exports XML, a small transform step ahead of this endpoint is the more maintainable path than TBBN adding and maintaining a second wire format.

Managing a multi-Business brand

If your locations are split across more than one legally separate Business (common in real franchising, where each location has its own ownership and its own payout account), TBBN Connect still applies per-Business — post each Business's locations to its own businessId. Franchise Groups (managed from business.tbbnetwork.com) let a brand owner invite each of those Businesses into one group for shared defaults and roll-up reporting, without merging their separate legal and financial identities. See your Business dashboard for details; this is a dashboard feature, not a separate API surface.