Security Performance Management
Continuous Monitoring
Cyber Insurance
National Cybersecurity

Articles in this section

See more

GET, POST: Security Rating Details of Companies in Your Portfolio

Avatar
Ingrid
Follow
  • July 30, 2020: Error 413.

⇤ Portfolio

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

Parameter Description Values 
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.

 [String] rating_details 
period
Query		 Specify a time interval to filter the ratings data. [String]
  • daily
  • monthly
  • latest
Example: ?period=monthly
 
start_date
Query		 Filter the ratings data by starting date. [String] The start date [YYYY-MM-DD]. 
end_date
Query		 Filter the ratings data by the end date. [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 -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.

Code Description
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.

Related articles