Developer Portal

Using the API

The Morningstar DBRS data API is protected and access-controlled. It is logically separated into a set of distinct services, grouped by function and responsibility. Access to the vast majority of its service endpoints requires a JSON web token, which is obtained by authenticating against the API's auth service.

In order to authenticate, you must be issued a client identifier and client secret. These credentials are used to identify your client as you access the API. Your client is associated with a set of permissions managed by Morningstar DBRS, which is used to allow or restrict access to certain endpoints, resources, and search filters.

It is very important that you do treat this credential pair as you would a normal login and password. If compromised, it can be used to gain access to the API on your behalf. If your credentials are ever compromised, we ask that you contact us promptly and we will reissue your client credentials.

Currently, since the service is in BETA, it is not possible to view or manage these permissions from the client side, and any changes or modifications can be requested by contacting us.

The API is currently read-only, and does not support any operations capable of modifying data. As a result, there is no sandbox environment and all access is granted against the production system.

API Permissions

At the time of account setup, your client will be granted permissions to access only endpoints and resources deemed necessary to your business and function. For example, you may only need to perform searches on documents, and therefore not be granted access to query ratings data or details about our rated companies. More precisely, your search capabilities may only be limited to retrieve research relevant to Europe, which would force your client to always pass an EU region filter when performing a lookup.

Changes to your client's permissions take effect as of the next request issued to the API after the permissions have been updated.

Endpoints and Resources

You would be limited to accessing only the services or endpoints you require. An attempt to access a forbidden endpoint will result in a 403 FORBIDDEN response code. Permissions may also be applied on sub-resources, for example you may be permitted to perform searches against /lookup/v1/documents but not /lookup/v1/marketSectors.

Search Filters

In some circumstances, your client may be limited to searching for content related to certain regions or categories. For example, you may have access to search for documents, but would be restricted to only retrieve Ratings Report document types. In these cases, your client would be required to pass the filter documentType=RatingReport when performing a document lookup against /lookup/v1/documents. Failure to do so will block the search attempt and result in a 403 FORBIDDEN response code.

Getting Started

A typical use case for accessing the data API is that of downloading a research publication, such as a recent Rating Report.

1. Perform an authentication against the Auth Service using your client credentials to obtain a token. To do this, issue a GET request to the /token endpoint.

Request

curl -X GET \
  https://api.dbrs.io/auth/v1/token \
  -H 'x-clientid: 123a4567-b89c-12d3-a456-426655441111' \
  -H 'x-clientsecret: ZGA0YBB0byBiXSBlbmNvZGVk=='

Response

200 OK

{
    "token": "eyJ0eXAiOiJKV1QiL...4_WeE",
    "expiryTimestamp": 
    {
        "iso": "2018-06-27T21:38:44.954707",
        "epoch": 1530135524
    }
}

2. Take note of the token expiry timestamp. Use the token in the Authorization header of the next request, to look for Rating Reports published in the month of May 2018.

Request

curl -X GET \
  'https://api.dbrs.io/lookup/v1/documents?publishStartDate=2018-05-01T00%3A00%3A00Z&publishEndDate=2018-05-31T23%3A59%3A59Z&docType=RatingReport' \
  -H 'authorization: eyJ0eXAiOiJKV1QiL...4_WeE'

Response

200 OK

{
    "documents": [
        {
            "documentKey": "321720.pdf",
            "id": 321720,
            "marketSectors": [...],
            "publishDate": "2018-05-07T15:27:47.000Z",
            "regions": [...],
            "title": "Laurel Road Prime Student Loan Trust 2018-B - Rating Report",
            "types": ["RatingReport"]
            ]
        }
    ],
    "links": [...],
    "result": {
        "count": 1,
        "total": 1
    }
}

3. Take note of the interesting document IDs and query the document service to obtain more details on the publication, along with a download link.

Request

curl -X GET \
  https://api.dbrs.io/document/v1/documents/321720 \
  -H 'authorization: eyJ0eXAiOiJKV1QiL...4_WeE'

Response

200 OK

{
    "documents": [
        {
            "authorNames": [...],
            ...,
            "documentKey": "321720.pdf",
            "documentLink": "https://dbrs.morningstar.com/document/321720.pdf?Expires=1530049796&Signature=SRfiD2...jQqK0_&Key-Pair-Id=APK...KURNQ",
            "documentText": null,
            "id": 321720,
            "marketSectors": [...],
            "publishDate": "2018-05-07T15:27:47.000Z",
            "regions": [...],
            "title": "Laurel Road Prime Student Loan Trust 2018-B - Rating Report",
            "types": ["RatingReport"]
        }
    ],
    "links": [...],
    "result": {
        "count": 1,
        "total": 1
    }
}

4. Follow the document URL to download the research - no Authorization header is necessary for this step, and the URL is already securely signed. The URL is only valid for 90 seconds after it is issued.

Request

wget https://dbrs.morningstar.com/document/321720.pdf?Expires=1530049796&Signature=SRfiD2...jQqK0_&Key-Pair-Id=APK...KURNQ

Response

200 OK

---

Authentication Service

The authentication service allows you to exchange your client identification and secret for a token to use in subsequent API interactions. The token is required to be included in the Authorization header of any request to a privileged service endpoint.

The token expiry period is configurable by Morningstar DBRS for your specific client, much like the permissions associated with your token.

If your token has expired, you will receive a 401 UNAUTHORIZED response code for any request attempted with that invalid token. In this case, the course of action is to obtain a new token from the Authentication Service.

A full breakdown of available endpoints, and how to use them can be found in our API documentation:

Lookup Service

The Lookup Service provides search functionality for a limited set for models in the Morningstar DBRS universe of research and ratings. It is intended to give the client the capability to discover new content, or look up content by specific criteria. For example, the client may want to list all new Rating Reports pertaining to Europe, which have been published by Morningstar DBRS since the beginning of this week.

Since it is a discovery service, the Lookup Service only provides key metadata for the models being searched. To retrieve the complete contents of a Morningstar DBRS document, for example, it is necessary to take note of its identifier and query the Document Service for the full publication.

While the list of filters and searchable resources is continually growing, at the present, the following search criteria are supported for each model below:

Market Sectors

All Morningstar DBRS research is categorized into one or more market sectors, based on the subject of the research. The Lookup Service provides an endpoint to allow the client to discover the full list of Morningstar DBRS market sectors and their identifiers.

More details on Morningstar DBRS market sectors are available on the website: https://dbrs.morningstar.com/sector/

Documents

All research publications created by Morningstar DBRS are referred to as documents. The Lookup Service permits clients to search against Morningstar DBRS's vast database of research using the following criteria:

-- Document Publication Date Range
-- Market Sectors
-- Document Type
-- Region of Interest
-- Search Term

Debts

Morningstar DBRS debts can be searched through the debts endpoint using the following parameters:

-- ISIN
-- CUSIP
-- Rating Publish Date

Search results on the Debts endpoint do not include ratings. In order to get them, a separate call to the Issuer Service should be made.

Issuers

Lookup service also provides an endpoint for searching issuers by providing the issuer LEI or the whole or partial name of the issuer. The following search parameters are exposed by the Issuers endpoint:

-- Search Term
-- Issuer LEI

The lookup service supports pagination of the result set and provides convenient HATEOAS links to scroll through the results.

A full breakdown of available endpoints, and how to use them can be found in our API documentation:

Document Service

The Document Service offers clients the capability to retrieve complete details about a Morningstar DBRS research publication. This includes details about the authors of the publication, along with the a download link to the document file.

Retrieving the document via the Document Service requires an additional step to download the research artifact. The service will provide a documentUrl that must be followed in order to retrieve the PDF, Excel, or other file format. This URL is uniquely and securely generated for your request, and will expire within 90 seconds of issuance, making it suitable for automated or programmatic consumption only. It should not be shared with third parties, because of its limited life span.

Currently, the Document Service only offers the capability to retrieve single documents by their unique identifier, with other conveniences and bulk retrieval options in consideration.

Document Service also provides an endpoint to retrieve the document in RIXML format. This endpoint provide a signed url to a zip archive which includes the original document along with the RIXML file.

A full breakdown of available endpoints, and how to use them can be found in our API documentation:

Issuer Service

A wide range of issuer data, including issuer details, debts, ratings and securities are available through Issuer Service.

Issuer Details

Issuer details can be retrieved by Issuer Endpoint using the Issuer ID.

Issuer Debts

A list of all debts of a specific issuer is provided by the Issuer Debts endpoint. Dept IDs retrieved via this endpoint can be used to get further details and rating of each particular debt.

Debt Details

Details about a specific debt including the ratings and meta data can be retrieved through querying Debts Endpoint by providing the Debt ID.

In order to facilitate retrieval of debts, two additional endpoints exist to query the debt by its ISIN or CUSIP.

Issuer Securities

This endpoint provides applicable ISIN, CUSIP and LEI for any Morningstar DBRS rated issuer

A full breakdown of available endpoints, and how to use them can be found in our API documentation: