The Documents House API allows customers to request Environmental, Social, and Governance (ESG) reports for any listed company within our coverage. The API responds with the URL of the requested report and relevant metadata. This documentation provides an overview of the API endpoints, request and response formats, and usage examples.
Getting Started
Base URL
Authentication
All requests to the API must include an API key in the headers for authentication. To obtain an API key, please contact our support team at support@documentshouse.com.
Authorization: Bearer YOUR_API_KEY
The API comes with two endpoints.
1. Get list of all ESG Reports for a company
Lists all available ESG reports for a specified company. You can use this endpoint to get a list of all reports available for a company along with metadata associated with the document and the company.
Endpoints
Endpoint
GET /esg-reports
keyinstn is the unique identifier of a company. You will be provided with a list of companies along with their respective keyinstn. Additionally, you will also be provided with the lookup values for key_doc_category and key_doc_type, should you wish to narrow the results to specified categories and types of ESG reports.
Parameter | Type | Description | Required |
|---|---|---|---|
keyinstn | String | Unique identifier for the company. You will be provided access to our KeyInstn-Company mapping. | Yes |
event_year | Integer | Reporting year of interest. Examples: 2024, 2023. | No |
key_doc_category | Integer | Unique identifier for the category of reports you are interested in. Examples: 1001 for Environmental Disclosures, 1002 for Social Disclosures, 1006 for Third-Party Reports, etc. | No |
key_doc_type | Integer | Unique identifier for the specific type of document you are interested in. Examples: 1001 for Sustainability Report, 1016 for Human Rights Policy, 1042 for EU Taxonomy Report, etc. | No |
include_url | Boolean | True/False. Flag indicating if you need the Document URLs to be included in the response for all documents on the list. When False, you will receive a list of documents along with relevant metadata but without the URL. However, from the list, you can choose the documents you want to request the URLs for and make another call to a different endpoint detailed below. | No |
Example Request
GET /esg-reports?keyinstn=10162
Authorization: Bearer YOUR_API_KEY
Request Parameters
Response Format
Field | Type | Description |
|---|---|---|
keyinstn | string | Unique identifier of a company. |
instn_name | string | Name of a company. |
ticker | string | Ticker of a company. |
keyfile | string | Unique identifier of a company. |
as_reported_doc_title | string | Title of the report as reported by a company. |
doc_category | string | Unique category of a report. Example: Environmental Disclosures, Consolidated Disclosures, Policies and Position, etc. |
doc_type | string | Unique type of a report. Example: Sustainability Report, Independent Assurance Statement, Human Rights Policy, etc. |
event_year | integer | Reporting year. |
language_name | string | Reporting language of a report. |
file_extension | string | File extension of a report. |
doc_url | string | URL to access and download a report. |
country_name | string | Name of country where the company is headquartered. |
exchange_code | string | Exchange code of the exchange the company is listed. |
exchange_name | string | Name of exchange where the company is listed. |
instn_type | string | Type of a company. Example: Public listed, Public unlisted, Private, etc. |
instn_status | string | Current status of a company. Example: Current, Non-current due to M&A, delisting, bankruptcy, name change, reorganization, etc. |
[
{
"keyinstn": "10162",
"instn_name": "Unilever Plc",
"ticker": "UVLR",
"keyfile": "1007237",
"as_reported_doc_title": "Our Sustainability Goals",
"doc_category": "Environmental Disclosures",
"doc_type": "Others",
"event_year": "2023",
"language_name": "English",
"file_extension": ".pdf",
"doc_url": "",
"country_name": "United Kingdom",
"exchange_code": "LSE",
"exchange_name": "London Stock Exchange",
"instn_type": "Listed Public",
"instn_status": "Current"
},
{
"keyinstn": "10162",
"instn_name": "Unilever Plc",
"ticker": "UVLR",
"keyfile": "1007237",
"as_reported_doc_title": "Our Sustainability Goals",
"doc_category": "Environmental Disclosures",
"doc_type": "Others",
"event_year": "2023",
"language_name": "English",
"file_extension": ".pdf",
"doc_url": "",
"country_name": "United Kingdom",
"exchange_code": "LSE",
"exchange_name": "London Stock Exchange",
"instn_type": "Listed Public",
"instn_status": "Current"
},
and other reports for the specified company...
]
Example Response
Get the URL of a specific ESG report that you want to view or download. The previous endpoint provides a list of ESG reports available for a company. After reviewing the list of reports offered by the previous endpoint and selecting one or more reports to view or download, use this endpoint to get the URL of such reports of interest.
2. Get URL of a specific ESG report chosen from the list
GET /esg-report
Using the results from the previous endpoint, extract the keyfile of the report you intend to view or download and pass it as a parameter to this endpoint.
Endpoint
Parameter | Type | Description | Required |
|---|---|---|---|
keyfile | Integer | Unique identifier of a report. Can be picked up from the results of the endpoint that lists all reports available for a specified company. | Yes |
Request Parameters
Example Request
GET /esg-report?keyfile=1007238
Authorization: Bearer YOUR_API_KEY
Response Format
Field | Type | Description |
|---|---|---|
keyfile | Integer | Unique identifier of a report. |
doc_url | String | URL to be used to view or download the report. |
[
{
"keyfile": "1007237",
"doc_url": "https://api.documentshouse.com/redirect/4q28o7-gdf86-42y79t/pdf"
}
]
Example Response
Error Handling
Common Errors
Field | Error Code | Description |
|---|---|---|
500 | SERVER_ERROR | An internal server error occurred. |
404 | NOT_FOUND | The requested report or resource was not found. |
401 | UNAUTHORIZED | The API key is missing or invalid. |
400 | INVALID_REQUEST | The request parameters are invalid. |
Error Response Format
Support
Usage Examples
Example: Listing available Governance reports for a company for the reporting period of 2023
{
"error": {
"code": "ERROR_CODE",
"message": "Detailed error message."
}
}
Example: Requesting the URL of a specific report
{
"error": {
"code": "INVALID_REQUEST",
"message": "The parameter keyinstn is required."
}
}
Example Error Response
GET /esg-reports?keyinstn=1008569&event_year=2023&key_doc_category=1004
Authorization: Bearer YOUR_API_KEY
GET /esg-report?keyfile=1027495
Authorization: Bearer YOUR_API_KEY
For any questions or to address any issues, please contact support@documentshouse.com.
API Documentation
Integrate our library into your products seamlessly
Provide your customers access to our incredible library of ESG reports within your own product. Our API enables you to do that with very little technology development effort.
Documents House provides one-stop, easy and effective access to ESG reports and disclosures of global listed companies. Our continuously expanding library of corporate ESG reports is set to become the most comprehensive and up-to-date library available anywhere in the world. Our mission is driven by our relentless commitment to provide accurate, comprehensive, timely and efficient access to corporate ESG reports. Additionally, we also provide document collection and maintenance as a bespoke service to build and maintain document libraries, ESG and non-ESG related, for your business. Contact us to learn more about how we can help you.
Home
About
Contact
© 2024 Documents House LLC