---
title: "Create a location"
method: POST
path: "/v1/org-nodes"
tags: ["org-nodes"]
---

# Create a location

`POST /v1/org-nodes`

## Request

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

Creates a new location under a parent location. Provide `name`, `parentId`, and an optional `kind`. To create many locations at once, use the bulk-create operation instead.

## Request body

- object
  - `name` string, required: Location name.
  - `parentId` string: Parent location; omit to place it directly under the workspace root.
  - `externalId` string: Your own location code; must be unique in the workspace.
  - `timezone` string: IANA zone, e.g. `Europe/London`.
  - `approval` ApprovalPolicy: 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.
  - `isSpace` boolean: Owner-only: create a child workspace (franchise).
  - `billingOwnerNodeId` string: With `isSpace`: the ancestor workspace that pays.
  - `screenLimit` integer: Owner-only, advisory.
  - `tier` integer: Owner-only. Defaults to 2.
  - `billing` unknown
  - `featureOverrides` unknown
  - `paysForItself` boolean: The location pays for its own screens and stays on the hold card until it adds a card. Defaults to the account setting `newLocationsPayFirst`. Choosing against that default needs `billing.edit` at the workspace root. Brix billing only (409 otherwise).

## Response `201`

Success.

- object
  - `data` Location, required: A location in the workspace tree (an org node).
    - `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

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `403`: An owner-only field was set (`isSpace`, `billing`, `featureOverrides`, `tier`, `screenLimit`, or a non-inheriting approval policy).
- `409`: `location_id_taken`: another location already uses this `externalId`.
- `422`: `name` missing, invalid `externalId`, or `parentId` not found.
- `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)