Skip to content
Synthreo Synthreo Builder Docs
synthreo.ai
Docs
Company Management API

Company Management API

Company Management API reference — manage companies, customers, and tenant relationships programmatically via the Synthreo REST API.

Overview

Section titled “Overview”

The Customer Management API enables programmatic management of customers (tenants) within the Synthreo platform. This API supports hierarchical customer structures, regional assignments, permission management, and billing configuration.

Base URL

Section titled “Base URL”
https://auth.synthreo.ai/tenant
```text
## Authentication


**Description**: All endpoints require authentication via JWT Bearer token.


**URL**: `POST /auth/token`


**Request Body**:


```json
{
  "email": "example@company.com",
  "password": "password",
  "customerId": 123
}
```text
**Field Descriptions**:


| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | string | Yes | Your email address |
| `password` | string | Yes | Your password |
| `customerId` | integer | No | The customer you want to generate a token for. If omitted, generates a token for your default customer. |


**Example Response**:


```json
{
    "token": "token here",
    "customerOptions": [
        {
            "customerId": 123,
            "displayName": "MyCompany",
            "roleName": "Admin",
            "isOwner": false
        }
    ]
}
```text
The value in Token is your JWT token.
The list of customers is the customers you have access to.


**Append the following to your header in all future calls**


```text
Authorization: Bearer your_jwt_token
```text
---


## Company Identity and Information


### Get Current Identity


**Description**: Returns information about the authenticated user's tenant identity and company permissions.


**URL**: `GET /tenant`


**Requirements**:


- Authentication required


**Example Request**:


```http
GET /tenant HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```text
**Example Response**:


```json
{
  "identity": {
    "customerId": 123,
    "userIdentityId": 456,
    "email": "admin@company.com"
  },
  "customer": {
    "id": 123,
    "name": "Acme Corporation",
    "regionId": 1,
    "canAddCustomers": true,
    "descendantsCanAdd": false,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
```text
### Get Company Details


**Description**: Retrieves detailed information about a specific company including its hierarchy position.


**URL**: `GET /tenant/{cid}`


**Requirements**:


- Authentication required


**Parameters**:


- `cid`: Company ID. If omitted, returns current company details.


**Example Request**:


```http
GET /tenant/123 HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```text
**Example Response**:


```json
{
  "customer": {
    "id": 123,
    "parentId": 100,
    "name": "2025 08 19 Release QA",
    "regionId": 1,
    "canAddCustomers": true,
    "descendantsCanAdd": false,
    "createdAt": "2024-01-15T10:30:00Z",
    "region": {
      "id": 1,
      "name": "EU",
      "description": "European region"
    }
  },
  "parent": {
    "id": 100,
    "name": "Synthreo Corporation",
    "regionId": 1
  },
  "ancestors": [
    {
      "id": 100,
      "name": "Synthreo Corporation",
      "regionId": 1,
      "level": 0
    }
  ]
}
```text
### Update Customer Details


**Description**: Updates basic customer information and permission settings.


**URL**: `PUT /tenant`


**Requirements**:


- Authentication required


**Request Body**:


```json
{
  "customerId": 123,
  "name": "Updated Company Name",
  "canAddCustomers": true,
  "descendantsCanAdd": false
}
```text
**Example Request**:


```http
PUT /tenant HTTP/1.1
Host: auth.synthreo.ai
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...


{
  "customerId": 123,
  "name": "Updated Company Name",
  "canAddCustomers": true,
  "descendantsCanAdd": false
}
```text
**Response**: `204 No Content` on success


---


## Company Hierarchy Management


### Get Company List


**Description**: Retrieves a list of companies in your accessible hierarchy.


**URL**: `GET /tenant/customers/{cid?}`


**Requirements**:


- Authentication required


**Parameters**:


- `cid` (optional): Company ID to get subsidiaries for. If omitted, uses current company.
- `self` (query string): Controls whether to include the specified company in results
  - Values: `"true"`, `"false"`, `"0"`, `"1"`, `"include"`, `"exclude"`
  - Default behavior excludes self unless specified


**Example Request**:


```http
GET /tenant/customers/123?self=include HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```text
**Example Response**:


```json
[
  {
    "id": 123,
    "parentId": 100,
    "name": "2025 08 19 Release QA",
    "regionId": 1,
    "canAddCustomers": true,
    "descendantsCanAdd": false,
    "path": "Synthreo Corporation/2025 08 19 Release QA",
    "level": 1,
    "createdAt": "2024-01-15T10:30:00Z"
  },
  {
    "id": 124,
    "parentId": 123,
    "name": "Aqaib Test 3",
    "regionId": 1,
    "canAddCustomers": false,
    "descendantsCanAdd": false,
    "path": "Synthreo Corporation/2025 08 19 Release QA/Aqaib Test 3",
    "level": 2,
    "createdAt": "2024-02-01T14:20:00Z"
  }
]
```text
### Create New Customer


**Description**: Creates a new customer with an initial owner account and application permissions.


**URL**: `POST /tenant/customer`


**Requirements**:


- Authentication required


**Request Body**:


```json
{
  "parentId": 123,
  "name": "New Subsidiary Company",
  "regionId": 1,
  "canAddCustomers": false,
  "descendantsCanAdd": false,
  "email": "admin@newcompany.com",
  "firstName": "John",
  "lastName": "Smith",
  "threo": true,
  "builder": true,
  "tenant": true
}
```text
**Field Descriptions**:


| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `parentId` | integer | No* | Parent customer ID (defaults to current customer if omitted) |
| `name` | string | Yes | Customer name |
| `regionId` | integer | Yes | Geographic region ID for the customer |
| `canAddCustomers` | boolean | No | Whether this customer can create subsidiary customers (default: false) |
| `descendantsCanAdd` | boolean | No | Whether subsidiary customers can create their own customers (default: false) |
| `email` | string | Yes | Email address for the customer's initial admin user |
| `firstName` | string | No | First name for the admin user |
| `lastName` | string | No | Last name for the admin user (defaults to customer name if omitted) |
| `threo` | boolean | No | Grant ThreoAI platform access (default: true) |
| `builder` | boolean | No | Grant TheoBuilder access (default: true) |
| `tenant` | boolean | No | Grant Tenant Management access (default: true) |


**Example Request**:


```http
POST /tenant/customer HTTP/1.1
Host: auth.synthreo.ai
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...


{
  "parentId": 123,
  "name": "New Subsidiary Customer",
  "regionId": 1,
  "canAddCustomers": false,
  "descendantsCanAdd": false,
  "email": "admin@newcustomer.com",
  "firstName": "John",
  "lastName": "Smith",
  "threo": true,
  "builder": true,
  "tenant": true
}
```text
**Example Response**:


```json
{
  "id": 126,
  "parentId": 123,
  "name": "New Subsidiary Company",
  "regionId": 1,
  "canAddCustomers": false,
  "descendantsCanAdd": false,
  "createdAt": "2024-08-28T15:30:00Z"
}
```text
---


### [User Management](user-management-api-docs.md)


---


## Application Account Management


### Get Application Accounts


**Description**: Retrieves all application accounts and their permissions for a company.


**URL**: `GET /tenant/accounts/{cid?}`


**Requirements**:


- Authentication required


**Parameters**:


- `cid` (optional): Company ID. If omitted, returns accounts for current company.


**Example Request**:


```http
GET /tenant/accounts/123 HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```text
**Example Response**:


```json
[
    {
        "id": 456,
        "name": "Test Company",
        "customerId": 123,
        "appInstanceId": 2,
        "instanceAccountId": 123,
        "disabled": false,
        "createdAt": "2025-08-29T14:48:02.86269",
        "application": {
            "id": 3,
            "name": "Tenant management",
            "description": "Tenant Magament App",
            "appType": 3,
            "authUrl": "#/access/",
            "createdAt": "2025-04-17T10:31:12.557848"
        },
        "region": {
            "id": 2,
            "name": "East US 2",
            "description": "Central Synthreo location",
            "createdAt": "2025-04-17T10:31:12.557848"
        },
        "instanceActive": true,
        "domain": "https://admin.synthreo.ai",
        "permissions": [
            {
                "id": 567,
                "lastAccess": "2025-08-29T14:52:26.629169",
                "disabled": false,
                "createdAt": "2025-08-29T14:48:02.867946",
                "role": {
                    "id": 8,
                    "applicationId": 3,
                    "customerId": null,
                    "name": "Owner",
                    "description": "Account Owner",
                    "isOwner": true,
                    "features": "[\"account.close\", \"account.subscription.access\", \"account.membership.access\", \"descendant.account.login\"]",
                    "createdAt": "2025-04-17T10:31:12.557848"
                },
                "userIdentity": {
                    "id": 56,
                    "firstName": "Test",
                    "lastName": "Man",
                    "email": "Testman@synthreo.ai",
                    "createdAt": "2025-05-13T18:58:59.948026",
                    "name": "Test Man"
                }
            }
        ]
    }
]
```text
---


## Billing Information Management


### Get Billing Information


**Description**: Retrieves billing information for a customer.


**URL**: `GET /tenant/billing/{cid?}`


**Requirements**:


- Authentication required


**Parameters**:


- `cid` (optional): Customer ID. If omitted, returns billing info for current customer.


**Example Request**:


```http
GET /tenant/billing/123 HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```text
**Example Response**:


```json
{
  "customerId": 123,
  "billingName": "2025 08 19 Release QA",
  "businessId": "",
  "taxId": "",
  "createdAt": "0001-01-01T00:00:00",
  "locationId": 0,
  "addressLine1": "123 Business St",
  "addressLine2": "Suite 100",
  "city": "New York",
  "state": "NY",
  "zipCode": "10001",
  "countryCode": "US"
}
```text
### Update Billing Information


**Description**: Creates or updates billing information for a customer.


**URL**: `POST /tenant/billing/{cid?}`


**Requirements**:


- Authentication required


**Parameters**:


- `cid` (optional): Customer ID. If omitted, updates current customer billing.


**Request Body**:


```json
{
  "billingName": "Test Billing",
  "addressLine1": "123 Business St",
  "addressLine2": "Suite 100",
  "city": "New York",
  "state": "NY",
  "zipCode": "10001",
  "countryCode": "US"
}
```text
**Example Request**:


```http
POST /tenant/billing/123 HTTP/1.1
Host: auth.synthreo.ai
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...


{
  "billingName": "Test Billing",
  "addressLine1": "123 Business St",
  "addressLine2": "Suite 100",
  "city": "New York",
  "state": "NY",
  "zipCode": "10001",
  "countryCode": "US"
}
```text
**Response**: `204 No Content` on success


---


## Region Management


### Get Available Regions


**Description**: Retrieves complete list of all regions (requires root customer permissions).


**URL**: `GET /region`


**Requirements**:


- Authentication required


**Example Request**:


```http
GET /region/available HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```text
**Example Response**:


```json
[
  {
    "id": 1,
    "name": "EU",
    "description": "European region"
  },
  {
    "id": 2,
    "name": "East US 2",
    "description": "US East Coast region"
  },
  {
    "id": 3,
    "name": "EU West",
    "description": "EU West region"
  }
]
```text
### Get All Regions


**Description**: Retrieves regions where both TheoBuilder and ThreoAI applications are available for new customer creation.


**URL**: `GET /region/available`


**Requirements**:


- Authentication required


**Example Request**:


```http
GET /region HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```text
### Get Specific Region


**Description**: Retrieves details about a specific region by ID.


**URL**: `GET /region/{id}`


**Requirements**:


- Authentication required


**Parameters**:


- `id` (integer): Region ID


**Example Request**:


```http
GET /region/1 HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```text
**Example Response**:


```json
{
  "id": 1,
  "name": "US East",
  "description": "US East Coast region"
}
```text
---


### Permission Requirements


**Company Access Rules**:


- You can only access companies that are descendants of your authenticated company
- Parent companies have full access to subsidiary company data
- Permission changes are subject to parent company restrictions
- The `CanAddCustomers` permission is required to create new companies
- The `DescendantsCanAdd` setting controls whether subsidiaries can create their own companies


**Hierarchy Validation**:


- All company operations validate that the target company ID is a descendant of the authenticated user's company
- Permission inheritance flows down the hierarchy but is constrained by parent settings
- Root-level permissions are required for certain administrative operations


---


## Code Examples


### Create a New Customer (Python)


```python
import requests


def create_customer(parent_id, customer_name, region_id, owner_email, first_name=None, last_name=None):
    url = "https://auth.synthreo.ai/tenant/customer"


    headers = {
        "Authorization": f"Bearer {access_token}"
    }


    data = {
        "parentId": parent_id,
        "name": customer_name,
        "regionId": region_id,
        "canAddCustomers": False,
        "descendantsCanAdd": False,
        "email": owner_email,
        "firstName": first_name or "Admin",
        "lastName": last_name or "User",
        "threo": True,
        "builder": True,
        "tenant": True
    }


    response = requests.post(url, headers=headers, json=data)


    if not response.ok:
        raise Exception(f"HTTP error! status: {response.status_code}")


    return response.json()
```text
### Get Customer Hierarchy (Python)


```python
def get_customer_hierarchy(customer_id=None, include_self=False):
    url = "https://auth.synthreo.ai/tenant/customers"
    if customer_id:
        url += f"/{customer_id}"


    params = {}
    if include_self:
        params['self'] = 'include'


    headers = {
        "Authorization": f"Bearer {access_token}"
    }


    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()
```text
### Update Customer Settings (Python)


```python
def update_customer_settings(customer_id, name=None, can_add_customers=None, descendants_can_add=None):
    url = "https://auth.synthreo.ai/tenant"


    headers = {
        "Authorization": f"Bearer {access_token}"
    }


    data = {
        "customerId": customer_id
    }


    if name is not None:
        data["name"] = name
    if can_add_customers is not None:
        data["canAddCustomers"] = can_add_customers
    if descendants_can_add is not None:
        data["descendantsCanAdd"] = descendants_can_add


    response = requests.put(url, headers=headers, json=data)


    if response.status_code == 204:
        return True
    else:
        raise Exception(f"Failed to update customer: {response.status_code}")
```text
### Update Billing Information (Python)


```python
def update_billing_info(customer_id, billing_data):
    url = f"https://auth.synthreo.ai/tenant/billing/{customer_id}"


    headers = {
        "Authorization": f"Bearer {access_token}"
    }


    response = requests.post(url, headers=headers, json=billing_data)


    if response.status_code == 204:
        return True
    else:
        raise Exception(f"Failed to update billing info: {response.status_code}")


billing_info = {
    "billingName": "Test Billing",
    "addressLine1": "123 Business St",
    "addressLine2": "Suite 100",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "countryCode": "US"
}


update_billing_info(123, billing_info)
```text
---


## Authorization Notes


1. **Authentication**: All endpoints require a valid JWT token in the Authorization header
2. **Hierarchical Access Control**: Access is controlled through company hierarchy relationships
   - Users can only access their own company and its descendants
   - Parent companies have full access to subsidiary data
   - Subsidiaries cannot access parent company data
3. **Permission Inheritance**:
   - `CanAddCustomers` permission is inherited but can be restricted by parents
   - `DescendantsCanAdd` controls whether subsidiaries can create their own companies
   - Application permissions (Threo, Builder, Tenant) are granted per user per company
4. **Root Customer Access**: Some endpoints require special "root customer" permissions for system-wide administration


## Best Practices


### Error Handling


- Always check response status codes before processing response data
- Implement retry logic for 5xx server errors
- Handle 403 errors by checking user permissions in your application


### Performance Optimization


- Cache region data as it changes infrequently
- Use company ID parameters to avoid unnecessary hierarchy traversal
- Batch user operations when adding multiple users to the same company


### Security Considerations


- Store JWT tokens securely (never in localStorage in production)
- Implement token refresh logic for long-running applications
- Validate user permissions in your application before making API calls
- Log all company creation and modification operations for audit purposes
© 2025 Synthreo. All rights reserved.
Home

ThreoAI

Welcome to ThreoAI ThreoAI Overview Reset Your Password Creating Custom GPTs Submit a Bug Report

Builder

Welcome to Builder User Manual Builder Debugger IP Whitelisting

Tenant Management

Tenant Management Overview Tools / App Permission Roles Adding a New User Adding a New Customer Using System Prompts in ThreoAI How to Impersonate a User

API Reference

Company Management API User Management API ThreoAI API Management Cognitive Diagrams Management API

API Guides

Template Variables Best Practices Code Examples Error Handling

Advanced Topics

Advanced Template Variables SDKs and Libraries Webhooks