Documentation

Brand-wide: Integration guide

A brand-wide account connects a franchisor (managing) company to one or more franchisee (reporting) companies. Each franchisee has its own separate Ops Execution company, with its own teams, users, locations, and API token.

When to Use Brandwide

Use a brandwide integration when your client is a franchise organization where:

  • The franchisor needs operational visibility across all franchise locations.
  • Individual franchisees manage their own staff, locations, and hierarchy data.
  • Each franchise operates as a legally distinct business entity.

Recommended Phases

Phase 1: Corporate Hierarchy

The corporate hierarchy is built using the same process as a standard Ops Execution integration. Create teams, user roles, users, and locations under the parent company's API token.

  1. Create corporate user roles - Save role IDs. These IDs are reused in Phase 2 — do not recreate roles for franchisee accounts.
  2. Create corporate teams - Save team IDs.
  3. Create corporate users - Assign to correct team IDs. Save user IDs.
  4. Create corporate locations - Assign the location user as owner and the correct team ID. Save location IDs.
⚠️

Location Owner Fields are for Location Users Only

The owners field on the Locations endpoint and the owned_locations field on the Users endpoint are exclusively for Location-role users (store accounts). These fields exist only to pair a single store account with the specific location it represents.


Managers, admins, and supervisors automatically inherit oversight of the teams, users, and locations at or below their team level through the hierarchy — this is a separate system behavior that does not involve these fields. It is completely normal and expected for non-Location-role users to have no data in these fields.


A common and impactful mistake: assigning managers, supervisors, or anyone above the store level as a location owner causes significant operational problems. Each location should have exactly one location user assigned as its owner, and each location user should be paired with exactly one location.

Use these endpoints with the franchisor's API token to create franchisee companies and look them up. After a franchisee company is created, use that franchisee's API token for every call that builds its hierarchy (teams, users, locations).


Phase 2: Franchisee Hierarchy

For each franchisee, follow these steps. Each franchisee gets its own company account and API token. You must use that franchisee's token — not the parent's — for all API calls within that franchisee account.

  1. Create Franchisee Company with the parent company's API token to provision a new franchisee company account. Save the new company's owner user ID and API token.
  2. Create teams with the franchisee's API token from the previous step. Save every team ID from the response. These IDs are scoped to this franchisee account only.
  3. Create users with the franchisee's API token. Assign each user to the correct team for that account.
    1. User roles for franchise companies use the same role IDs from the corporate hierarchy — you do not create new roles for each franchise. Save every user ID from the response. These IDs will be used to assign location ownership in Step 4.
  4. Create locations - Assign an external_key, the location owner, and the correct team. The external_key links the Ops Execution location record back to your source-of-truth system and is essential for reconciliation and updates over time.
⚠️

Location and Location Owner Must Be on the Same Team

A location and its owner user must always belong to the same team. If they are on different teams, tasks assigned via projects may go unassigned silently — with no error to indicate the failure. Whenever a location moves to a new team, its owner user must be moved to the same team in the same operation.

⚠️

Location Owner Fields Are for Location Users Only

The owners field on the Locations endpoint and the owned_locations field on the Users endpoint are exclusively for Location-role users (store accounts). These fields exist only to pair a single store account with the specific location it represents.


Managers, admins, and supervisors automatically inherit oversight of the teams, users, and locations at or below their team level through the hierarchy — this is a separate system behavior that does not involve these fields. It is completely normal and expected for non-Location-role users to have no data in these fields.


A common and impactful mistake: assigning managers, supervisors, or anyone above the store level as a location owner causes significant operational problems. Each location should have exactly one location user assigned as its owner, and each location user should be paired with exactly one location.


Updating the Hierarchy

How you update a brandwide hierarchy depends on whether the franchisor maintains accurate hierarchy data for each of its franchisees.

Phase 1: Updating the Corporate Hierarchy

When a user or location moves to a new team, PATCH both the user and the location to the same new team.

⚠️

Important

Always patch both the user and the location together when either one moves. If the location and its owner user end up on different teams, task assignments via projects may fail silently.

Phase 2: Updating Franchisee Hierarchies


When Hierarchy Data Is Available
If the franchisor provides accurate, up-to-date hierarchy data for each franchisee, use it to keep team assignments synchronized:

When Hierarchy Data Is Not Available

Some franchisors do not maintain accurate hierarchy data for each of their franchisees. In this scenario, do not attempt to move locations, since there is no reliable data to determine where a location should be.

Instead, treat the location as the source of truth:

  • Do not move locations based on external data.
  • Ensure the location owner is always on the same team as the location.
  • Run a recurring validation script to detect and correct any drift between location and owner teams.
ℹ️

Why Teams Get Out of Sync

A common cause of drift is a franchisee company admin moving a location in the Ops Execution UI without realizing they also need to move the location owner user to the same team. When this happens, the location and its owner are on different teams, and project-assigned tasks may go unassigned silently. A routine validation script catches this before it becomes an operational problem.

Location / Location Owner Sync Validation

For brandwide integrations — especially those where franchisees can move resources in the UI — implement a recurring validation script that checks for sync drift between locations and their owners.

The validation script should:

  • Pull all location and user data from each franchisee company using List Locations and List Users with the franchisee's token.
  • For each location, compare the location's team ID against its owner user's team ID.
  • If the team IDs differ, patch the owner user to the location's team using the PATCH endpoint.

Updated 16 days ago