---
title: "Bulk-create locations"
method: POST
path: "/v1/org-nodes/bulk"
tags: ["org-nodes"]
---

# Bulk-create locations

`POST /v1/org-nodes/bulk`

## Request

- Base URL: `https://api.brixsignage.com`
- URL: `https://api.brixsignage.com/v1/org-nodes/bulk`
- Auth: HTTP bearer

Creates up to 200 locations in a single call, for example to paste in a full location list at fleet setup. Send `parentId` and either a list of `names` or a list of `units`, each with a name and an optional time zone, town, Location ID and parent Location ID, so one list can hold regions and the stores under them. Empty or repeated names, and Location IDs already in use, are skipped, so the same list can safely be submitted again. Requires the create-location permission at the parent location.

**Notes.**
- Idempotent: sending the same list again creates nothing new and lists every row in `skipped`.

## Request body

- object
  - `parentId` string, required: The location the new ones go under (unless a row names its own parent).
  - `names` string[]: Location names. Use this or `units`.
  - `paysForItself` boolean: Every new location pays for itself before it goes live. Defaults to the account setting `newLocationsPayFirst`; choosing against it needs `billing.edit` at the workspace root.
  - `units` object[]: One row per location (up to 200). Use this or `names`.
    - `name` string, required
    - `timezone` string, nullable: IANA zone.
    - `location` object, nullable: A town or city (with coordinates, or looked up from `label`).
      - `label` string, required
      - `lat` number
      - `lng` number
    - `externalId` string: Your own location code.
    - `parentExternalId` string: The location code of this row's parent: an earlier row, or an existing location.

## Response `201`

Success.

- object
  - `data` object, required
    - `created` Location[], required
      - `id` string, required: Location (org node) id.
      - `name` string, required
      - `parentId` string, nullable, required: Parent location; null for the workspace root.
      - `externalId` string, nullable, required: Your own location code (store number, region code). Unique in the workspace.
      - `timezone` string, nullable, required: IANA zone screens here inherit, e.g. `America/Chicago`.
      - `tier` integer, required: Depth: 1 = the workspace root.
      - `isSpace` boolean, required: True for a workspace (Space) boundary: the root, or a franchise child workspace.
      - `payment` 'awaiting' | 'live', nullable, required: A location that pays for itself: `awaiting` (its screens wait on the hold card for its card), `live` (its own payer pays). Null when the account pays.
      - `paymentTrial` 'card_added' | 'no_card', nullable, required: While the account is in its free trial the location plays like any trial location: `card_added` (its year starts when the trial ends) or `no_card` (it waits on the hold card from then). Null outside the trial.
      - `screenCount` integer, required: Screens placed directly at this location (not its children).
      - `members` object[], required: People granted a role at this location.
        - `userId` string, required
        - `userName` string, required
        - `roleId` string, required
        - `roleName` string, required
        - `roleColor` string, nullable, required
        - `source` string, nullable, required: `sso:<connectionId>` when an identity provider granted this; null when granted in Brix.
      - `featureOverrides` unknown, required
      - `approval` ApprovalPolicy, required: The location's content-approval policy, as stored. New locations inherit `{required:false, inheritFromParent:true, …}`.
        - `required` boolean
        - `inheritFromParent` boolean
        - `escalateUpTiers` boolean
        - `allowSharedExemptions` boolean
        - `approvers` string[]: User ids named as approvers.
      - `billing` unknown, required
      - `prefs` LocationPrefs, required: Inheritable per-location settings (nearest ancestor wins).
        - `location` object, nullable, required: Physical place screens here inherit (drives weather and other location-aware apps).
          - `label` string, required
          - `lat` number, required
          - `lng` number, required
        - `language` string, nullable, required: BCP 47 tag screens here inherit, e.g. `de-DE`.
        - `defaultContent` object, nullable, required: What screens here play when they have no content of their own.
          - `kind` 'playlist' | 'schedule' | 'layout' | 'creative' | 'app' | 'media' | 'signage', required
          - `id` string, required
    - `skipped` string[], required: Names skipped: empty, repeated, or already a location there (or a Location ID already in use).
    - `locationsSkipped` string[], required: Names created without a town or city, because the one given could not be found.

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `403`: You do not hold `org-unit.create` at the parent location.
- `422`: `parentId` missing or not found, no rows, more than 200 rows, an invalid Location ID or time zone, or a parent that is a separate workspace.
- `5XX`: Server error. The body carries a `requestId` to quote to support.

---

[API](https://skmtc.dev/brixsignage/apis/brix-api.md) · [All operations](https://skmtc.dev/brixsignage/apis/brix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/brixsignage/apis/brix-api/revisions/02fd3665dc7d?raw)