NAV
shell

Introduction

Cognitive Credit provides a REST API to enable clients to pull data from the Cognitive Credit Application in standardised, JSON-encoded format.

These pages provide a tool for clients who are interested in Cognitive Credit Company data to be consumed via an interface that is fast and scalable, and view data that will be returned by the API, as well as the documentation necessary to build to the Cognitive Credit service and integrate it into their system.

For full connectivity and access to the Cognitive Credit Data Set, clients must subscribe to the API service and will be given an authentication key to enable them to securely connect to the Cognitive Credit server.

Useful resources

Swagger UI

We have a Swagger UI site which you can use to explore our API: You can find it at swagger-ui/

OpenAPI V3 file

You can download an OpenAPI V3 file which describes our API. It can be used for generating API clients, generating mock servers and stub code, etc. It can also be imported into Postman

Pre-generated clients

We have generated a selection of clients from our OpenAPI file using OpenAPI Generator. You can download SDKs for:

Or you can download all SDKs in one file.

Clients may need adjustments to work correctly.

If you would like a client in another language, just ask. We can produce clients in any of the languages in this list. Alternatively, download the OpenAPI file and generate your own; for example using the OpenAPI Generator online tool.

Generated server stubs

If you would like server stubs generated to aid your integration testing, we can generate code for these languages/frameworks on request. Alternatively, use the OpenAPI file to generate your own.

Authentication & authorisation

To authorise, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" \
  -H "x-api-key: api-key-value"

Make sure to replace api-key-value with your API key.

The Data API uses API keys to allow access to the API. Contact our sales team to get set up!

DAPI expects for the API key to be included in all API requests to the server in a header that looks like the following:

x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS

The header name is not case-sensitive.

Coverage Universe

Each company has been assigned one or more coverage universes. Clients can be assigned licences for one or more of these.

API queries are automatically filtered to return companies in the assigned universe(s). The list of possible coverage universes is as follows:

Code Description
us-hy U.S. High Yield licence
us-ig U.S. Investment Grade licence
euro-hy European High Yield licence
euro-ig European Investment Grade licence

Throttling

Please note that throttling will be applied on a per client basis if the request limits are exceeded - see the errors section for specific limits.

Content encoding

An example cURL request would look like this:

curl "api_endpoint_here" \
  -H "Accept-Encoding: gzip, deflate" \
  -H "x-api-key: api-key-value"

Compression is supported for responses greater than 1kb. Include an Accept-Encoding header in your request to supply your supported encodings.

The supported methods of content coding are:

If this header is not present or no method of content coding is specified, the API endpoint will return an uncompressed response.

HTTP request headers common to all endpoints

Paging

curl -X GET "${BASE_PATH}/companies?limit=2" \
  -H 'Accept: application/json' \
  -H 'x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS'

{
  "meta": {
    "next": "/companies?limit=2&continuation_token=adient"
  },
  "data": {
   "results": "here" 
  }
}

curl -X GET "${BASE_PATH}/companies?limit=2&continuation_token=adient" \
  -H 'Accept: application/json' \
  -H 'x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS'

{
  "meta": {
    "next": "/companies?limit=2&continuation_token=adlergroup"
  },
  "data": {
   "more_results": "here" 
  }
}

curl -X GET "${BASE_PATH}/companies?limit=2&continuation_token=adlergroup" \
  -H 'Accept: application/json' \
  -H 'x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS'

{
  "meta": {
    "next": null
  },
  "data": {
   "even_more_results": "here" 
  }
}

All list queries support paging. To request paged data, include a limit query parameter. The response will include a meta section with a next field containing the url fragment that will fetch the next page. Use this with the base url. When there are no more pages of data, the value of the next field will be null.

Routes

All URIs are relative to https://cognitivecreditapi.com/v1

Method HTTP request Description
GetCompanyDescriptions GET /companies Get company descriptions
GetCompanyComparables GET /comparables/{interval} Get company comparables
GetCompanyComparables GET /comparables [This is a legacy route] - It is equivalent to making a request to /comparables/ltm
GetComparablesUpdatesSince GET /comparables/updates Get company comparables updates for a given time period
GetCompanyFinancials GET /companies/{companyId}/financials Get company financials
GetCompanyDatapoint GET /datapoints/{datapointId} Get a company datapoint
GetCompanyPeriodDates GET /companies/{companyId}/periods Get company period dates
GetCompanyTimeSeries GET /companies/{companyId}/timeseries/{tag}/{interval} Get company time series

GetCompanyDescriptions

Companies covered can be requested as follows:

BASE_PATH=https://cognitivecreditapi.com/v1

curl -X GET "${BASE_PATH}/companies" \
  -H 'Accept: application/json' \
  -H 'x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS'

curl -X GET "${BASE_PATH}/companies?limit=20&continuation_token=acs" \
  -H 'Accept: application/json' \
  -H 'x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS'

curl -X GET "${BASE_PATH}/companies?at_timestamp=2022-08-26&company_ids=accor,adient,bkfrance" \
  -H 'Accept: application/json' \
  -H 'x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS'

An example request to get all Company Descriptions updates since a particular date-time is as follows:

BASE_PATH=https://cognitivecreditapi.com/v1

curl -X GET "${BASE_PATH}/companies?updated_after=2023-01-02T09:00:00" \
  -H 'Accept: application/json' \
  -H 'x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS'

A typical response would be:

{
    "meta": {
        "next": "/companies?at_timestamp=2022-08-17T08:49:16.883091%2B00:00&limit=2&continuation_token=adient"
    },
    "data": [
        {
            "id": "accor",
            "name": "Accor",
            "ticker": "ACFP",
            "retired": false,
            "gics_code": "25301020",
            "ownership": "pub",
            "country_code": "FR",
            "generated_at": "2022-09-02T16:24:16.956719+00:00",
            "retired_date": null,
            "url_investors_relations": "https://group.accor.com/en/investors",
            "currency": "EUR",
            "multiplier": "Millions",
            "year_end": "Dec",
            "frequency": "Q",
            "last_reported_date": "2022-01-01T02:34:56+00:00",
            "accounting_standard": "IFRS",
            "next_reporting_date": "2022-04-01 02:34:56+00",
            "last_reported_period": "Q3",
            "next_reporting_period": "Q4",
            "last_reported_document_type": "Annual report",
            "created_at": "2022-09-02T16:24:17.951869+00:00",
            "updated_at": "2022-09-02T16:24:17.951869+00:00",
            "description": "Accor’s business model is founded on a wide range of accommodation in hotels and private residences offered to travelersand travel professionals, together with coworking spaces and countless services.",
        },
        {
            "id": "adient",
            "name": "Adient",
            "ticker": "ADNT",
            "retired": false,
            "gics_code": "25101010",
            "ownership": "pub",
            "country_code": "IE",
            "generated_at": "2022-09-02T16:24:26.473911+00:00",
            "retired_date": null,
            "url_investors_relations": "https://www.adient.com/investors",
            "currency": "USD",
            "multiplier": "Millions",
            "year_end": "Sep",
            "frequency": "Q",
            "last_reported_date": "2022-08-05T00:00:00+00:00",
            "accounting_standard": "US GAAP",
            "next_reporting_date": null,
            "last_reported_period": "3Q22",
            "next_reporting_period": "FY22",
            "last_reported_document_type": "preliminaries",
            "created_at": "2022-09-02T16:24:27.236060+00:00",
            "updated_at": "2022-09-02T16:24:27.236060+00:00",
            "description": "Adient is a global leader in the automotive seating supply industry, with leading market positions in theAmericas, Europe and China. Adient maintains longstanding relationships with the largest global automotiveoriginal equipment manufacturers (“OEMs”). Adient’s proprietary technologies extend into virtually every areaof automotive seating solutions, including complete seating systems, frames, mechanisms, foam, head restraints,armrests, trim covers and fabrics.",
        }
    ]
}

Get company descriptions

Returns a list of company description objects.

HTTP Request

GET https://cognitivecreditapi.com/v1/companies

Query Parameters

Name Type Description Notes
at_timestamp Date timestamp to return company descriptions snapshot for [optional] ISO-8601 format (for timezone offsets, be sure to URL encode the + as %2B)
company_ids String filter by supplied company ids [optional] Comma separated list
is_retired String filter by retired status - (true, false) [optional]
tickers String filter by supplied tickers [optional] Comma separated list
limit Integer maximum number of results to return - typically used when paging [optional]
updated_after Date only return latest company descriptions added or updated on or after this ISO-8601 timestamp [optional] This filters on the date the company description set was created (either when an existing company is updated or a new company is added). Therefore, in the response you will see results with created_at in the range set by this parameter. (for timezone offsets, be sure to URL encode the + as %2B)
updated_before Date only return latest company descriptions added or updated before this ISO-8601 timestamp [optional] As above (for timezone offsets, be sure to URL encode the + as %2B).
last_reported_date_after Date only return latest company descriptions where last reported date is on or after this ISO-8601 timestamp [optional] ISO-8601 format (for timezone offsets, be sure to URL encode the + as %2B)
last_reported_date_before Date only return latest company descriptions where last reported date is before this ISO-8601 timestamp [optional] ISO-8601 format (for timezone offsets, be sure to URL encode the + as %2B)
continuation_token String identifier of last result in previous result set - allows continuation of paged results [optional]

Return type

Name Type
data List[Company]
meta Metadata

with Metadata having the form:

Name Type Notes
next String Url fragment to fetch the next page of data. null if there are no more pages

and with a Company having the form:

Name Type Description
accounting_standard String the Accounting Standard use, for example IFRS or GAAP
country_code String 2-Char Country Code
created_at[Deprecated] Date Creation Date Note: This field is now deprecated.
updated_at Date Update Date
currency String 3-Char Currency Code
frequency String 1-Char Company Reporting Frequency Code, example: Q (Quarterly), H (Half-yearly), Y (Yearly)
generated_at[Deprecated] Date Date the data was generated. Note: This field is now deprecated.
gics_code String code to identify company by sector, industry group, industry and sub-industry
id String string Identifier
last_reported_date Date date company last reported
last_reported_document_type String Report Type (Earnings Report, Presentation, Prospectus)
last_reported_period String the Reporting Period corresponding to this report
multiplier String numeric multiplier on what the numbers are quoted in, example: millions
name String company name
next_reporting_date String date the company will be next reporting
next_reporting_period String the next expected reporting period
ownership String company status as public or private
retired Boolean true / false flag to indicate if a company is retired/no longer reporting
retired_date Date the date the company was retired if no longer reporting
ticker String Bloomberg ticker
url_investors_relations String link to the Company Investor Relations website
year_end String the financial year end cycle of the company
description String A description provided by the issuer in their disclosure regarding the nature of their business

GetCompanyComparables

BASE_PATH=https://cognitivecreditapi.com/v1
INTERVAL="ltm"

curl -X GET "${BASE_PATH}/comparables/${INTERVAL}?limit=2" \
  -H 'Accept: application/json' \
  -H 'x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS'

curl "${BASE_PATH}/comparables/${INTERVAL}?at_timestamp=2022-08-25T15:51:55.789012Z&limit=2" \
  -H 'Accept: application/json' \
  -H 'x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS'

curl"${BASE_PATH}/comparables/${INTERVAL}?at_timestamp=2022-08-26&company_ids=accor,adient,bkfrance" \
  -H 'Accept: application/json' \
  -H 'x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS'

A typical response would be (omitting almost all of the actual comparables data):

{
    "data": [
        {
            "company_id": "accor",
            "generated_at": "2022-10-13T10:11:06.489680+00:00",
            "updated_at": "2022-10-13T10:11:06.489680+00:00",
            "report_period": "1H22",
            "interval": "ltm",
            "comparables": [
                {
                    "id": "YWNjb3IraGFyZC1zdG9hdCs0MDQwMDg3OTM=",
                    "tag": "Revenue",
                    "period": "1H22-LTM",
                    "label": "Revenue",
                    "value": "3105"
                },
                {
                    "id": "YWNjb3IraGFyZC1zdG9hdCs0MDQwMTA3MDQ=",
                    "tag": "cc:YoyRevenueChange",
                    "period": "1H22-LTM",
                    "label": "Revenue Δ% YoY",
                    "value": "1.0320680628272252"
                }
            ]
        },
        {
            "company_id": "adient",
            "generated_at": "2022-08-25T15:51:39.841441+00:00",
            "updated_at": "2022-08-25T15:51:39.841441+00:00",
            "report_period": "1Q22",
            "interval": "ltm",
            "comparables": [
                {
                    "id": "YWNjb3IraGFyZC1zdG9hdCs0MDQwMTA5MTI=",
                    "tag": "Revenue",
                    "value": "13242.0",
                    "period": "3Q22-LTM",
                    "label": "Revenue"
                },
                {
                    "id": "YWNjb3IraGFyZC1zdG9hdCs0MDQwMTAzMDI=",
                    "tag": "cc:YoyRevenueChange",
                    "value": "-0.0871363573693644",
                    "period": "3Q22-LTM",
                    "label": "Revenue Δ% YoY"
                }
            ]
        }
    ],
    "meta": {
        "next": "/comparables/ltm?limit=2&continuation_token=adient"
    }
}

Get company comparables

Returns comparables data for a list of companies for the allowed coverage universe

HTTP Request

GET https://cognitivecreditapi.com/v1/comparables/{interval}

Path Parameters

Name Type Description Notes
interval String identifier for the interval of comparables data to fetch [mandatory] Allowed values are ltm, annual or interim

Query Parameters

Name Type Description Notes
at_timestamp Date timestamp to return comparables snapshot for [optional] ISO-8601 format (for timezone offsets, be sure to URL encode the + as %2B)
company_ids String filter by supplied company ids [optional] Comma separated list
limit Integer maximum number of results to return - typically used when paging [optional]
continuation_token String identifier of last result in previous result set - allows continuation of paged results [optional]

Return type

Name Type
data List[Comparable]
meta Metadata

with Metadata having the form:

Name Type Notes
next String Url fragment to fetch the next page of data. null if there are no more pages

and with a Comparables object having the form:

Name Type Description
company_id String Company Identifier
interval String the comparables interval returned, for example Last Twelve Months (LTM)
comparables List[Comparable] array list of company comparables data
generated_at[Deprecated] Date date the comparables data was generated Note: This field is now deprecated.
id Integer unique Identifier
report_period String specific Reporting Period
updated_at Date Update Date

With a Comparable having the form:

Name Type Description
id String unique Identifier
label String text description of the tag returned, example: Revenue Δ% YoY
period String Reporting Period and Interval
tag String the tag to which this specific field was labeled as, example "cc:YoyRevenueChange"
value String numeric value corresponding to the returned label

GetComparablesUpdatesSince

Updates since can be requested as follows:

BASE_PATH=https://cognitivecreditapi.com/v1

curl -X GET "${BASE_PATH}/comparables/updates?start_timestamp=2010-01-01T12:34:56.789012Z&limit=2" \
  -H 'Accept: application/json' \
  -H 'x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS'

curl "${BASE_PATH}/comparables/updates?start_timestamp=2010-01-01T12:34:56.789012Z&end_timestamp=2022-08-25T15:51:46.206Z&limit=2" \
  -H 'Accept: application/json' \
  -H 'x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS'

curl "${BASE_PATH}/comparables/updates?start_timestamp=2010-01-01T12:34:56.789012Z&company_ids=adient,bkfrance" \
  -H 'Accept: application/json' \
  -H 'x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS'

A typical response would be (omitting almost all of the actual comparables data):

{
    "data": [
        {
            "company_id": "bkfrance",
            "generated_at": "2022-08-25T15:51:39.841441+00:00",
            "updated_at": "2022-08-25T15:51:39.841441+00:00",
            "report_period": "1Q22",
            "interval": "ltm",
            "comparables": [
                {
                    "id": "YWNjb3IraGFyZC1zdG9hdCs0MDQwMTAxOTg=",
                    "label": "Revenue"
                    "period": "1Q22-LTM",
                    "tag": "Revenue",
                    "value": "535.8",
                },
                {
                    "id": "YWNjb3IraGFyZC1zdG9hdCs0MDQwMTA0NDM=",
                    "label": "Revenue Δ% YoY"
                    "period": "1Q22-LTM",
                    "tag": "cc:YoyRevenueChange",
                    "value": "0.4395486297689414",
                }
            ]
        },
        {
            "company_id": "adient",
            "generated_at": "2022-08-25T15:51:46.205695+00:00",
            "updated_at": "2022-08-25T15:51:46.205695+00:00",
            "report_period": "3Q22",
            "interval": "ltm",
            "comparables": [
                {
                    "id": "YWNjb3IraGFyZC1zdG9hdCs0MDQwMTA1ODI=",
                    "label": "Revenue"
                    "period": "3Q22-LTM",
                    "tag": "Revenue",
                    "value": "13242.0",
                },
                {
                    "id": "YWNjb3IraGFyZC1zdG9hdCs0MDQwMTEwMTg=",
                    "label": "Revenue Δ% YoY"
                    "period": "3Q22-LTM",
                    "tag": "cc:YoyRevenueChange",
                    "value": "-0.0871363573693644",
                }
            ]
        }
    ],
    "meta": {
        "next": "/comparables/updates?start_timestamp=2010-01-01T12:34:56.789012Z&limit=2&continuation_token=2"
    }
}

Get company comparables updates for a given time period

Returns comparables data for a list of companies for the allowed coverage universe, from a given start timestamp and optional end timestamp

HTTP Request

GET https://cognitivecreditapi.com/v1/comparables/updates

Query Parameters

Name Type Description Notes
start_timestamp Date Timestamp to return comparables updates since (all updates greater than or equal to the timestamp) - for timezone offsets, be sure to URL encode the + as %2B [mandatory]
end_timestamp Date Timestamp to return comparables updates until (all updates less than, but not equal to, the timestamp) - for timezone offsets, be sure to URL encode the + as %2B [optional]
company_ids String filter by supplied company ids [optional]
limit Integer maximum number of results to return - typically used when paging [optional]
continuation_token String identifier of last result in previous result set - allows continuation of paged results [optional]

Return type

The response is of the same form as the GetCompanyComparables endpoint:

Name Type
data List[Comparables]
meta Metadata

with Metadata having the form:

Name Type Notes
next String Url fragment to fetch the next page of data. null if there are no more pages

with a Comparables object having the form:

Name Type Description
company_id String Company Identifier
interval String the comparables interval returned, example: Last Twelve Months (LTM)
comparables List[Comparable] array list of company comparables data
generated_at[Deprecated] Date date the comparables data was generated Note: This field is now deprecated.
updated_at Date Update Date
id Integer unique Identifier
report_period String specific Reporting Period

With a Comparable having the form:

Name Type Description
id String unique Identifier
label String text description of the tag returned, example: Revenue Δ% YoY
period String Reporting Period and Interval
tag String the tag to which this specific field was labeled as, example: cc:YoyRevenueChange
value String numeric value corresponding to the returned label

GetCompanyFinancials

BASE_PATH=https://cognitivecreditapi.com/v1
COMPANY_ID=adient

curl -L -X GET "${BASE_PATH}/companies/${COMPANY_ID}/financials" \
-H 'x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS'

curl -L -X GET "${BASE_PATH}/companies/${COMPANY_ID}/financials?at_timestamp=2022-08-17T08:49:16.883091Z" \
-H 'x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS'

A typical response would be (omitting almost all of the actual financials data):

{
    "data": {
        "company_id": "adient",
        "generated_at": "2022-10-13T10:12:08.910567+00:00",
        "updated_at": "2022-10-13T10:12:08.910567+00:00",
        "financials": [
            {
                "label": "Net sales",
                "sheet_type": "is",
                "tag": "Revenue",
                "data": [
                    {
                        "ids": [
                            "YWRpZW50K3BpZXJjaW5nLWd1aXRhcis5MDA1Mzc4"
                        ],
                        "period": "FY15",
                        "value": "20023"
                    },
                    {
                        "ids": [
                            "YWRpZW50K3BpZXJjaW5nLWd1aXRhcis5MDA1ODE3",
                            "YWRpZW50K3BpZXJjaW5nLWd1aXRhcis5MDA1Mzc3"
                        ],
                        "period": "FY16",
                        "value": "16790"
                    }
                ]
            },
            {
                "label": "Cost of sales",
                "sheet_type": "is",
                "tag": "CostOfSales",
                "data": [
                    {
                        "ids": [
                            "YWRpZW50K3BpZXJjaW5nLWd1aXRhcis5MDA1Mzgx"
                        ],
                        "period": "FY15",
                        "value": "-18171"
                    },
                    {
                        "ids": [
                            "YWRpZW50K3BpZXJjaW5nLWd1aXRhcis5MDA1ODIw",
                            "YWRpZW50K3BpZXJjaW5nLWd1aXRhcis5MDA1Mzgw"
                        ],
                        "period": "FY16",
                        "value": "-15181"
                    },
                    {
                        "ids": [
                            "YWRpZW50K3BpZXJjaW5nLWd1aXRhcis5MDA0MTYw",
                            "YWRpZW50K3BpZXJjaW5nLWd1aXRhcis5MDA1ODE5",
                            "YWRpZW50K3BpZXJjaW5nLWd1aXRhcis5MDA1Mzc5"
                        ],
                        "period": "FY17",
                        "value": "-14816"
                    }
                ]
            }
        ]
    }
}

Get company financials

Returns historical financials data for single company

The returned data is the entire financials history as they were known at the given at_timestamp value. Historical datapoint values can and do change - these will be reflected in datasets with later timestamps.

HTTP Request

GET https://cognitivecreditapi.com/v1/companies/{companyId}/financials

Path Parameters

Name Type Description Notes
companyId String identifier for the company to fetch financials for [mandatory]

Query Parameters

Name Type Description Notes
at_timestamp Date ISO-8601 Timestamp to return financials snapshot for (for timezone offsets, be sure to URL encode the + as %2B) [optional] ISO-8601 format

Return type

Name Type
data FinancialMetricCollection

With a FinancialMetricCollection having the form:

Name Type Description
company_id String identifier for the company to fetch financials for
financials List[FinancialDatapointSet] array list of company financials data points
generated_at[Deprecated] Date date the data was generated Note: This field is now deprecated.
updated_at Date Update Date

With a FinancialDatapointSet having the form:

Name Type Description
data List[FinancialDatapoint] Array list of company financials data points
label String Text description of the tag returned, example: Revenue Δ% YoY
sheet_type String Sheet Type - for example, 'is' for income statement
tag String the tag to which this specific field was labeled as, example: Revenue

with a single FinancialDatapoint having the form

Name Type Description
ids List unique data point identifier
period String Reporting Period
value String numeric value corresponding to the returned label

GetCompanyDatapoint

BASE_PATH=https://cognitivecreditapi.com/v1
DATAPOINT_ID=YWRpZW50K2NodWJieS1kdWNrKzkwMjk4MjM=

curl -L -X GET "${BASE_PATH}/datapoints/${DATAPOINT_ID}" \
-H 'x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS'

A typical response would be:

{
    "data": {
        "id": "YWRpZW50K2NodWJieS1kdWNrKzkwMjk4MjM=",
        "comment": null,
        "comment_refs": null,
        "company_id": "adient",
        "display_label": "Y/o/Y Revenue Change",
        "generated_at": "2023-09-27T14:08:05.086369+00:00",
        "page_number": null,
        "parts": [
            {
                "id": "YWRpZW50K2NodWJieS1kdWNrKzkwMDAwMzA=",
                "op": null
            },
            {
                "id": "YWRpZW50K2NodWJieS1kdWNrKzkwMDAwMzE=",
                "op": "vs."
            }
        ],
        "period": "FY22",
        "source_doc": null,
        "source_type": "re",
        "tag": "cc:YoyRevenueChange",
        "not_meaningful": false,
        "value": "0.0322368421",
        "updated_at": "2023-09-27T14:08:05.086369+00:00"
    }
}

Get a company datapoint

Returns details of an individual datapoint for a company.

The returned item is a datapoint, which describes the source and calculation behind the value. Ids can be found in the results from the comparables and the financials endpoints.

HTTP Request

GET https://cognitivecreditapi.com/v1/datapoints/{datapointId}

Path Parameters

Name Type Description Notes
datapointId String identifier for the datapoint [mandatory]

Return type

Name Type Description
data [CompanyDatapoint] array list of company data points

With a CompanyDatapoint having the form:

Name Type Description
comment String
comment_refs List[CommentRef]
company_id String Company identifier
display_label String text description of the tag returned example: Revenue Δ% YoY
generated_at[Deprecated] Date date the data was generated Note: This field is now deprecated.
updated_at Date Update Date
id String unique Identifier
page_number Integer page of the document where the data point was extracted
parts List[Part]
period String Reporting Period and Interval
source_doc String Originating Document
source_type[Deprecated] String Originating Source Type
tag String the tag to which this specific field was labeled as
value String numeric value corresponding to the returned label
not_meaningful Boolean Value that is insignificant, incompatible with the current view, or of a different type.

with a CommentRefs object having the form:

Name Type Description
doc String Originating Document
label String Text description of the tag returned example: Revenue Δ% YoY
page Integer

and a Part having the form:

Name Type Description
id String unique Identifier
op String operator (+, - etc)

GetCompanyPeriodDates

BASE_PATH=https://cognitivecreditapi.com/v1
COMPANY_ID=adient

curl -L -X GET "${BASE_PATH}/companies/${COMPANY_ID}/periods" \
-H 'x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS'

A typical response would be (omitting most of the period_dates data):

{
    "data": {
        "company_id": "adient",
        "generated_at": "2022-10-13T10:12:08.910567+00:00",
        "updated_at": "2022-10-13T10:12:08.910567+00:00",
        "period_dates": [
            {
                "period": "FY22",
                "date": "2022-09-30"
            },
            {
                "period": "1H22",
                "date": "2022-03-31"
            },
            {
                "period": "3Q22-LTM",
                "date": "2022-06-30"
            },
            {
                "period": "3Q22-YTD",
                "date": "2022-06-30"
            }
        ]
    }
}

Get company period dates

Returns end dates of financial reporting periods for given company

The returned data is the specific date for the end of each financial period for a given company, for that company's history.

HTTP Request

GET https://cognitivecreditapi.com/v1/companies/{companyId}/periods

Path Parameters

Name Type Description Notes
companyId String identifier for the company to fetch period dates for [mandatory]

Return type

Name Type
data PeriodDatesCollection

With a PeriodDatesCollection having the form:

Name Type Description
company_id String Company identifier
generated_at[Deprecated] Date date the data was generated Note: This field is now deprecated.
updated_at Date Update Date
period_dates List[PeriodDate] array list of Reporting Periods and their associated dates

With a PeriodDate having the form:

Name Type Description
period String Reporting Period
date Date end date of the associated Reporting Period

GetCompanyTimeSeries

BASE_PATH=https://cognitivecreditapi.com/v1
COMPANY_ID=adient
TAG=Revenue
INTERVAL=ltm

curl -L -X GET "${BASE_PATH}/companies/${COMPANY_ID}/timeseries/${TAG}/${INTERVAL}" \
-H 'x-api-key: rAjfuEECTrBrAapx0D5WxIHvsey9P7XwIVxtYTQS'

A typical response would be (omitting most of the time_series data):

{
    "data": {
      "company_id": "adient",
      "generated_at": "2023-02-23T11:51:51.402072+00:00",
      "updated_at": "2023-02-23T11:51:51.402072+00:00",
      "interval": "interim",
      "tag": "Revenue",
      "time_series": [
        {
          "id": "YWRpZW50K3Jldm9sdmluZy1jcmF5ZmlzaCs5MDAyMTc1",
          "period": "1Q16",
          "value": "4233"
        },
        {
          "id": "YWRpZW50K3Jldm9sdmluZy1jcmF5ZmlzaCs5MDAxNTk0",
          "period": "2Q16",
          "value": "4298"
        },
        {
          "id": "YWRpZW50K3Jldm9sdmluZy1jcmF5ZmlzaCs5MDAyNDI4",
          "period": "3Q16",
          "value": "4362"
        }
      ]
    }
}

Get company time series

Returns all historical values for a specific comparable for a given company and interval

The returned data is a set of historical values for a particular comparable, for a given company.

error code when reported
COMPANY_NOT_FOUND if there were no timeseries because company is not available in the universe
ANNUAL_REPORTER_INTERIM_TIMESERIES_NOT_AVAILABLE if there were no timeseries because company is annual reporter
TIMESERIES_NOT_FOUND if there were no timeseries for some other reason

HTTP Request

GET https://cognitivecreditapi.com/v1/companies/{companyId}/timeseries/{tag}/{interval}

Path Parameters

Name Type Description Notes
companyId String identifier for the company to fetch time series data [mandatory]
tag String identifier for the comparable tag to fetch time series data for [mandatory]
interval String identifier for the interval of time series data to fetch [mandatory] Allowed values are ltm, annual or interim

Return type

Name Type
data CompanyTimeSeriesCollection

With a CompanyTimeSeriesCollection having the form:

Name Type Description
company_id String Company identifier
generated_at[Deprecated] Date date the data was generated Note: This field is now deprecated.
updated_at Date Update Date
interval String the comparables interval returned, example: Last Twelve Months (LTM)
tag String the specific tag for the returned time series data, example: Revenue
time_series List[TimeSeriesDatapoint] array list of time series datapoints

With a TimeSeriesDatapoint having the form:

Name Type Description
id String unique Identifier
period String Reporting Period
value String numeric value corresponding to the returned tag

Errors

Http Error Codes

The Data API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is invalid, disabled, or not linked to a market.
403 Forbidden -- You are not permitted to access this resource.
404 Not Found -- The requested entity was not found.
406 Not Acceptable -- You requested a format that isn't json.
429 Too Many Requests -- You are being throttled for making too many requests. Try again later at a lower rate (see below for specific limits).
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Request Limits

The current request limits per client are as follows:

Error return type

Typical parsing error:

{
    "error": {
        "code": 400,
        "message": "Invalid timestamp value: '2022-99-17T08:49:16.883091Z'. Please use an ISO-8601 datetime, url encoding if using timezones. e.g. '2022-13-17T08:49:16.883091Z'.",
        "status": "INVALID_PARAMETER_VALUE",
        "details": [
            {
                "exception": "InvalidTimestampStringError()",
                "causes": [
                    "ValueError('month must be in 1..12')"
                ]
            }
        ]
    }
}

An error response may have a body with the form:

Name Type Description
error Error

where Error has the form:

Name Type Description
code Integer Http Status Code
message String Error Summary
status String Error Code
details List[Object] Objects containing error details

Typical validation error:

{
    "message": "Missing required request parameters: [start_timestamp]"
}

Currently, validation errors produce a 400 response with a body of the simple form:

Name Type Description
message String Error Summary
shell