smartStructures API Reference

Base URLs

Environment	Base URL
Sandbox	https://api.dev.smartobjx.com/structures-demo
Production	Provided by your smartObjx account administrator

All endpoints require authentication headers.

Domain Model

Perspective

Entry point — a named view of an organizational hierarchy. Subscribers can have multiple Perspectives (e.g., Finance, Operations, HR), each showing organizations arranged differently. Think of it as "how does this department see the company?"

Organization

A building block of the hierarchy. Organizations are arranged in parent-child trees via drag-and-drop in the IDE or via the API. Each organization has a Name and OID.

Tree

The hierarchical arrangement of Organizations within a Perspective. Supports unlimited depth and different structures per client. One client might have 3 levels, another 7 — smartStructures handles both.

InheritanceStructure

Defines how properties and settings inherit through the organizational hierarchy. Integrates with smartRules and smartSettings to enable per-org overrides.

---

Endpoints

GET /perspectiveslist

List all Perspective names. Returns a simple JSON array of name strings.

Response

["Operations", "Finance", "Marketing", "SDLicensing", "smartSaaS"]

cURL example

curl -X GET "https://api.dev.smartobjx.com/structures-demo/perspectiveslist" \
  -H "Ocp-Apim-Subscription-Key: fd8efd80-f215-4c73-95f2-23841e98acbd" \
  -H "Ocp-Apim-POV-Key: 45ef2936-160e-47dc-bd17-3dc0060acec9"

---

GET /perspective/{oid}

Get a Perspective by its OID, including its full organizational hierarchy tree.

Parameters

Parameter	Type	Description
oid	path (GUID)	The OID of the Perspective

Response

Returns a Perspective object with its Tree containing the full hierarchy of Organizations.

{
  "Name": "Operations",
  "OID": "a1b2c3d4-...",
  "Tree": {
    "Units": [
      {
        "Name": "West Region",
        "OID": "e5f6a7b8-...",
        "Units": [
          { "Name": "Seattle Office", "OID": "..." },
          { "Name": "Portland Office", "OID": "..." }
        ]
      },
      {
        "Name": "East Region",
        "OID": "c9d0e1f2-...",
        "Units": [
          { "Name": "New York Office", "OID": "..." }
        ]
      }
    ]
  }
}

---

POST /perspective

Create or save a Perspective.

Request body

{
  "Name": "Operations"
}

Response

Returns the created/updated Perspective object with its OID and Tree.

cURL example

curl -X POST "https://api.dev.smartobjx.com/structures-demo/perspective" \
  -H "Ocp-Apim-Subscription-Key: fd8efd80-f215-4c73-95f2-23841e98acbd" \
  -H "Ocp-Apim-POV-Key: 45ef2936-160e-47dc-bd17-3dc0060acec9" \
  -H "Content-Type: application/json" \
  -d '{"Name": "Operations"}'

---

POST /organization

Create or save an Organization (a node in the hierarchy tree).

Request body

{
  "Name": "West Region"
}

Response

Returns the created/updated Organization object with its OID.

---

Building a Hierarchy

To build an organizational hierarchy:

1. Create a Perspective: POST /perspective with a name
2. Create Organizations: POST /organization for each node
3. Arrange the tree: Add Organizations to the Perspective's Tree using perspective.Tree.AddUnit(organization) and save
4. Nest organizations: Add child Organizations under parent Organizations to create depth

There is no limit on tree depth. Different clients can have different structures — one client might have 3 levels (Region → Office → Team), another might have 7 levels.

Multiple Perspectives

The same set of organizations can appear in different perspectives with different arrangements. For example:

• Operations perspective: Region → Office → Team
• Finance perspective: Business Unit → Cost Center → Department
• HR perspective: Division → Department → Role

This means Finance can see the company organized by cost centers while Operations sees the same company organized by regions — without duplicating data.

Use Cases

• Multi-level org charts with departments, teams, and roles
• Client hierarchies where each client has different depth
• Multiple perspective views (Finance vs. Operations vs. HR)
• Integration with smartRules for per-org rule overrides
• Integration with smartSettings for per-org configuration
• Franchise or dealership network structures

Integration Code

JavaScript

const headers = {
  'Content-Type': 'application/json',
  'Ocp-Apim-Subscription-Key': 'your-subscription-key',
  'Ocp-Apim-POV-Key': 'your-pov-key'
};

// List all Perspective names
const perspectives = await fetch('https://your-structures-api/perspectiveslist', {
  method: 'GET', headers
}).then(r => r.json());
// Returns: ["Operations", "Finance", "Marketing", ...]

// Get a perspective with its full hierarchy
const perspective = await fetch(
  `https://your-structures-api/perspective/${perspectiveOid}`, {
  method: 'GET', headers
}).then(r => r.json());

// Create a new perspective
const newPerspective = await fetch('https://your-structures-api/perspective', {
  method: 'POST', headers,
  body: JSON.stringify({ Name: 'Operations' })
}).then(r => r.json());

C# with smartConnectors

// NuGet: Install SmartObjx.Connectors
var config = new ApiConfiguration();
config.BasePath = "https://your-structures-api-url";
config.ApiKey.Add("Ocp-Apim-POV-Key", "your-pov-key");
config.ApiKey.Add("Ocp-Apim-Subscription-Key", "your-subscription-key");

StructuresApi apiInstance = new StructuresApi(config);

// List all perspective names
// GET /perspectiveslist returns ["Operations", "Finance", ...]

// Get a perspective with its hierarchy
Perspective perspective = apiInstance.FindPerspectiveWith(perspectiveOID);

// Create a new perspective
Perspective newPerspective = new Perspective("Operations");
perspective = apiInstance.SavePerspective(newPerspective);

// Create and add organizations to the hierarchy
Organization newOrg = new Organization("West Region");
Organization org = apiInstance.SaveOrganization(newOrg);
newPerspective.Tree.AddUnit(newOrg);
apiInstance.SavePerspective(newPerspective);

Browser IDE

smartStructures includes a browser-based IDE for managing hierarchies visually with drag-and-drop. Try the sandbox IDE at structures-demo.smartobjx.com.

Related

• Authentication — required headers for all API calls
• smartConnectors SDK — NuGet and npm packages
• smartStructures product page