API
This document describes how to use the Denominator API to retrieve data on scores and ratings from Denominator and to instruct Denominator to execute actions. This overview section presents a list of all available function calls.
Before using the API, it is recommended to read the General Information section.
Use of the API
The Denominator API is typically used to retrieve Denominator’s data and scores in a fast and reliable way for integration into clients existing software, data infrastructure, and/or business processes.
Users of the API can for example
Retrieve a company’s DEI performance scores. This applies to both aggregated scores as well as the sub-dimension of DEI like Gender, Race/Ethnicity, Age, and more.
Retrieve core reference data on the company like address, type, ticker, status, and more
Retrieve raw DEI data on companies such as: does the company have a DEI policy, what is their Gender target, what is the retention rate, etc.
Retrieve company DEI ratios such as Female share in Middle Management, Education level of Board, Race/Ethnicity composition of Executives, and more.
Glossary of Terms
Term | Definition |
|---|---|
URI | Universal Resource Identifier – a pointer to a web resource |
HTTP | HyperText Transfer Protocol – the application layer networking protocol by which the World Wide Web operates. |
GET | HTTP method to retrieve data from a server |
POST | HTTP method to send data to a server (and, in this case, to retrieve a response based on that data) |
JSON | JavaScript Object Notation – a standard data-interchange format |
The API is a REST API. We utilize Amazon Web Services (AWS) Lambda functions to pass data to and from the database, through HTTP GET and POST requests.
General Information
Base URI
All customers are assigned the same Base URI: https://externalapi.denominator.one/
Session Authentication Token
Every call to the API requires the use of a per-session authentication token. The token is obtained by calling the Login function before calling any other function during a particular session. The returned token must be included in the x-api-token field in the header of every subsequent call to the API (see boldface text in the response section of the User Login API call below).
Authorization-Token: a JSON Web Token
Accept: application/json
Content-Type: application/json
Data Types
All data values passed to/from the API are of one of the following data types:
Number | An integer of arbitrary length |
String | A string of alphanumeric characters of arbitrary length |
Array | A list of numbers or strings, e.g.- [ “alpha”, “bravo”, “charlie” ] |
JSON Object | A comma-separated list of key:value pairs, where the key is a string and the value may be a number, string, array, or object. |
Input Parameters
Where applicable, our API supports query string parameters (separated from the URI by a ‘?’ and from each other by ‘&’) for GET requests and/or a valid JSON object in the body for POST requests.
Response Parameters
Responses are limited to 5000 entries per page, plus an AWS-enforced reply timeout of 29 seconds and max payload size of 6 MB.
No more than 10,000 API requests per second are accepted globally, excessive requests will be throttled. Server-less architecture with additional backend instances to spin up on a per method basis to address load on a particular API call.
Some responses may include a pagination block, which includes:
pageSize – the maximum number of entries returned per response
pageIndex – the index (0-based) of the current response
pageNumber – the number (1-based) of the current response
pageCount – the total number of pages (1-based) available for the current query
Empty Response
An empty response from the DEI Search function indicates that the inputs were recognized as valid, but that no data exists. e.g.
{
"companies": [],
"pagination": {
"pageSize": 5000,
"pageIndex": 0,
"pageNumber": 1,
"pageCount": 0
}
}
An empty response from the User Login or Request Columns List is not useful and may indicate a problem on the server side.
All general functions are called by appending the function name to the URL prefix
General Functions
User Login
URI | |
HTTP Method | POST |
Request Structure |
|
Response Structure |
|
Sample Request |
|
Sample Response |
|
DEI Search
Used to request company data for a specific set of columns. Array of requested columns is set to columns field of of request body object, and requested DEI IDs of a companies a passed to ids array there. Alternatively, one can use searchPrefix field containing a string prefix of a company name to look for company data. Pagination settings in request object are optional.
Datapoint values are always returned as strings. If a datapoint is a rate, percentage or other possibly non-integer value, it is rounded and formatted with two decimal places. If there could be multiple values for a single datapoint (for example, ISIN codes, stock index tickers, list of educational institutions attended by board members), they are formatted as comma-separated with a whitespace.
URI | |
HTTP Method | POST |
Request Structure |
|
Response Structure |
|
Sample Request |
|
Sample Response |
|
Request Columns List
Used to request the datapoint IDs used for the “columns” field of the search request.
URI | ||
HTTP Method | GET | |
Required Header | x-api-token Uses token from login response (see Session Authorization Token section above) | |
Request Structure |
| |
Response Structure |
| |
Sample Request |
| |
Sample Response |
|
Request API Version
Used to request the version of the API implemented on the server. Could be used to determine if a new minor version of API was deployed.
URI | |
HTTP Method | GET |
Required Header | x-api-token Uses token from login response (see Session Authorization Token section above) |
Request Structure |
|
Response Structure |
|
Sample Request |
|
Sample Response |
|