# API Documentation

Welcome to the Synnax Enterprise API documentation. This API provides access to company financial data, predictions, and credit risk analytics.

If you would like to use Synnax Enterprise API, please reach out to us at <contact@synnax.ai> or via a support form on [synnax.app](https://app.gitbook.com/u/yf3uNRE9VrOf1L5mn19gLFF3mpq2).

## Base URL

```
https://public-company-report-api.synnax.app/enterprise/v1
```

## Authentication

All Enterprise API endpoints require authentication using an API key in the Authorization header:

```bash
Authorization: Bearer <YOUR_API_KEY>
```

#### Example Request

```bash
curl -X POST https://public-company-report-api.synnax.app/enterprise/v1/companies/search \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "itemsPerPage": 10,
    "textSearch": "Apple"
  }'
```

## Field Notation

In the type definitions throughout this documentation:

* Fields marked with `?` are **optional** and may not be present in the response
* Fields without `?` are **required** and will always be present (when the parent object exists)
* `UNCALC` means the ratio could not be calculated, typically due to division by zero or missing required data

***

## Endpoints

### Search Companies

Search for companies with filtering, sorting, and pagination capabilities.

**Endpoint:** `POST /companies/search`

**Request Body**

```typescript
{
  "itemsPerPage": number,
  "textSearch"?: string,
  "nextPageKey"?: string, // For pagination (from previous response)
  "filter"?: {
    "countryCode"?: string[],
    "industry"?: string[],
    "sector"?: string[],
    "status"?: string[]
  }
}
```

**Filter Values**

* **countryCode**: Uses [ISO 3166-1 alpha-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) (e.g., `"US"`, `"CN"`, `"GB"`)
* **industry and sector**: See the complete list in the [industry-sector](https://docs.synnax.ai/synnax/private-entities-onboarding/industry-sector "mention") page
* **status**: See the available company statuses in the [company-statuses](https://docs.synnax.ai/synnax/synnax-enterprise/api-documentation/company-statuses "mention") page

**Response**

```typescript
{
  "totalCount": number,
  "items": [
    {
      "companyId": string,
      "name": string,
      "tickerSymbol": string,
      "countryCode": string,
      "countryName": string,
      "industry": string,
      "sector": string,
      "status": string
    }
  ],
  "nextPageKey"?: string            // Present if more results available
}
```

**Pagination**

To paginate through results:

1. Make an initial request with `itemsPerPage` set to your desired page size
2. From the response include the `nextPageKey` for the subsequent requests
3. Continue pagination until the number of items returned is less than `itemsPerPage`

***

### Get Company Summary Report

Retrieve current and predicted financial summary report for a company.

**Endpoint:** `POST /companies/report/summary/get`

**Request Body**

```typescript
{
  "companyId": string
}
```

You can get the `companyId` using the Search API (see [above](#search-companies)).

**Response**

```typescript
{
  "companyInformation": {
    "id": string,
    "name": string,
    "website"?: string,
    "countryCode": string,
    "countryName": string,
    "financialCurrency"?: string,
    "industry": string,
    "sector": string,
    "tickerSymbol": string,
    "status": string,
    "lastUpdatedQuarterEndDate": string
  },
  "summary": {
    "realized": {
      "quarterEndDate": string,
      "fiscalQuarter": {
        "endYear": number,
        "quarter": number
      },
      "creditSignal"?: {
        "label": string,
        "numeric": number
      },
      "probabilityOfDefault"?: number
    },
    "predicted"?: {
      "expectedQuarterEndDate": string,
      "fiscalQuarter": {
        "endYear": number,
        "quarter": number
      },
      "creditSignal"?: {
        "label": string,
        "numeric": number
      },
      "probabilityOfDefault"?: number
    }
  }
}
```

***

### Get Company Predictions Report

Retrieve daily predictions for future quarters with detailed financial indicators and ratios. Each `datasetDate` represents a snapshot of predictions made on that particular date from multiple model runs.

**Endpoint:** `POST /companies/report/timeseries/predictions/get`

**Request Body**

```typescript
{
  "companyId": string
}
```

You can get the `companyId` using the Search API (see [above](#search-companies)).

**Response**

```typescript
{
  "companyId": string,
  "predictions": {
    "[quarterEndDate]": {
      "[datasetDate]": {  // Date of the dataset and submissions made by data scientists
        "expectedQuarterEndDate": string,
        "fiscalQuarter": {
          "endYear": number,
          "quarter": number
        },
        "datasetDate": string,
        "indicators": {
          "[dataScientistId]": {  // One submission per data scientist
            "cceAndShortTermInvestments": number,
            "costOfRevenue": number,
            "currentAssets": number,
            "ebit": number,
            "ebt": number,
            "grossProfit": number,
            "interestExpenses": number,
            "inventory": number,
            "longTermDebt": number,
            "netIncome": number,
            "operatingIncome": number,
            "payables": number,
            "receivables": number,
            "stockholdersEquity": number,
            "totalAssets": number,
            "totalDebt": number,
            "totalRevenue": number,
            "currentDebt"?: number,
            "incomeTaxPayable"?: number,
            "otherOperatingExpenses"?: number,
            "sellingAndMarketingExpenses"?: number,
            "sellingGeneralAndAdministrativeExpenses"?: number
          }
          // Multiple model runs with different identifiers
        },
        "ratios": {
          "[dataScientistId]": {  // Same data scientist identifiers as in indicators
            "current": number | "UNCALC",
            "quick": number | "UNCALC",
            "cash": number | "UNCALC",
            "receivablesTurnover": number | "UNCALC",
            "inventoryTurnover": number | "UNCALC",
            "payablesTurnover": number | "UNCALC",
            "grossProfitMargin": number | "UNCALC",
            "operatingProfitMargin": number | "UNCALC",
            "pretaxMargin": number | "UNCALC",
            "netProfitMargin": number | "UNCALC",
            "operatingReturnOnAssets": number | "UNCALC",
            "returnOnAssets": number | "UNCALC",
            "returnOnEquity": number | "UNCALC",
            "returnOnInvestedCapital": number | "UNCALC",
            "taxBurden": number | "UNCALC",
            "interestBurden": number | "UNCALC",
            "ebitMargin": number | "UNCALC",
            "financialLeverage": number | "UNCALC",
            "debtToAssets": number | "UNCALC",
            "debtToEquity": number | "UNCALC",
            "debtToCapital": number | "UNCALC",
            "interestCoverage": number | "UNCALC"
          }
          // Multiple model runs with different identifiers
        },
        "derivedAttributes"?: {
          "creditSignal"?: {
            "label": string,
            "numeric": number
          },
          "probabilityOfDefault"?: number
        }
      }
    }
  }
}
```

***

### Get Historic Predictions Report

Retrieve past predictions with aggregated statistics (median, mean, max, min) for quarters that have already occurred.

**Endpoint:** `POST /companies/report/timeseries/predictions/historic/get`

**Request Body**

```typescript
{
  "companyId": string
}
```

You can get the `companyId` using the Search API (see [above](#search-companies)).

**Response**

```typescript
{
  "companyId": string,
  "historicPredictions": {
    "[quarterEndDate]": {
      "quarterEndDate": string,
      "fiscalQuarter": {
        "endYear": number,
        "quarter": number
      },
      "indicators": {
        "[indicatorName]": {
          "median"?: number,
          "mean"?: number,
          "max"?: number,
          "min"?: number
        }
        // Available for all indicator fields (cceAndShortTermInvestments, costOfRevenue, etc.) 
      },
      "ratios": {
        "[ratioName]": {
          "median"?: number,
          "mean"?: number,
          "max"?: number,
          "min"?: number
        }
        // Available for all ratio fields (current, quick, cash, etc.)
      },
      "derivedAttributes"?: {
        "creditSignal"?: {
          "label": string,
          "numeric": number
        },
        "probabilityOfDefault"?: number
      }
    }
  }
}
```

***

### Get Realized Historical Report

Retrieve actual reported financial data for past quarters.

**Endpoint:** `POST /companies/report/timeseries/realized/get`

**Request Body**

```typescript
{
  "companyId": string
}
```

You can get the `companyId` using the Search API (see [above](#search-companies)).

**Response**

```typescript
{
  "companyId": string,
  "realized": {
    "[quarterEndDate]": {
      "quarterEndDate": string,
      "fiscalQuarter": {
        "endYear": number,
        "quarter": number
      },
      "indicators"?: {
        "cceAndShortTermInvestments": number,
        "costOfRevenue": number,
        "currentAssets": number,
        "ebit": number,
        "ebt": number,
        "grossProfit": number,
        "interestExpenses": number,
        "inventory": number,
        "longTermDebt": number,
        "netIncome": number,
        "operatingIncome": number,
        "payables": number,
        "receivables": number,
        "stockholdersEquity": number,
        "totalAssets": number,
        "totalDebt": number,
        "totalRevenue": number,
        "currentDebt"?: number,
        "incomeTaxPayable"?: number,
        "otherOperatingExpenses"?: number,
        "sellingAndMarketingExpenses"?: number,
        "sellingGeneralAndAdministrativeExpenses"?: number
      },
      "ratios"?: {
        "current": number | "UNCALC",
        "quick": number | "UNCALC",
        "cash": number | "UNCALC",
        "receivablesTurnover": number | "UNCALC",
        "inventoryTurnover": number | "UNCALC",
        "payablesTurnover": number | "UNCALC",
        "grossProfitMargin": number | "UNCALC",
        "operatingProfitMargin": number | "UNCALC",
        "pretaxMargin": number | "UNCALC",
        "netProfitMargin": number | "UNCALC",
        "operatingReturnOnAssets": number | "UNCALC",
        "returnOnAssets": number | "UNCALC",
        "returnOnEquity": number | "UNCALC",
        "returnOnInvestedCapital": number | "UNCALC",
        "taxBurden": number | "UNCALC",
        "interestBurden": number | "UNCALC",
        "ebitMargin": number | "UNCALC",
        "financialLeverage": number | "UNCALC",
        "debtToAssets": number | "UNCALC",
        "debtToEquity": number | "UNCALC",
        "debtToCapital": number | "UNCALC",
        "interestCoverage": number | "UNCALC"
      },
      "derivedAttributes"?: {
        "creditSignal"?: {
          "label": string,
          "numeric": number
        },
        "probabilityOfDefault"?: number
      }
    }
  }
}
```

***

## Error Responses

All endpoints return standard HTTP status codes and error responses in JSON format.

#### 400 Bad Request

Invalid request body or parameters

```json
{
  "message": "Validation error: companyId is required"
}
```

#### 401 Unauthorized

Missing or invalid authentication token

```json
{
  "message": "Unauthorized"
}
```

#### 403 Forbidden

Subscription required or access denied

```json
{
  "message": "Subscription required to access this company's data"
}
```

#### 404 Not Found

Company not found

```json
{
  "message": "Company not found"
}
```

#### 500 Internal Server Error

Server error

```json
{
  "message": "Internal server error"
}
```

***

## Examples & Common Use Cases

This section demonstrates typical workflows and tasks using the Enterprise API.

#### Example 1: Find Company ID by Name

To work with a specific company, you first need to find its `companyId`. Here's how to search for Alphabet (Google):

**Request**

```bash
curl -X POST https://public-company-report-api.synnax.app/enterprise/v1/companies/search \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "textSearch": "GOOGL",
    "itemsPerPage": 10
  }'
```

**Response**

```json
{
  "totalCount": 2,
  "items": [
    {
      "companyId": "8af77c11-98c2-427c-ae91-bc81b79f01a5",
      "name": "Alphabet Inc.",
      "tickerSymbol": "GOOGL",
      "countryCode": "US",
      "countryName": "United States of America",
      "industry": "Internet Content & Information",
      "sector": "Communication Services",
      "status": "Active"
    },
    {
      "companyId": "562e476f-16bf-4288-8bb8-2cb7bbd7d235",
      "name": "Googol Technology Co., Ltd.",
      "tickerSymbol": "301510.SZ",
      "countryCode": "CN",
      "countryName": "People's Republic of China",
      "industry": "Electronic Components",
      "sector": "Technology",
      "status": "Active"
    }
  ],
  "nextPageKey": "[9.776237,0,\"Active\",1751241600000,\"562e476f-16bf-4288-8bb8-2cb7bbd7d235\"]"
}
```

{% hint style="info" %}
**Note:** In this example, we requested 10 items but received only 2 results, yet `nextPageKey` is still present. This is expected behavior — the next page will be empty. See the Pagination section above for more details.
{% endhint %}

***

#### Example 2: Get Current Financial Summary

Once you have a company ID, retrieve the current financial summary including credit signal and probability of default:

**Request**

```bash
curl -X POST https://public-company-report-api.synnax.app/enterprise/v1/companies/report/summary/get \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "8af77c11-98c2-427c-ae91-bc81b79f01a5"
  }'
```

**Response**

```json
{
  "companyInformation": {
    "id": "8af77c11-98c2-427c-ae91-bc81b79f01a5",
    "name": "Alphabet Inc.",
    "website": "https://abc.xyz",
    "countryCode": "US",
    "countryName": "United States of America",
    "financialCurrency": "USD",
    "sector": "Communication Services",
    "industry": "Internet Content & Information",
    "tickerSymbol": "GOOGL",
    "status": "Active",
    "lastUpdatedQuarterEndDate": "2025-06-30"
  },
  "summary": {
    "realized": {
      "quarterEndDate": "2025-06-30",
      "fiscalQuarter": {
        "quarter": 2,
        "endYear": 2025
      },
      "creditSignal": {
        "numeric": 100,
        "label": "Superior"
      },
      "probabilityOfDefault": 1.28
    },
    "predicted": {
      "expectedQuarterEndDate": "2025-09-30",
      "fiscalQuarter": {
        "quarter": 3,
        "endYear": 2025
      },
      "creditSignal": {
        "numeric": 99,
        "label": "Superior"
      },
      "probabilityOfDefault": 1.38
    }
  }
}
```

***

#### Example 3: Get Realized Financial Data

Retrieve actual reported financial data for past quarters, including detailed indicators and ratios:

**Request**

```bash
curl -X POST https://public-company-report-api.synnax.app/enterprise/v1/companies/report/timeseries/realized/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "8af77c11-98c2-427c-ae91-bc81b79f01a5"
  }'
```

**Response**

```json
{
  "companyId": "8af77c11-98c2-427c-ae91-bc81b79f01a5",
  "realized": {
    "2025-06-30": {
      "quarterEndDate": "2025-06-30",
      "fiscalQuarter": {
        "quarter": 2,
        "endYear": 2025
      },
      "indicators": {
        "operatingIncome": 31271000000,
        "currentDebt": 0,
        "interestExpenses": 261000000,
        "totalAssets": 502053000000,
        "sellingGeneralAndAdministrativeExpenses": 12310000000,
        "ebit": 34194000000,
        "totalDebt": 35559000000,
        "longTermDebt": 35559000000,
        "costOfRevenue": 39039000000,
        "inventory": 0,
        "stockholdersEquity": 362916000000,
        "currentAssets": 166216000000,
        "cceAndShortTermInvestments": 95148000000,
        "payables": 63074000000,
        "incomeTaxPayable": 786000000,
        "ebt": 33933000000,
        "sellingAndMarketingExpenses": 7101000000,
        "netIncome": 28196000000,
        "receivables": 55048000000,
        "totalRevenue": 96428000000,
        "grossProfit": 57389000000,
        "otherOperatingExpenses": -20231000000
      },
      "ratios": {
        "quick": "UNCALC",
        "operatingReturnOnAssets": 0.0639863641990655,
        "returnOnAssets": 0.05769433420603278,
        "inventoryTurnover": "UNCALC",
        "debtToCapital": 0.0892377188029362,
        "payablesTurnover": 0.5901498087708424,
        "interestBurden": 0.9923670819442008,
        "receivablesTurnover": 1.7517076006394419,
        "operatingProfitMargin": 0.3242937735927324,
        "pretaxMargin": 0.3518998631102999,
        "netProfitMargin": 0.2924046957315303,
        "debtToEquity": 0.09798135105644282,
        "current": "UNCALC",
        "grossProfitMargin": 0.5951487119923674,
        "interestCoverage": 131.01149425287358,
        "returnOnEquity": 0.0796291354070911,
        "returnOnInvestedCapital": 0.08924372248161962,
        "debtToAssets": 0.07082718358420326,
        "financialLeverage": 1.3833862381377509,
        "cash": "UNCALC",
        "ebitMargin": 0.3546065458165678,
        "taxBurden": 0.8245891092004445
      },
      "derivedAttributes": {
        "creditSignal": {
          "numeric": 100,
          "label": "Superior"
        },
        "probabilityOfDefault": 1.28
      }
    }
  }
}
```

***

#### Example 4: Get Median Predicted Cost of Revenue

To calculate the median predicted cost of revenue for a company, retrieve historic predictions which include aggregated statistics:

**Request**

```bash
curl -X POST https://public-company-report-api.synnax.app/enterprise/v1/companies/report/timeseries/predictions/historic/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "8af77c11-98c2-427c-ae91-bc81b79f01a5"
  }'
```

**Response**

```json
{
  "companyId": "8af77c11-98c2-427c-ae91-bc81b79f01a5",
  "historicPredictions": {
    "2025-06-30": {
      "quarterEndDate": "2025-06-30",
      "fiscalQuarter": {
        "endYear": 2025,
        "quarter": 2
      },
      "indicators": {
        "costOfRevenue": {
          "median": 39039000000,
          "mean": 39150000000,
          "max": 40200000000,
          "min": 38100000000
        },
        // Other indicators...
      },
      "ratios": {
        // All ratios...
      },
      "derivedAttributes": {
        "probabilityOfDefault": 1.44,
        "creditSignal": {
          "label": "Superior",
          "numeric": 99
        }
      }
    },
    "2025-03-31": {
      // ...
    }
  }
}
```

The `median` value under `indicators.costOfRevenue` gives you the median predicted cost of revenue across all data scientist submissions for that quarter.

***

## Support

For additional help or questions about the Enterprise API, please contact our support team or refer to our main documentation portal.