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 [email protected] or via a support form on synnax.app.

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:

Authorization: Bearer <YOUR_API_KEY>

Example Request

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

{
  "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 (e.g., "US", "CN", "GB")
industry and sector: See the complete list in the Industry / Sector page
status: See the available company statuses in the Company Statuses page

Response

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

Make an initial request with itemsPerPage set to your desired page size
From the response include the nextPageKey for the subsequent requests
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

{
  "companyId": string
}

You can get the companyId using the Search API (see above).

Response

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

{
  "companyId": string
}

You can get the companyId using the Search API (see above).

Response

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

{
  "companyId": string
}

You can get the companyId using the Search API (see above).

Response

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

{
  "companyId": string
}

You can get the companyId using the Search API (see above).

Response

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

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

401 Unauthorized

Missing or invalid authentication token

{
  "message": "Unauthorized"
}

403 Forbidden

Subscription required or access denied

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

404 Not Found

Company not found

{
  "message": "Company not found"
}

500 Internal Server Error

Server error

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

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

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

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.

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

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

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

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

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

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

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

PreviousUploading Data to Synnax Pro NextCompany Statuses

Last updated 4 days ago