GET, POST: Security Rating Details of Companies in Your Portfolio – Bitsight Knowledge Base

https://api.bitsighttech.com/ratings/v1/portfolio/ratings

Get security rating details of the companies in your portfolio, including the unique identifiers of particular companies.

Parameters

expand

[Query] Show the letter grades of each risk vector.

This parameter might result in a large amount of data. See error 413 for details.

Value: [String] rating_details

period

[Query] Specify a time interval to filter the ratings data.

Value: [String]

daily
monthly
latest

Example: ?period=monthly

start_date

[Query] Filter the ratings data by starting date.

Value: [String] The start date [YYYY-MM-DD].

end_date

[Query] Filter the ratings data by the end date.

Value: [String] The end date [YYYY-MM-DD].

Example GET Request

Use a GET request to retrieve data for your entire portfolio.

curl -X GET 'https://api.bitsighttech.com/ratings/v1/portfolio/ratings?expand=rating_details&start_date=2021-01-01&end_date=2021-12-01&period=monthly' -u api_token:

Example POST Request

Use a POST to customize the JSON body for the request, i.e., select a subset of companies instead of your entire portfolio.

curl -X POST https://api_token@api.bitsighttech.com/ratings/v1/portfolio/ratings -H "Content-Type: application/json" -d '{"companies":["1b3d260c-9e23-4e19-b3a5-a0bcf67d74d9","a5e23bf0-38d4-4cea-aa50-19ee75da481d"],"start_date":"2021-01-01","end_date":"2021-12-01","expand":"rating_details","period":"monthly"}'

Example Response

[
  {
    "ratings":[
      {
        "date":"2021-10-18",
        "rating":780,
        "percentile":90,
        "risk_vectors":[
          {
            "grade":"C",
            "rating":700,
            "percentile":50,
            "name":"DNSSEC"
          }
        ]
      }
    ],
    "guid":"1b3d260c-9e23-4e19-b3a5-a0bcf67d74d9",
    "name":"Actors Films"
  }
]

Response Attributes

Field					Description
ratings Array					A list of objects containing security rating details of a company.
	Object				Ratings data from a particular date.
		date String [`YYYY‑MM‑DD`]			The date when this rating details object was retrieved.
		rating Integer			The headline security rating of this company on the specified date.
		percentile Integer			For internal Bitsight use. Indicates this company's percentile compared to other companies, with regards to their security rating.
		risk_vectors Array			A list of objects containing risk vector details.
			Object		Risk vector details.
				grade String	The letter grade of this risk vector.
				rating Integer
				percentile Integer	For internal Bitsight use. Indicates this company's percentile compared to other companies, with regards to their risk vector letter grade.
				name String	The name of this risk vector.
guid String [`entity_guid`]					The unique identifier of this company.
name String					The name of this company.

Errors and Status Codes

See common errors and status codes.

413: The amount of data being computed is too high. We recommend making the response smaller either by setting the period parameter value to latest (?period=latest) or by not including the expand parameter.

July 30, 2020: Error 413.