Company Management API

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

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

https://auth.synthreo.ai/tenant

Authentication

All endpoints require authentication via JWT Bearer token. Obtain a token by posting to the auth endpoint described below, then include it in all subsequent requests.

URL: POST https://auth.synthreo.ai/tenant/token

Request Body:

{
  "email": "example@company.com",
  "password": "password",
  "customerId": 123
}

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:

{
  "token": "token here",
  "customerOptions": [
    {
      "customerId": 123,
      "displayName": "MyCompany",
      "roleName": "Admin",
      "isOwner": false
    }
  ]
}

The value in token is your JWT token. The customerOptions array lists all customers your identity has access to.

Include the following header in all subsequent calls:

Authorization: Bearer your_jwt_token

Quick Reference

Operation	Method	Endpoint	Description
Get current identity	GET	`/tenant`	Returns authenticated user and company info
Get company details	GET	`/tenant/{cid}`	Get hierarchy and details for a company
Update company	PUT	`/tenant`	Update name and permission settings
List companies	GET	`/tenant/customers/{cid?}`	List accessible companies
Create customer	POST	`/tenant/customer`	Create a new sub-customer with an owner
Get app accounts	GET	`/tenant/accounts/{cid?}`	List application accounts for a company
Get billing	GET	`/tenant/billing/{cid?}`	Retrieve billing information
Update billing	POST	`/tenant/billing/{cid?}`	Create or update billing information
List regions	GET	`/region`	Get all available regions
Get region	GET	`/region/{id}`	Get a specific region by ID

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:

GET /tenant HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response:

{
  "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"
  }
}

Response Fields:

Field	Type	Description
`identity.customerId`	integer	The customer ID the token is scoped to
`identity.userIdentityId`	integer	The authenticated user’s identity ID
`identity.email`	string	The authenticated user’s email
`customer.id`	integer	Unique company ID
`customer.name`	string	Company display name
`customer.regionId`	integer	The region this company’s data lives in
`customer.canAddCustomers`	boolean	Whether this company can create sub-customers
`customer.descendantsCanAdd`	boolean	Whether sub-customers can create their own customers

Get Company Details

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

URL: GET /tenant/{cid}

Requirements:

Authentication required

Path Parameters:

Parameter	Type	Required	Description
`cid`	integer	No	Company ID. If omitted, returns current company details.

Example Request:

GET /tenant/123 HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response:

{
  "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
    }
  ]
}

Update Customer Details

Description: Updates basic customer information and permission settings.

URL: PUT /tenant

Requirements:

Authentication required

Request Body:

{
  "customerId": 123,
  "name": "Updated Company Name",
  "canAddCustomers": true,
  "descendantsCanAdd": false
}

Field Descriptions:

Field	Type	Required	Description
`customerId`	integer	Yes	The ID of the company to update
`name`	string	No	New display name for the company
`canAddCustomers`	boolean	No	Whether this company can create sub-customers
`descendantsCanAdd`	boolean	No	Whether sub-customers can create their own customers

Example Request:

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
}

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:

Parameter	Type	Required	Description
`cid`	integer	No	Company ID to get subsidiaries for. If omitted, uses current company.
`self`	string (query)	No	Controls whether to include the root company in results. Accepted values: `"true"`, `"false"`, `"0"`, `"1"`, `"include"`, `"exclude"`

Example Request:

GET /tenant/customers/123?self=include HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response:

[
  {
    "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"
  }
]

Response Fields:

Field	Type	Description
`id`	integer	Unique company ID
`parentId`	integer	ID of the parent company
`name`	string	Company display name
`regionId`	integer	Region identifier
`canAddCustomers`	boolean	Whether this company can create sub-customers
`path`	string	Full path of the company in the hierarchy
`level`	integer	Depth in the hierarchy (0 = root)
`createdAt`	string	ISO 8601 timestamp of when the company was created

Create New Customer

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

URL: POST /tenant/customer

Requirements:

Authentication required
The authenticated user’s company must have canAddCustomers set to true

Request Body:

{
  "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
}

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. Use `GET /region/available` to list valid IDs.
`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 Builder access (default: true)
`tenant`	boolean	No	Grant Tenant Management access (default: true)

Example Request:

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
}

Example Response:

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

User Management

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:

Parameter	Type	Required	Description
`cid`	integer	No	Company ID. If omitted, returns accounts for current company.

Example Request:

GET /tenant/accounts/123 HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response:

[
  {
    "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 Management 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"
        }
      }
    ]
  }
]

Billing Information Management

Get Billing Information

Description: Retrieves billing information for a customer.

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

Requirements:

Authentication required

Parameters:

Parameter	Type	Required	Description
`cid`	integer	No	Customer ID. If omitted, returns billing info for current customer.

Example Request:

GET /tenant/billing/123 HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response:

{
  "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"
}

Update Billing Information

Description: Creates or updates billing information for a customer.

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

Requirements:

Authentication required

Parameters:

Parameter	Type	Required	Description
`cid`	integer	No	Customer ID. If omitted, updates current customer billing.

Request Body:

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

Field Descriptions:

Field	Type	Required	Description
`billingName`	string	No	Display name for billing purposes
`businessId`	string	No	Business registration ID
`taxId`	string	No	Tax identification number
`addressLine1`	string	No	Primary street address
`addressLine2`	string	No	Suite, floor, or unit number
`city`	string	No	City name
`state`	string	No	State or province
`zipCode`	string	No	Postal or ZIP code
`countryCode`	string	No	ISO 3166-1 alpha-2 country code (e.g., `"US"`)

Example Request:

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"
}

Response: 204 No Content on success

Region Management

Get Available Regions

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

URL: GET /region/available

Requirements:

Authentication required

Example Request:

GET /region/available HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response:

[
  {
    "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"
  }
]

Get All Regions

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

URL: GET /region

Requirements:

Authentication required
Root customer permissions

Example Request:

GET /region HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Get Specific Region

Description: Retrieves details about a specific region by ID.

URL: GET /region/{id}

Requirements:

Authentication required

Parameters:

Parameter	Type	Required	Description
`id`	integer	Yes	Region ID

Example Request:

GET /region/1 HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response:

{
  "id": 1,
  "name": "US East",
  "description": "US East Coast region"
}

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)

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()

Get Customer Hierarchy (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()

Update Customer Settings (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}")

Update Billing Information (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)

Authorization Notes

Authentication: All endpoints require a valid JWT token in the Authorization header
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
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
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

Related pages:

User Management API - manage users and permissions within companies
Authentication - obtain and manage JWT tokens