Synthreo Customer Management API Documentation

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

Description: All endpoints require authentication via JWT Bearer token.

URL: POST /auth/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 list of customers is the customers you have access to.

Append the following to your header in all future calls

Authorization: Bearer your_jwt_token

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

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:

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
}

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:

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:

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

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:

{
  "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
`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:

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:

cid (optional): 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 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"
                }
            }
        ]
    }
]

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:

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:

cid (optional): 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"
}

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 complete list of all regions (requires root customer permissions).

URL: GET /region

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 regions where both TheoBuilder and ThreoAI applications are available for new customer creation.

URL: GET /region/available

Requirements:

Authentication required

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:

id (integer): 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}")

# Usage example
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

Overview​

Base URL​

Authentication​

Company Identity and Information​

Get Current Identity​

Get Company Details​

Update Customer Details​

Company Hierarchy Management​

Get Company List​

Create New Customer​

User Management​

Application Account Management​

Get Application Accounts​

Billing Information Management​

Get Billing Information​

Update Billing Information​

Region Management​

Get Available Regions​

Get All Regions​

Get Specific Region​

Permission Requirements​

Code Examples​

Create a New Customer (Python)​

Get Customer Hierarchy (Python)​

Update Customer Settings (Python)​

Update Billing Information (Python)​

Authorization Notes​

Best Practices​

Error Handling​

Performance Optimization​

Security Considerations​

Overview

Base URL

Authentication

Company Identity and Information

Get Current Identity

Get Company Details

Update Customer Details

Company Hierarchy Management

Get Company List

Create New Customer

User Management

Application Account Management

Get Application Accounts

Billing Information Management

Get Billing Information

Update Billing Information

Region Management

Get Available Regions

Get All Regions

Get Specific Region

Permission Requirements

Code Examples

Create a New Customer (Python)

Get Customer Hierarchy (Python)

Update Customer Settings (Python)

Update Billing Information (Python)

Authorization Notes

Best Practices

Error Handling

Performance Optimization

Security Considerations