Operation Definitions

POST /v1/companies/{companyId}/sites

Summary

Use this endpoint create a new site with the option to copy from a base site. For the copy option:

If source_site_copy_id is provided, the API copies the selected entities from the source (base) site.
The copy_entities field controls which entities are copied. Send only what the destination site requires.

Disable automatic updates:

Set automatic_updates=false.
Provide apps[] with pinned preferred versions for each managed app, commonly XKS/XPOS.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The Bearer token
path	`companyid`	string	Yes	The company identifier (ID)
body	`body`	CreateSiteRequest	Yes	The request body information

Responses

Code	Description	Schema
200	Success Response Site created	SiteResponse
201	Success Response Site created	SiteResponse
403	Error Response Message: Permission denied	None
404	Error Response Message: Validation error	None
Default	Error Response Message: Unexpected Error	None

CreateSiteRequest

Field Name	Type	Required	Description
`name`	string	Yes	The site name
`store_number`	string	Yes	The store number
`type`	string	Yes	The business classification for the site. The practical default for normal restaurant stores: `Production`.
`environment`	string	Yes	The operational environment (runtime context). The practical default for normal restaurant stores: `Production`.
`business_type`	string	Yes	The business model classification. The practical default for normal restaurant stores: `QSR` or `TSR` for table-service.
`timezone`	string	Yes	The time zone for the site. For example, `US/Eastern`.
`preferred_language`	string	Yes	The preferred language for the site. For example, `en-US`.
`location`	Location object	Yes	The list of locations for the site
`phone_settings`	PhoneSettings object	No	The phone number information for the site
`automatic_updates`	boolean	No	A global automatic updates flag used by some payload variants. If `false`, include `apps[]` with pinned preferred versions for managed apps.
`apps`	AppPreference array	No*	*This field is required when `automatic_updates=false` to pin preferred versions, commonly XKS/XPOS
`subscriptions`	Subscriptions array	Yes	The subscription list for the site. At site level, `count` is typically `1`. Genius Gateway (`product=genius_transport`) required `external_data`: `environment` `merchant_name` `merchant_site_id` `merchant_key`
`source_site_copy_id`	string	No	The source site identifier (ID) used for copy behavior
`copy_entities`	array	No	Entities to copy from the source site. Use a minimal list. Large lists increase runtime and integration risk.
`website`	string	No	The site website
`email`	string	No	The site email address
`support_phone_option`	string	No	The site support phone option
`support_phone_settings`	PhoneSettings object	No	The support phone number information for the site
`edm_sync`	boolean	No
`identifiers`	Tax object	No	The federal and state/province tax IDs
`alternate_languages`	string	No	Alternate language information
`salesforce`	Salesforce object	No	Revenue and billings IDs
`metadata`	array	No
`copy_portal_entities`	string	No

Sample Request Body

{
  "name": "Site 3 (Copy)",
  "store_number": "4",
  "type": "Production",
  "environment": "Production",
  "business_type": "QSR",
  "timezone": "US/Eastern",
  "preferred_language": "en-US",
  "location": {
    "address_1": "4444",
    "address_2": "",
    "city": "444",
    "state": "AL",
    "zip": "44444",
    "country": "US"
  },
  "automatic_updates": false,
  "apps": [
    {
      "app_code": "XKS",
      "preferred_version": {
        "version": "4.0.444",
        "uri": "https://<official-host>/xks/4.0.444/"
      }
    },
    {
      "app_code": "XPOS",
      "preferred_version": {
        "version": "13131313131313",
        "uri": "https://pos-download.xenial.com/pos-app/13131313131313/"
      }
    }
  ],
  "subscriptions": [
    {
      "count": 1,
      "name": "Enterprise Kitchen",
      "product": "XKS",
      "is_active": true,
      "external_data": {
        "automatic_updates": false,
        "enable_encryption": false
      }
    },
    {
      "count": 1,
      "name": "Enterprise POS",
      "product": "XENIAL POS",
      "is_active": true,
      "external_data": {
        "automatic_updates": false
      }
    },
    {
      "count": 1,
      "name": "Genius Gateway",
      "product": "genius_transport",
      "is_active": true,
      "external_data": {
        "environment": "Production",
        "merchant_name": "merchant_name",
        "merchant_site_id": "merchant_site_id",
        "merchant_key": "merchant_key",
        "web_checkout_key": "web_checkout_key",
        "kount_fraud_detection": true,
        "applepay_merchant_id": "apple_merchant_id",
        "googlepay_merchant_id": "google_merchant_id"
      }
    }
  ],
  "source_site_copy_id": "{source_site_id}",
  "copy_entities": [
    "audio-file",
    "break-time",
    "bundle-component",
    "calendar",
    "configuration-group",
    "count-frequency",
    "country-state",
    "course",
    "currency-scheme",
    "custom-label-definition",
    "customer-survey",
    "date-range",
    "day-part",
    "day-part-type",
    "default-user",
    "discount-definition",
    "donation",
    "dynamic-matrix",
    "employee-status-change-reason",
    "employee-status-config",
    "event-type",
    "external-application",
    "fee-definition",
    "fixed-matrix",
    "floor-plan",
    "forecast-definition",
    "forecast-definition-mapping",
    "general-ledger-account",
    "gift-service",
    "history-definition",
    "house-account",
    "i9-document-class",
    "i9-status",
    "inventory-item-venue",
    "inventory-location",
    "job-change-reason",
    "job-code",
    "job-code-category",
    "job-code-rate",
    "labor-matrix",
    "load-balancing-rule",
    "main-variant-mix",
    "measure",
    "menu",
    "menu-category",
    "menu-item-group",
    "min-wage-config",
    "modifier-build",
    "modifier-collection",
    "modifier-group",
    "named-calculation",
    "notification-template",
    "online-ordering-settings",
    "order-destination",
    "order-lane",
    "order-screen",
    "order-source",
    "pay-type",
    "pay-type-scheme",
    "payroll-employee-status-mapping",
    "payroll-job-category-mapping",
    "payrule-group",
    "peripheral",
    "pos-job-code",
    "pos-pay-mapping",
    "pos-reason-code",
    "preferences",
    "product",
    "product-availability",
    "product-price",
    "punch-adjustment-reason",
    "receipt-message",
    "receipt-template",
    "report-options",
    "schedule-type",
    "service-point",
    "store-hours-config",
    "store-hours-config-group",
    "support-user",
    "tag-rule",
    "tare",
    "tax-definition",
    "tax-group",
    "tender-currency",
    "tender-mapping",
    "terminal",
    "terminal-scheme",
    "time-period",
    "tip-group",
    "validation-format",
    "variant-build",
    "vendor",
    "w4-filing-status",
    "web-meta-data",
    "workflow",
    "xks-bumpbar",
    "xks-display-definition",
    "xks-display-scheme",
    "xks-general-settings",
    "xks-station-config",
    "modifier"
  ]
}

Location

Field Name	Type	Required	Description
`address_1`	string	Yes	The site's street number and name
`address_2`	string	No	Additional site address information such as a suite number, if applicable
`city`	string	Yes	The site's city name
`state`	string	Yes	The site's state abbreviation
`zip`	string	Yes	The site's zip or postal code
`country`	string	Yes	The site's country abbreviation

PhoneSettings

Field Name	Type	Required	Description
`number`	string	No	The site phone number
`code`	string	No	The site area code
`country`	string	No	The site country code

AppPreference

Field Name	Type	Required	Description
`app_code`	string	Yes	The app code
`preferred_version`	AppRelease object	Yes	The preferred app version information

AppRelease

Field Name	Type	Required	Description
`version`	string	Yes	The app version
`uri`	string	Yes	The app uniform resource identifier (URI)

Subscriptions

Field Name	Type	Required	Description
`count`	integer	Yes	The number of subscriptions for the site
`name`	string	Yes	The subscription name
`product`	string	Yes	The subscription product information
`is_active`	boolean	Yes	A flag that indicates if the subscription is active currently
`external_data`	ExternalData object	No	Product-specific fields

ExternalData

Field Name	Type	Required	Description
`automatic_updates`	boolean	No	A flag that indicates if there are automatic updates for XKS/XPOS
`enable_encryption`	boolean	No	For XKS. This field is optional and defaults to `false`.
`environment`	string	Yes*	The product's environment. *This field is required for Genius Gateway if `product=genius_transport`. Value: `Production\|Custom`.
`merchant_name`	string	Yes*	The product's merchant name. *This field is required for Genius Gateway if `product=genius_transport`.
`merchant_site_id`	string	Yes*	The product's merchant site identifier (ID). *This field is required for Genius Gateway if `product=genius_transport`.
`merchant_key`	string	Yes*	The product's merchant key. *This field is required for Genius Gateway if `product=genius_transport`.

Tax

Field Name	Type	Required	Description
`federal_tax`	string	No	The federal tax identifier (ID)
`state_province_tax`	string	No	The state/province tax ID

Salesforce

Field Name	Type	Required	Description
`revenue_id`	string	No	The revenue identifier (ID) for Salesforce
`billing_id`	string	No	The billing ID for Salesforce

SiteResponse

This is a simplified response shape. The actual response may include additional fields

Field Name	Type	Description
`id`	string	The site identifier (ID)
`name`	string	The site name
`store_number`	string	The site store number
`company`	string	The site company name

Sample Response Body

{
  "id": "string",
  "name": "string",
  "store_number": "string",
  "company": "string"
}

GET /v1/apps

Summary

Get a list of available applications and releases. This operation is used when automatic updates are disabled to select preferred versions for XKS/XPOS.

Request Parameters

In	Field Name	Type	Required	Description
query	`current_release`	string	No	The recommended default query
query	`other_releases`	string	No	Use only when end-of-life is in the future and the uniform resource identifier (URI) is an official host
query	`include_inactive`	boolean	Yes	When the value is `true`, the response includes inactive apps in the results

Response

Code	Description	Schema
200	The app list	AppsResponse

AppsResponse

Field Name	Type	Description
`total`	integer	The total number of items in the response
`items`	AppItem object	The list of apps

Sample Response Body

{
  "total": 0,
  "items": [
    {
      "id": "string",
      "name": "string",
      "code": "string",
      "force_update": true,
      "current_release": {
        "version": "string",
        "uri": "string",
        "end_of_life": "2026-02-20T17:26:51.978Z"
      },
      "other_releases": [
        {
          "version": "string",
          "uri": "string",
          "end_of_life": "2026-02-20T17:26:51.978Z"
        }
      ]
    }
  ]
}

AppItem

Field Name	Type	Description
`id`	string	The app identifier (ID)
`name`	string	The app name
`code`	string	the app code
`force_update`	boolean
`current_releases`	AppReleaseWithEol object	The list of current releases
`other_releases`	AppReleaseWithEol object	The list of other releases

AppReleaseWithEol

Field Name	Type	Description
`version`	string	The app version information
`uri`	string	The app uniform resource identifier (URI)
`end_of_life`	string (date/time)	The app's end of life date and time

PATCH /v1/companies/{companyId}/site-hierarchies/{siteHierarchyId}

Summary

Use this endpoint to add or move a site assignment in a hierarchy. Key behavior for this endpoint:

Each level object must include id, name, sites, and children.
children: [] is schema-required and does not delete existing children.
Omitted nodes are not treated as removals.

Request Parameters

In	Field Name	Type	Required	Description
path	`companyid`	string	Yes	The company identifier (ID)
query	`siteHierarchyId`	string	Yes	The site hierarchy ID
query	`filter_by_assigned_sites`	boolean	No	A flag that indicates whether to filter by assigned sites. The default value is `true`.
body	`body`	PatchHierarchyRequest	Yes	The request body information

Response

Code	Description	Schema
200	Updated hierarchy	SiteHierarchiesResponse

PatchHierarchyRequest

Field Name	Type	Required	Description
`name`	string	Yes
`levels`	HierarchyLevel object	Yes	The hierarchy level information

Sample Request Body

{
  "name": "Hierarchy name",
  "levels": [
    {
      "id": "{levelId}",
      "name": "Level name",
      "sites": [
        {
          "id": "{newSiteId}",
          "name": "4 (Copy)"
        }
      ],
      "children": []
    }
  ]
}

HierarchyLevel

Field Name	Type	Required	Description
`id`	string	Yes	The hierarchy level identifier (ID)
`name`	string	Yes	The hierarchy level name
`sites`	HierarchySite object	Yes	The hierarchy sites information
`children`	array	Yes	Schema-required list of child levels. `[]` does not delete existing children.

HierarchySite

Field Name	Type	Required	Description
`id`	string	Yes	The hierarchy site identifier (ID)
`name`	string	Yes	The hierarchy site name
`order`	integer	No	The hierarchy site order

SiteHierarchiesResponse

Field Name	Type	Description
`total`	integer	The total number of returned items
`items`	SiteHierarchyItem object	The site hierarchy item information

Sample Response Body

{
  "id": "string",
  "name": "string",
  "company_id": "string",
  "assigned_sites": 0,
  "levels": [
    {
      "id": "string",
      "name": "string",
      "sites": [
        {
          "id": "string",
          "name": "string",
          "order": 0
        }
      ],
      "children": [
        "string"
      ]
    }
  ]
}

SiteHierarchyItem

Field Name	Type	Description
`id`	string	The site hierarchy item identifier (ID)
`name`	string	The site hierarchy item name
`company_id`	string	The company ID for the site hierarchy item
`assigned_sites`	integer	The number of assigned sites for the site hierarchy item
`levels`	HierarchyLevel object	The hierarchy level information

GET /v1/companies/{companyId}/site-hierarchies

Summary

Get a list of site hierarchies and level identifiers (IDs). This endpoint returns the hierarchy ID and nested level IDs used by PATCH /v1/companies/{companyId}/site-hierarchies/{siteHierarchyId}. Use this endpoint to discover:

items[].id as siteHierarchyId
items[].levels[].id as top-level levelId
items[].levels[].children[].id as nested child levelId

Request Parameters

In	Field Name	Type	Required	Description
path	`companyid`	string	Yes	The company identifier (ID)
query	`$top`	integer	No	The number of items to be returned. The default value is `10`.
query	`$skip`	integer	No	The number of items to be skipped. The default value is `0`.
query	`$filter`	string	No	A filter expression in OData v4 format
query	`$orderby`	string	No	An order by expression in OData v4 format
query	`no_mapping_hierarchy`	boolean	No	The default value is `false`
query	`filter_by_assigned_sites`	boolean	No	A flag that indicates whether to filter by assigned sites. The default value is `true`.

Response

Code	Description	Schema
200	Hierarchy list	SiteHierarchiesResponse

Operation Definitions

POST /v1/companies/{companyId}/sites

CreateSiteRequest

Location

PhoneSettings

AppPreference

AppRelease

Subscriptions

ExternalData

Tax

Salesforce

SiteResponse

GET /v1/apps

AppsResponse

AppItem

AppReleaseWithEol

PATCH /v1/companies/{companyId}/site-hierarchies/{siteHierarchyId}

PatchHierarchyRequest

HierarchyLevel

HierarchySite

SiteHierarchiesResponse

SiteHierarchyItem

GET /v1/companies/{companyId}/site-hierarchies

Search results