Ethos API docs

Endpoint schema

Causes

Retrieve the list of available causes on Ethos

/causes/list

Clients

Retrieve information about clients on Ethos

/clients/get

Companies

Retrieve company-level information, ratings, screens and metrics

/companies/get

/companies/screens/get

/companies/ratings/get

/companies/metrics/get

Retrieve the list of available companies

/companies/list

Compliance

Retrieve information about compliance tests, rules and results

/compliance/results/get

/compliance/rules/get

/compliance/tests/get

Funds

Retrieve fund-level information, ratings and metrics

/funds/get

/funds/screens/get

/funds/ratings/get

/funds/metrics/get

Retrieve the list of available funds

/funds/list

Help

Submit requests for coverage additions or customer support

/help/coverage_requests/get

/help/coverage_requests/create

/help/tickets/get

/help/tickets/create

Metrics

Retrieve the list of available metrics on Ethos

/metrics/list

Portfolios

Retrieve and submit data on one or more of your Portfolios

/portfolios/get

/portfolios/update

/portfolios/holdings/get

/portfolios/holdings/update

/portfolios/ratings/get

Questionnaires

Retrieve and submit data on one or more of your Questionnaires

/questionnaires/get

/questionnaires/responses/get

/questionnaires/questions/get

/questionnaires/answers/get

/questionnaires/approvals/get

Reports

Retrieve and submit data on one or more of your Reports

/reports/get

API Keys

Every firm on Ethos has a unique firm_id and secret that you can use to access the Ethos API. You can find your firm_id and secret under "Keys" in your account on Ethos.

Protocols and headers

The Ethos API uses POST requests to communicate and HTTP response codes to indicate status and errors. All responses come in standard JSON. The Ethos API is served over HTTPS TLS v1.2+ to ensure data privacy. All requests must include a Content-Type of application/json and the body must be valid JSON.

Almost all Ethos API endpoints require a firm_id and secret. These may be sent either in the request body or in the headers ETHOS-FIRM-ID and ETHOS-SECRET.

Every Ethos API response includes a request_id in the returned JSON response (see examples below). The request_id is included regardless of whether or not the API request succeeded or failed. For faster support, include the request_id when contacting support regarding a specific API call.

API host

Development: https://development.ethosesg.com

Staging: https://staging.ethosesg.com

Production: https://production.ethosesg.com

All testing should be done in the Development and Staging environments.

Causes (Topics)

Retrieve a list of causes available on Ethos. Ratings of companies and funds can be scoped to specific causes

In this section

/causes/list

The /causes/list endpoint allows you to receive a list of Causes available on Ethos, with basic information about each Cause.

Causes are returned in alphabetical order by name. There are 45 total Causes available on Ethos; no paging is included in the response.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

A list of cause ids to retrieve data for

[integer]

Example request

/causes/list

curl -X POST https://development.ethosesg.com/causes/list \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"cause_ids": [Integer]
}
}'

Response fields

causes

An array containing the requested causes.

[object]

cause_id

Ethos' unique identifier for the cause

integer

name

Name of the cause

string

description

Short description of the cause

string

problem

Problem statement of the cause, i.e., the problem the cause seeks to address

string

keywords

Keywords associated with the cause

string

total_causes

Number of total causes available based on the request

integer

max_id

Maximum id for all causes matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"causes" : [
{
"cause_id" : 32
"name" : "Sustainable use of water"
"description" : "Promote sustainable management of water everywhere"
"problem" : "Less than 1.2% of all water on earth is available for human use, and the UN projects a 40% shortfall in meeting demand for global water by 2030. More efficient use of water is critical to addressing this shortfall, as well as mitigating the impact of increasing droughts and floods resulting from climate change. Companies play a central role in how water is used, especially in industrial, agricultural, and food industries. Companies can contribute to sustainable water use in several ways, including by reducing water withdrawals, especially in high-stress water regions; setting specific targets for their water use and establishing robust policies for water use and management; engaging with their value chains on sustainable water use; leading on developing and implementing international standards for water use; and setting board and executive compensation incentives to better manage water issues"
"keywords" : "sustainable farming, industrial agriculture, sustainability, access to water, water stress"
}
],
"total_causes" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

Clients

Retrieve data on one or more of your Clients

In this section

/clients/get

The /clients/get endpoint allows you to receive basic data about one or more of your Clients.

Clients are returned in alphabetical order by their name. Results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_clients response body field.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

A list of client ids to retrieve data for

[integer]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

count

The number of clients to fetch.

Default: 100

Minimum: 1

Maximum: 100

integer

offset

The number of clients to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/clients/get

curl -X POST https://development.ethosesg.com/clients/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"count": 100,
"offset": 0
}
}'

Response fields

clients

An array containing the requested clients.

[object]

client_id

Ethos' unique identifier for the client

integer

name

Name of the client

string

updated_at

Date the client record was last updated in Ethos' database, in the format YYYY-MM-DD

string

aum

Client assets under management (AUM)

integer

custodian_id

ID of client record in associated custodian or third-party system

string

total_clients

Number of total clients available based on the request

integer

max_id

Maximum id for all clients matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"clients" : [
{
"client_id" : 55323
"name" : "John Smith",
"updated_at" : "2022-06-19",
"aum" : 1000000,
"custodian_id" : "123456789",
}
],
"offset_clients" : 0 ,
"paged_clients" : 1 ,
"total_clients" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

Companies

Retrieve data on one or more companies, including company information, classification, ESG screens, ratings and metrics.

In this section

/companies/get

/companies/screens/get

/companies/ratings/get

/companies/metrics/get

/companies/list

/companies/get

The /companies/get endpoint allows you to receive data about one or more Companies, including classification, geography, screens (e.g., fossil fuel, gambling or nuclear), and more.

Companies are returned in alphabetical order by standard Ethos name. Due to the potentially large amount of data associated with multiple Companies, results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_companies response body field.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

A list of company ids to retrieve data for

[integer]

symbols

A list of company symbols (tickers) to retrieve company data for

[string]

cusips

A list of cusip numbers to retrieve company data for

[string]

isins

A list of ISIN numbers to retrieve company data for

[string]

uuids

A list of UUID numbers to retrieve company data for

[string]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

portfolio_ids

A list of portfolio IDs to retrieve data for held companies

[integer]

include_price

Whether or not to include price data (delayed 15-minutes) in the returned information

[true/false]

count

The number of companies to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

The number of companies to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/companies/get

curl -X POST https://development.ethosesg.com/companies/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"symbols": [String],
"count": 100,
"offset": 0
}
}'

Response fields

companies

An array containing the requested companies.

[object]

company_id

Ethos' unique identifier for the company. Like all Ethos identifiers, the company_id is case sensitive

integer

name

Name of the company

string

symbol

Unique symbol (ticker) for the company. Like all Ethos identifiers, the symbol is case sensitive

string

cusip

Unique CUSIP number of stock associated with company, if available

string

isin

Unique ISIN number of stock associated with company, if available

string

uuid

Unique UUID field used by ACA Group, if available

string

open_figi

Unique OpenFigi identifier, if available

string

summary_pdf_link

Link to a 3-page summary PDF of the company, if available

string

updated_at

Date the company record was last updated in Ethos' database

string

deleted_at

Date the company record was deleted from Ethos' database (for example, if it was acquired or ceased to operate). After the initial deletion date, a company will stay in Ethos' database for up to 3 months before being fully removed from the API.

string

classifications

A set of fields describing company classification (sector, industry and sub-industry)

object

sector

Sector of the company. Sector is the broadest classification that Ethos uses; potential values are Basic Materials, Consumer Goods, Energy, Financial, Food & Beverage, Healthcare, Industrials, Real Estate, Services, Technology & Communications, Transportation, and Utilities

string

industry

Industry of the company. Industry is a narrower classification than sector

string

sub_industry

Sub-industry of the company. Sub-industry is the narrowest classification that Ethos uses

string

geography

A set of fields describing company geography

object

region

Global region of the company. Possible values are Asia, Europe, North America ex. US, Rest of World, South America, and United States

string

hq_country

Country of company headquarters

string

hq_state

State or province of company headquarters, if available

string

hq_city

City of company headquarters, if available

string

financial

A set of fields describing company financial highlights

object

revenue

Trailing twelve-month revenue

integer

market_value

Market capitalization

integer

market_cap

Market cap category of company. Possible values are micro (less than $300M), small ($300M - $2B), medium ($2B - $10B), large (more than $10B), and mega (more than $200B)

string

net_income

Trailing twelve-month net income

integer

price

Share price of the associated security (delayed 15-minutes). In order to include this in the response, you must set the "include_price" option to "true" in the request.

string

earnings_per_share

Earnings per share

string

return_on_assets

Return on assets

string

return_on_equity

Return on equity

string

net_invested_capital

Total amount of non-financial assets, net of non-financial liabilities

string

dividends_per_share

Sum of declared dividends issued by a company for every ordinary share outstanding

string

net_debt

Short-term debt + long-term debt - cash and cash equivalents

string

cash_and_short_term

Cash and equivalents and short term investments in marketable securities

string

performance

A set of fields describing financial performance (returns) of an associated stock. Please note our terms of use for price and performance data.

object

return_one_day

One-day return of stock price, based on end-of-day prices

string

return_one_week

One-week return of stock price, based on end-of-day prices

string

return_one_month

One-month return of stock price, based on end-of-day prices

string

return_three_months

Three-month return of stock price, based on end-of-day prices

string

return_one_year

One-year return of stock price, based on end-of-day prices

string

return_two_years

Two-year return of stock price, based on end-of-day prices

string

return_three_years

Three-year return of stock price, based on end-of-day prices

string

return_five_years

Five-year return of stock price, based on end-of-day prices

string

executives

A set of fields describing company executives

[object]

name

Executive name

string

title

Executive title

string

is_ceo

Whether or not the executive is CEO of the company

boolean

age

Executive age

integer

pay

Executive compensation for last available year

integer

screens

A set of fields describing whether or not the company fails ESG-related screens

object

advertising

Whether company is involved in advertising as part of its core business model. This typically includes companies with greater than 10% of revenue from advertising.

string

alcohol

Whether company generates significant revenue from the sale of alcohol. This typically means that the company derives more than 1% of its revenue from alcohol-related sales.

string

alcohol_marketing

Whether company generates significant revenue from the sale of alcohol (generally more than 10% of total revenue), and does not have a policy for the responsible marketing of alcohol.

string

animal_treatment

Whether company has been reported to exploit animals or be involved in cruel treatment of animals, as reported by the nonprofit Cruelty Free Investing.

string

anti_abortion

Whether company has been reported to lobby against abortion or donate to politicians or groups working to erode female rights.

string

anti_personnel_mines

Whether company generates revenue from the sale of anti-personnel mines. Anti-personnel landmines are explosive devices designed to be detonated by the presence, proximity, or contact of a person.

string

antisemitism

Whether company has been reported to be involved in antisemitic or anti-Israel activities. Based on publicly-available information.

string

anti_social_publishing

Whether company generates revenue from anti-social publishing (including anti-social internet publishing).

string

arctic_drilling

Whether company is involved in arctic drilling for oil or gas. Does not include service companies or equipment manufacturers.

string

banned_chemicals

Whether company is involved in producing or selling hazardous chemicals or pesticides. "Hazardous chemicals or pesticides" means any substance mentioned by the European Chemicals Agency within the Prior Informed Consent Regulation or any unregulated hazardous chemicals, non-biological pesticides and hazardous wastes, or ozone-depleting substances as covered by the Montreal Protocol on Substances that Deplete the Ozone Layer (1989) or any similar international treaties (such as polychlorinated biphenyl, dichlorodiphenyltrichloroethane, chlorofluorocarbons, halons and asbestos).

string

banned_pharmaceuticals

Whether company has been reported to be involved in production or trade in controlled substances or pharmaceuticals subject to international ban.

string

biological_chemical_weapons

Whether company has been reported to be involved in producing or selling biological or chemical weapons. Biological and toxin weapons are either microorganisms like virus, bacteria or fungi, or toxic substances produced by living organisms that are produced and released deliberately to cause disease and death in humans, animals or plants. Chemical weapons are chemicals used to cause intentional death or harm through their toxic properties.

string

cannabis

Whether company is involved in the cannabis industry as part of its business model.

string

carbon_emissions_intensity

Whether company's carbon emissions intensity is significantly higher than peers. Carbon intensity is measured as (Scope 1 and 2 emissions) / $M revenue. Threshold for failing this screen is emissions intensity greater than 1 standard deviation above peer average.

string

carbon_underground

Whether company fails the Carbon Underground 200 (CU200) screen. The CU200 identifies the top 200 global publicly-listed coal, oil, and gas reserves owners ranked by the carbon emissions embedded in their reserves.

string

cu_coal

Whether company fails the Carbon Underground 200 (CU200) coal screen. The coal screen identifies the top global publicly-listed coal reserves owners ranked by the carbon emissions embedded in their reserves.

string

cu_oil_gas

Whether company fails the Carbon Underground 200 (CU200) oil and gas screen. The oil and gas screen identifies the top global publicly-listed oil and gas reserves owners ranked by the carbon emissions embedded in their reserves.

string

cu_tar_sands

Whether company fails the Carbon Underground 200 (CU200) tar sands screen. The tar sand screen identifies the top global publicly-listed tar sand reserves owners ranked by the carbon emissions embedded in their reserves.

string

cu_thermal_coal

Whether company fails the Carbon Underground 200 (CU200) thermal coal screen. The thermal coal screen identifies the top global publicly-listed thermal coal reserves owners ranked by the carbon emissions embedded in their reserves.

string

child_safety

Whether company has been involved in controversies related to child safety, including areas such as child labor, child exploitation, human trafficking, stolen identity, deep fakes, or other abuse of children. Based on ongoing monitoring of news stories and public information.

string

cluster_munitions

Whether company generates revenue from the sale of cluster munitions. Cluster munitions are munitions designed to disperse or release explosive submunitions or bomblets. Cluster munitions pose a threat to civilians during conflict by randomly scattering submunitions over a wide area. They pose a threat post-conflict by leaving submunitions that fail to explode upon impact and become de facto landmines. The 2008 Convention on Cluster Munitions prohibits the use, production, transfer, and stockpiling of cluster munitions.

string

coal

Whether company's primary business model involves coal mining, including thermal or metallurgical (coking).

string

conflict_minerals

Whether company generates revenue from the extraction or trading of minerals, coal and uranium from conflict areas.

string

contraceptives

Whether company manufactures contraceptives or derives significant revenue from selling contraceptives.

string

controversial_weapons

Whether company generates significant revenue from the sale of controversial weapons. Controversial weapons include weapons of mass destruction (chemical, biological and nuclear weapons), cluster munitions, antipersonnel mines, incendiary weapons, and other weapons considered to be excessively injurious, to have indiscriminate effects, or to damage the natural environment.

string

deforestation_financing

Whether company is a major financer of deforestation. Defined as providing more than $100M USD to companies involved in deforestation.

string

deforestation_supply_chain

Whether company is involved in deforestation in its supply chain and has been rated in the bottom two quintiles (lower 40%) by publicly-available sources.

string

depleted_uranium

Whether company has been reported to be involved in producing or selling depleted uranium. Depleted uranium is a dense metal produced as a by-product of enrichment of natural uranium for nuclear fuel. It is still radioactive, but at a much lower level than the starting material. It is used in armour-piercing shells and bombs, to give them more penetrating power.

string

discrimination_cont

Whether company has been involved in a "severe" or "very severe" controversy related to customer or employee discrimination over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".

string

electrical_utility

Whether company derives revenue from electrical utility activities.

string

endangered_wildlife

Whether company derives revenue from trade in endangered wildlife; any species described as "endangered" or "critically endangered" in the most recent publication of the International Union for Conservation of Nature (IUCN) Red List; or any species subject to protection under the Convention on International Trade in Endangered Species of Wild Fauna and Flora (1973).

string

environmental_cont

Whether company has been involved in a "very severe" controversy related to the environment over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".

string

eu_sanctions

Whether company is included in the European Union (EU) sanctions list. The EU uses restrictive measures, or sanctions, to promote the objectives of the Common Foreign and Security Policy (CFSP). These include safe-guarding the EU's values, its fundamental interests and security; consolidating and supporting democracy, the rule of law, human rights and the principles of international law; preserving peace; preventing conflicts and strengthening international security. This screen includes only companies specifically listed by the EU.

string

factory_farming

Whether company has been reported to use factory farming in its supply chain.

string

fast_food

Whether company is involved in the fast-food industry, and derives at least 10% of its revenue from fast food.

string

firearms

Whether company generates significant revenue from production or sale of firearms intended for civilian (non-military) use. This typically means deriving more than 1% of revenue from such sales. Firearms include handguns, pistols, shotguns, rifles, revolvers, and ammunition.

string

food_commodity_derivatives

Whether company is involved in food commodity derivatives trading or speculative transactions that may contribute to price inflation in basic agricultural or marine commodities (e.g., wheat, rice, meat, soy, sugar, dairy, fish, corn).

string

for_profit_health

Whether company is a for-profit healthcare provider. Includes for-profit hospitals, home healthcare providers, long-term care providers, and other specialty providers. Does not include pharmaceutical companies, biotech, medical equipment manufacturers, distributors, or other healthcare companies that are not directly involved in providing care.

string

fossil_fuel

Whether company is involved in fossil fuel production or distribution. Includes oil and gas companies, coal companies, and utilities that use fossil fuels.

string

fur

Whether company produces or sells fur as a part of its business model.

string

gambling

Whether company generates significant revenue from gambling-related activities. This typically means that the company derives more than 1% of its revenue from gambling-related activities.

string

genetic_engineering

Whether company uses genetic engineering in its product development or other research.

string

health_cont

Whether company has been involved in a "very severe" controversy related to health and well-being over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".

string

human_rights_cont

Whether company has been involved in a "very severe" controversy related to human rights or involvement with an oppressive government over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".

string

human_trafficking

Whether company has been reported to be involved in human trafficking over the past 5 years, either directly or through its supply chain.

string

illegal_activities

Whether company has products or activities that are deemed illegal under international law or local law where it is headquartered (including recreational cannabis).

string

ilo

Whether company has been involved in a "severe" or "very severe" controversy related to violations of the International Labor Organization (ILO) Conventions. Conventions cover areas such as basic human rights, minimum wages, industrial relations, employment policy, social dialogue, social security and other issues.

string

interest_based

Whether company offers an interest-based financial product as part of its business model.

string

interest_bearing_debt

Whether company's debt-to-market-cap ratio is greater than 30%.

string

interest_bearing_securities

Whether company's ratio of interest-bearing securities to market cap is greater than 30%. This is calculated as (cash and equivalents and short-term investments) / market cap.

string

iran

Whether company has been reported to have involvement in Iran over the past 5 years, either through operations, investment, or partnership with an Iranian entity. Indicates reported involvement, and not necessarily any violation of sanctions

string

land_use_biodiversity

Whether company has faced "high" or "severe" controversies related to land use or biodiversity. Also includes companies that work with soy, cattle or timber and have been reported to have a significant negative impact on deforestation.

string

military_contracting

Whether company generates revenue from military contracts related to weapons or combat operations.

string

misleading_communication

Whether company has been involved in a "severe" or "very severe" controversy related to misleading communication over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".

string

music

Whether company is involved in producing, distributing or selling music as part of its business model.

string

myanmar

Whether company has been reported to have involvement with Myanmar (Burma), or has been reported to support the military government in Myanmar as a supplier or funder. Indicates reported involvement, and not necessarily any violation of sanctions

string

non_sustainable_palm_oil

Whether company is involved in non-sustainable palm-oil production or distribution. Defined as a) not having achieved or committed to achieve Roundtable on Sustainable Palm Oil (RSPO) certification or other internationally-recognized sustainable palm oil certifications, and b) any of the following: involvement in unresolved land rights conflicts, inability to prove the legality of operations, no undertaking of social and environmental impact assessments, not consulting with stakeholders prior to commencing operations, or involvement in illegal logging.

string

norges_bank

Whether company is on the exclusion list created by Norges Bank, the central bank of Norway. The exclusion list is based on recommendations from Norway's Council on Ethics.

string

northern_ireland

Whether company has operations in Northern Ireland and may not be compliant with the Macbride Principles, based on publicly-available information. Based in part on analysis by the Equality Commission for Northern Ireland covering companies with at least 25 employees in Northern Ireland.

string

north_korea

Whether company has been reported to have involvement in North Korea in the past 5 years, either through operations, investment, or partnership with a North Korean entity. Indicates reported involvement, and not necessarily any violation of sanctions

string

no_sbti

Whether company has committed to a "science-based" target to reduce its emissions in line with the Paris Agreement on climate change mitigation. Uses data from the Science-Based Targets Initiative (SBTI).

string

nuclear

Whether company generates nuclear power or provides supplies enabling nuclear power.

string

oecd

Whether company has been involved in a "severe" or "very severe" controversy related to violations of the Organization for Economic Cooperation and Development (OECD) Guidelines for Multinational Enterprises. The guidelines are "non-binding principles and standards for responsible business conduct in a global context consistent with applicable laws and internationally recognised standards."

string

oil_and_gas

Whether company is involved in oil and gas industries. Includes companies involved in the exploration, production, distribution, or marketing of oil and gas.

string

opioid_cont

Whether company has been reported to be involved in the opiod crisis in the United States.

string

oppressive_cont

Whether company has been involved in a "severe" or "very severe" controversy with an oppressive government over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".

string

palestinian_human_rights

Whether company has been reported to be involved in human rights violations against the Palestinian people. Based on publicly-available information.

string

pharma_cont

Whether company has been reported to be involved in pharmaceutical-related controversies such as price-gouging or the opioid crisis.

string

pork

Whether company produces or sells pork as part of its business model.

string

pornography

Whether a core part of company's business seeks to appeal to a prurient interest in sex or to incite sexual excitement. Includes companies that produce pornographic material as well as companies that feature adult entertainment, such as casinos.

string

predatory_lending

Whether company has been reported to engage in predatory lending.

string

prison_involvement

Whether company is involved in private prisons or immigrant detention. Involvement defined as direct involvement in the operations of a prison or a prison 'harm score' of 11 or higher from the nonprofit organization Worth Rises.

string

privacy_cont

Whether company has been involved in a "severe" or "very severe" controversy related to privacy over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".

string

pro_life

Whether company directly participates in or enables abortion. Direct participation may include manufacturing of abortifacients and health care companies that perform abortions when not required to by law.

string

russia

Whether company is headquartered in Russia, has significant operations in Russia, or has significant ties (such as a joint venture or major investment) with Russian companies.

string

single_use_plastic

Whether company produces or sells single-use plastic items as part of its business model.

string

stem_cell

Whether company performs research on human fetuses or embryos that results in the end of pre-natal life, makes use of tissue derived from abortions, or otherwise violates the dignity of a developing person.

string

sudan

Whether company has been reported to have involvement in Sudan over the past 5 years, either through operations, investment, or partnership with a Sudanese entity. Indicates reported involvement, and not necessarily any violation of sanctions

string

sugar

Whether company produces or sells sugary products as part of its business model.

string

syria

Whether company has been reported to have involvement in Syria over the past 5 years, either through operations, investment, or partnership with a Syrian entity. Indicates reported involvement, and not necessarily any violation of sanctions

string

tar_sands

Whether company is involved in the extraction of tar sands, sometimes called oil sands.

string

thermal_coal

Whether company's primary business model involves thermal coal mining.

string

tobacco

Whether company generates significant revenue from tobacco-related sales. This typically means deriving more than 1% of revenue from tobacco-related sales.

string

tobacco_gics

Whether is classified under the GICS Sub-Industry of Tobacco. GICS defines this Sub-Industry as "Manufacturers of cigarettes and other tobacco products such as e-cigarettes. This Sub-Industry excludes companies primarily engaged in producing cannabis related products."

string

uk_sanctions

Whether company is included in the United Kingdom's sanctions list (companies designated or specified under regulations made under the Sanctions and Anti-Money Laundering Act 2018). This screen includes only companies specifically listed by the UK.

string

undermining_us_elections

Whether company has been reported to donate to US members of Congress who voted not to certify the 2020 election results. Data from the transparency group Accountable.US.

string

ungc

Whether company has been involved in a "severe" or "very severe" controversy related to violations of the United Nations Global Compact principles. Principles cover areas such as human rights, freedom from forced labor and discrimination, anti-corruption, and environmental protection.

string

ungp

Whether company has been involved in a "severe" or "very severe" controversy related to violations of the United Nations Guiding Principles (UNGP) on Business and Human Rights. The UNGP's foundational principle for businesses is that they should respect human rights, meaning "they should avoid infringing on the human rights of others and should address adverse human rights impacts with which they are involved."

string

us_ofac

Whether company is included in sanctions lists from the United States Office of Foreign Assets Control (OFAC), including the list of Specially Designated Nationals (SDNs) and non-SDN lists, or the Bureau of Industry and Security Entity List. This screen includes only companies specifically listed by the US.

string

weapons

Whether company generates significant revenue from weapons-related sales, including "conventional" weapons and "controversial" weapons. Controversial weapons include weapons of mass destruction (chemical, biological and nuclear weapons), cluster munitions, antipersonnel mines, incendiary weapons, and other weapons considered to be excessively injurious, to have indiscriminate effects, or to damage the natural environment.

string

offset_companies

Number of companies offset in the request

integer

paged_companies

Number of paged companies returned

integer

total_companies

Number of total companies available based on the request

integer

max_id

Maximum id for all companies matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"companies" : [
{
"company_id" : 553
"name" : "Apple",
"symbol" : "AAPL",
"cusip", : "37833100",
"isin" : "US0378331005",
"uuid" : "II|V1|FactSetId|000C7F-E|17",
"open_figi" : "BBG000B9XRY4",
"summary_pdf_link" : "https://....pdf",
"updated_at" : "2022-06-19",
"deleted_at" : null,
"price" : "200.5",
"classifications" : {
"sector" : "Technology & Communications",
"industry" : "Software & Services",
"sub_industry" : "Big Tech - Major Diversified",
}
"geography" : {
"region" : "United States",
"hq_country" : "United States",
"hq_state" : "California",
"hq_city" : "Cupertino",
}
"financial" : {
"revenue" : 347155005440,
"market_value" : 2457875513344,
"market_cap" : "mega",
"net_income" : 100555000000,
"price" : "168.64",
"earnings_per_share" : "6.015",
"return_on_assets" : "0.2",
"return_on_equity" : "1.46",
"net_invested_capital" : 194730000000,
"dividends_per_share" : "0.865",
"net_debt" : 85679000000,
"cash_and_short_term" : 63913000000,
}
"performance" : {
"return_one_day" : "-2.102473",
"return_one_week" : "-5.29824",
"return_one_month" : "-3.678318",
"return_three_months" : "14.046122",
"return_one_year" : "24.975637",
"return_two_years" : "108.424224",
"return_three_years" : "304.289341",
"return_five_years" : "369.4877506",
}
"executives" : [{
"name" : "Mr. Timothy D. Cook",
"title" : "CEO & Director",
"is_ceo" : true,
"age" : 61,
"pay" : 16386559,
]}
"screens" : {
"advertising" : pass,
"alcohol" : pass,
"animal_testing" : pass,
"cannabis" : pass,
"carbon_emissions_intensity" : pass,
"coal" : pass,
"contraceptives" : pass,
"deforestation_financing" : pass,
"deforestation_supply_chain" : pass,
"discrimination_cont" : pass,
"environmental_cont" : pass,
"factory_farming" : pass,
"fast_food" : pass,
"fossil_fuel" : pass,
"fur" : pass,
"gambling" : pass,
"genetic_engineering" : pass,
"health_cont" : pass,
"human_trafficking" : fail,
"interest_based" : pass,
"interest_bearing_debt" : pass,
"interest_bearing_securities" : pass,
"misleading_communication" : pass,
"music" : pass,
"no_sbti" : pass,
"nuclear" : pass,
"oil_and_gas" : pass,
"opioid_cont" : pass,
"oppressive_cont" : fail,
"pork" : pass,
"pornography" : pass,
"predatory_lending" : pass,
"prison_involvement" : pass,
"privacy_cont" : fail,
"pro_life" : pass,
"single_use_plastic" : pass,
"stem_cell" : pass,
"sugar" : pass,
"tobacco" : pass,
"weapons" : pass
}
}
],
"offset_companies" : 0 ,
"paged_companies" : 1 ,
"total_companies" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

/companies/screens/get

The /companies/screens/get endpoint allows you to receive ESG Screens data about one or more Companies.

You must specify at least one Company identifier (symbol, CUSIP, ISIN or UUID).

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

A list of company ids to retrieve data for

[integer]

symbols

A list of company symbols (tickers) to retrieve company data for

[string]

cusips

A list of cusip numbers to retrieve company data for

[string]

isins

A list of ISIN numbers to retrieve company data for

[string]

uuids

A list of UUID numbers to retrieve company data for

[string]

portfolio_ids

A list of portfolio IDs to retrieve data for held companies

[integer]

count

The number of companies to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

offset

The number of companies to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/companies/screens/get

curl -X POST https://development.ethosesg.com/companies/screens/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"symbols": [String],
"count": 100,
"offset": 0
}
}'

Response fields

companies

An array containing the requested companies.

[object]

company_id

Ethos' unique identifier for the company. Like all Ethos identifiers, the company_id is case sensitive

integer

symbol

Unique symbol (ticker) for the company. Like all Ethos identifiers, the symbol is case sensitive

string

cusip

Unique CUSIP number of stock associated with company, if available

string

isin

Unique ISIN number of stock associated with company, if available

string

uuid

Unique UUID field used by ACA Group, if available

string

open_figi

Unique OpenFigi identifier, if available

string

name

Name of the company

string

updated_at

Date the company record was last updated in Ethos ESG's database

string

screens

A set of fields describing whether or not the company fails ESG-related screens, as well as percent of revenue derived from each screened activity

object

advertising

Whether company is involved in advertising as part of its core business model. This typically includes companies with greater than 10% of revenue from advertising.

object

alcohol

Whether company generates significant revenue from the sale of alcohol. This typically means that the company derives more than 1% of its revenue from alcohol-related sales.

object

alcohol_marketing

Whether company generates significant revenue from the sale of alcohol (generally more than 10% of total revenue), and does not have a policy for the responsible marketing of alcohol.

object

animal_treatment

Whether company has been reported to exploit animals or be involved in cruel treatment of animals, as reported by the nonprofit Cruelty Free Investing.

object

anti_abortion

Whether company has been reported to lobby against abortion or donate to politicians or groups working to erode female rights.

object

anti_personnel_mines

Whether company generates revenue from the sale of anti-personnel mines. Anti-personnel landmines are explosive devices designed to be detonated by the presence, proximity, or contact of a person.

object

antisemitism

Whether company has been reported to be involved in antisemitic or anti-Israel activities. Based on publicly-available information.

object

anti_social_publishing

Whether company generates revenue from anti-social publishing (including anti-social internet publishing).

object

arctic_drilling

Whether company is involved in arctic drilling for oil or gas. Does not include service companies or equipment manufacturers.

object

banned_chemicals

object

banned_pharmaceuticals

Whether company has been reported to be involved in production or trade in controlled substances or pharmaceuticals subject to international ban.

object

biological_chemical_weapons

object

cannabis

Whether company is involved in the cannabis industry as part of its business model.

object

carbon_emissions_intensity

object

carbon_underground

object

cu_coal

object

cu_oil_gas

object

cu_tar_sands

object

cu_thermal_coal

object

child_safety

object

cluster_munitions

object

coal

Whether company's primary business model involves coal mining, including thermal or metallurgical (coking).

object

conflict_minerals

Whether company generates revenue from the extraction or trading of minerals, coal and uranium from conflict areas.

object

contraceptives

Whether company manufactures contraceptives or derives significant revenue from selling contraceptives.

object

controversial_weapons

object

deforestation_financing

Whether company is a major financer of deforestation. Defined as providing more than $100M USD to companies involved in deforestation.

object

deforestation_supply_chain

Whether company is involved in deforestation in its supply chain and has been rated in the bottom two quintiles (lower 40%) by publicly-available sources.

object

depleted_uranium

object

discrimination_cont

object

electrical_utility

Whether company derives revenue from electrical utility activities.

object

endangered_wildlife

object

environmental_cont

object

eu_sanctions

object

factory_farming

Whether company has been reported to use factory farming in its supply chain.

object

fast_food

Whether company is involved in the fast-food industry, and derives at least 10% of its revenue from fast food.

object

firearms

object

food_commodity_derivatives

object

for_profit_health

object

fossil_fuel

Whether company is involved in fossil fuel production or distribution. Includes oil and gas companies, coal companies, and utilities that use fossil fuels.

object

fur

Whether company produces or sells fur as a part of its business model.

object

gambling

Whether company generates significant revenue from gambling-related activities. This typically means that the company derives more than 1% of its revenue from gambling-related activities.

object

genetic_engineering

Whether company uses genetic engineering in its product development or other research.

object

health_cont

object

human_rights_cont

object

human_trafficking

Whether company has been reported to be involved in human trafficking over the past 5 years, either directly or through its supply chain.

object

illegal_activities

Whether company has products or activities that are deemed illegal under international law or local law where it is headquartered (including recreational cannabis).

object

ilo

object

interest_based

Whether company offers an interest-based financial product as part of its business model.

object

interest_bearing_debt

Whether company's debt-to-market-cap ratio is greater than 30%.

object

interest_bearing_securities

Whether company's ratio of interest-bearing securities to market cap is greater than 30%. This is calculated as (cash and equivalents and short-term investments) / market cap.

object

iran

object

land_use_biodiversity

object

military_contracting

Whether company generates revenue from military contracts related to weapons or combat operations.

object

misleading_communication

object

music

Whether company is involved in producing, distributing or selling music as part of its business model.

object

myanmar

object

non_sustainable_palm_oil

object

norges_bank

Whether company is on the exclusion list created by Norges Bank, the central bank of Norway. The exclusion list is based on recommendations from Norway's Council on Ethics.

object

northern_ireland

object

north_korea

object

no_sbti

object

nuclear

Whether company generates nuclear power or provides supplies enabling nuclear power.

object

oecd

object

oil_and_gas

Whether company is involved in oil and gas industries. Includes companies involved in the exploration, production, distribution, or marketing of oil and gas.

object

opioid_cont

Whether company has been reported to be involved in the opiod crisis in the United States.

object

oppressive_cont

object

palestinian_human_rights

Whether company has been reported to be involved in human rights violations against the Palestinian people. Based on publicly-available information.

object

pharma_cont

Whether company has been reported to be involved in pharmaceutical-related controversies such as price-gouging or the opioid crisis.

object

pork

Whether company produces or sells pork as part of its business model.

object

pornography

object

predatory_lending

Whether company has been reported to engage in predatory lending.

object

prison_involvement

object

privacy_cont

object

pro_life

object

russia

Whether company is headquartered in Russia, has significant operations in Russia, or has significant ties (such as a joint venture or major investment) with Russian companies.

object

single_use_plastic

Whether company produces or sells single-use plastic items as part of its business model.

object

stem_cell

object

sudan

object

sugar

Whether company produces or sells sugary products as part of its business model.

object

syria

object

tar_sands

Whether company is involved in the extraction of tar sands, sometimes called oil sands.

object

thermal_coal

Whether company's primary business model involves thermal coal mining.

object

tobacco

Whether company generates significant revenue from tobacco-related sales. This typically means deriving more than 1% of revenue from tobacco-related sales.

object

tobacco_gics

object

uk_sanctions

object

undermining_us_elections

Whether company has been reported to donate to US members of Congress who voted not to certify the 2020 election results. Data from the transparency group Accountable.US.

object

ungc

object

ungp

object

us_ofac

object

weapons

object

offset_companies

Number of companies offset in the request

integer

paged_companies

Number of paged companies returned

integer

total_companies

Number of total companies available based on the request

integer

max_id

Maximum id for all companies matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"companies" : [
{
"company_id" : 553,
"symbol" : "AAPL",
"cusip" : "37833100",
"isin" : "US0378331005",
"uuid" : "II|V1|FactSetId|000C7F-E|17",
"open_figi" : "BBG000B9XRY4",
"name" : "Apple",
"updated_at" : "2022-06-19"
"screens" : {
"advertising" : {
"pass" : "false",
"revenue_percent" : 0.157,
"updated_at" : "2022-06-19"
},
"alcohol" : {
"pass" : "true",
"revenue_percent" : 0,
"updated_at" : "2022-06-19"
},
"animal_testing" : {
"pass" : "true",
"revenue_percent" : 0,
"updated_at" : "2022-06-19"
},
"cannabis" : {
"pass" : "true",
"revenue_percent" : 0,
"updated_at" : "2022-06-19"
},
"carbon_emissions_intensity" : {
"pass" : "true",
"revenue_percent" : 0,
"updated_at" : "2022-06-19"
},
"..." : {
"pass" : "true",
"revenue_percent" : 0,
"updated_at" : "2022-06-19"
}
}
}
],
"offset_companies" : 0 ,
"paged_companies" : 1 ,
"total_companies" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

/companies/ratings/get

The /companies/ratings/get endpoint allows you to receive ESG Ratings data about one or more Companies.

You must specify at least one Company identifier (symbol, CUSIP, ISIN, UUID, or portfolio_ids). Optionally specify the id of a cause (topic) you want to retrieve a Rating for. Defaults to returning ratings for all causes on Ethos.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An object to be used with the request.

object

ids

A list of company ids to retrieve data for

[integer]

symbols

A list of company symbols (tickers) to retrieve company data for

[string]

cusips

A list of cusip numbers to retrieve company data for

[string]

isins

A list of ISIN numbers to retrieve company data for

[string]

uuids

A list of UUID numbers to retrieve company data for

[string]

portfolio_ids

A list of portfolio IDs to retrieve data for held companies

[integer]

cause_ids

A list of cause_ids to retrieve company data for. If not specified, ratings for all causes for requested companies will be returned

[integer]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

count

The number of companies to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

Example request

/companies/ratings/get

curl -X POST https://development.ethosesg.com/companies/ratings/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"symbols": [String],
"count": 100,
"offset": 0
}
}'

Response fields

companies

An array containing the requested companies.

[object]

company_id

Ethos' unique identifier for the company. Like all Ethos identifiers, the company_id is case sensitive

integer

symbol

Unique symbol (ticker) for the company. Like all Ethos identifiers, the symbol is case sensitive

string

cusip

Unique CUSIP number of stock associated with company, if available

string

isin

Unique ISIN number of stock associated with company, if available

string

uuid

Unique UUID field used by ACA Group, if available

string

open_figi

Unique OpenFigi identifier, if available

string

name

Name of the company

string

updated_at

Date the company record was last updated in Ethos ESG's database

string

ratings

A set of fields describing ESG ratings associated with the company

object

cause

Name of the cause or "Impact Persona" for which the company is rated. Impact Personas are combinations of causes based on what a client or lead selects in their Impact Assessment.

string

cause_id

Unique id of the cause. Note that this field does not apply to "Impact Personas" (combinations of causes). This field will be a null value for Impact Personas.

integer

client_persona

Whether or not the cause is an Impact Persona of one or more of your clients or leads. Impact Personas can reflect a single cause or multiple causes, depending on what the client selects in their Impact Assessment.

boolean

date

Date of the rating

date

score

Score of the rating, from 0 (worst) to 100 (best)

integer

rank

Rank of the rating, compared to all companies

integer

percentile

Percentile of the rating, compared to all companies

integer

offset_companies

Number of companies offset in the request

integer

paged_companies

Number of paged companies returned

integer

total_companies

Number of total companies available based on the request

integer

max_id

Maximum id for all companies matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"companies" : [
{
"company_id" : 553,
"symbol" : "AAPL",
"cusip" : "37833100",
"isin" : "US0378331005",
"uuid" : "II|V1|FactSetId|000C7F-E|17",
"open_figi" : "BBG000B9XRY4",
"name" : "Apple",
"updated_at" : "2022-06-19",
"ratings" : [
{
"cause" : "Gender equality",
"cause_id" : "37",
"updated_at" : "2022-06-19",
"score" : 84.1,
"rank" : 119,
"percentile" : 0.85
}
]
}
],
"offset_companies" : 0 ,
"paged_companies" : 1 ,
"total_companies" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

/companies/metrics/get

The /companies/metrics/get endpoint allows you to receive ESG Metrics data about one or more Companies.

You must specify at least one Company identifier (symbol, CUSIP, ISIN or UUID). Optionally specify the id of a Metric you want to retrieve data for. Defaults to all Metrics on Ethos.

Companies are returned in alphabetical order by standard Ethos name. Due to the potentially very large amount of data associated with multiple Companies, results are paginated in groups of max 10. Manipulate the count and offset parameters in conjunction with the total_companies response body field.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An object to be used with the request.

object

ids

A list of specific metric record ids to retrieve data for (the combination of metric, company and date). Note this is the "record_id" field in the response

[integer]

metric_ids

A list of metric ids to retrieve data for

[integer]

company_ids

A list of company ids to retrieve data for

[integer]

symbols

A list of company symbols (tickers) to retrieve company data for

[string]

cusips

A list of cusip numbers to retrieve company data for

[string]

isins

A list of ISIN numbers to retrieve company data for

[string]

uuids

A list of UUID numbers to retrieve company data for

[string]

portfolio_ids

A list of portfolio IDs to retrieve data for held companies

[integer]

metric_ids

A list of metric_ids to retrieve company data for. If not specified, all metrics for requested companies will be returned

[integer]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

count

The number of companies to fetch.

Default: 10

Minimum: 1

Maximum: 10

integer

Example request

/companies/metrics/get

curl -X POST https://development.ethosesg.com/companies/metrics/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"symbols": [String],
"count": 100,
"offset": 0
}
}'

Response fields

companies

An array containing the requested companies.

[object]

company_id

Ethos' unique identifier for the company. Like all Ethos identifiers, the company_id is case sensitive

integer

symbol

Unique symbol (ticker) for the company. Like all Ethos identifiers, the symbol is case sensitive

string

cusip

Unique CUSIP number of stock associated with company, if available

string

isin

Unique ISIN number of stock associated with company, if available

string

uuid

Unique UUID field used by ACA Group, if available

string

open_figi

Unique OpenFigi identifier, if available

string

name

Name of the company

string

updated_at

Date the company record was last updated in Ethos ESG's database

string

metrics

A set of fields describing ESG metrics associated with the company

object

record_id

Unique id of the specific metric record (for the company, metric and date combination)

integer

metric_id

Unique id of the metric

integer

name

Name of the metric

string

description

Short description of the metric

string

link

Link to metric source, if available

string

uom

Unit of measure of the metric

string

date

Date of the data point

string

esg_category

Primary ESG category of the metric (environment, social or governance)

string

score_base

Base score of the metric, measured according to the unit of measure

integer

normalization_scope

Whether the metric is normalized relative to peers, all companies, or not at all

string

score_normalized

Normalized score of the metric (on a 0-100 scale)

integer

peer_value

Whether or not the score is based on an average of its sub-industry. Ethos uses peer averages when no data is available for a company

boolean

offset_companies

Number of companies offset in the request

integer

paged_companies

Number of paged companies returned

integer

total_companies

Number of total companies available based on the request

integer

max_id

Maximum id for all companies matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"companies" : [
{
"company_id" : 553,
"symbol" : "AAPL",
"cusip" : "37833100",
"isin" : "US0378331005",
"uuid" : "II|V1|FactSetId|000C7F-E|17",
"open_figi" : "BBG000B9XRY4",
"name" : "Apple",
"updated_at" : "2022-06-19",
"metrics" : [
{
"record_id" : "22434202",
"metric_id" : "224",
"name" : "Advertising fines and violations",
"description" : "Sum of fines incurred over the past four years from the Federal Trade Commission, related to advertising",
"link" : "https://www.goodjobsfirst.org/violation-tracker",
"uom" : "$ fines",
"updated_at" : "2022-06-30",
"esg_category" : "social",
"score_base" : 113000000,
"score_normalized" : 0,
"peer_value" : false
}
]
}
],
"offset_companies" : 0 ,
"paged_companies" : 1 ,
"total_companies" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

/companies/list

The /companies/list endpoint allows you to receive a list of Companies available on Ethos, with basic identifiers for each Company.

Companies are returned in alphabetical order by name. No paging is included in the response.

If you would like more detailed information about a company, use the /companies/get endpoint below.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

A list of company ids to retrieve data for

[integer]

symbols

A list of company symbols (tickers) to retrieve company data (identifiers) for

[string]

cusips

A list of cusip numbers to retrieve company data (identifiers) for

[string]

isins

A list of ISIN numbers to retrieve company data (identifiers) for

[string]

uuids

A list of UUID numbers to retrieve company data for

[string]

portfolio_ids

A list of portfolio IDs to retrieve data for held companies

[integer]

Example request

/companies/list

curl -X POST https://development.ethosesg.com/companies/list \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
}'

Response fields

companies

An array containing a list of companies with identifiers.

[object]

company_id

Ethos' unique identifier for the company. Like all Ethos identifiers, the company_id is case sensitive

integer

symbol

Unique symbol (ticker) for the company. Like all Ethos identifiers, the symbol is case sensitive

string

cusip

Unique CUSIP number of stock associated with company, if available

string

isin

Unique ISIN number of stock associated with company, if available

string

uuid

Unique UUID field used by ACA Group, if available

string

open_figi

Unique OpenFigi identifier, if available

string

name

Name of the company

string

updated_at

Date the company record was last updated in Ethos ESG's database

string

total_companies

Number of total companies available based on the request

integer

max_id

Maximum id for all companies matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"companies" : [
{
"company_id" : 553,
"symbol" : "AAPL",
"cusip" : "37833100",
"isin" : "US0378331005",
"uuid" : "II|V1|FactSetId|000C7F-E|17",
"open_figi" : "BBG000B9XRY4",
"name" : "Apple",
"updated_at" : "2022-06-19"
}
],
"total_companies" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

Compliance

Retrieve data on one or more of your Compliance Tests

In this section

/compliance/results/get

/compliance/rules/get

/compliance/tests/get

/compliance/results/get

The /compliance/results/get endpoint allows you to receive basic data about one or more of your Compliance Test Results.

Results are returned by ID. Results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_results response body field.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

A list of test result ids to retrieve data for

[integer]

test_ids

A list of test IDs to retrieve data for held companies

[integer]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

count

The number of companies to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

The number of companies to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/compliance/results/get

curl -X POST https://development.ethosesg.com/compliance/results/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"count": 100,
"offset": 0
}
}'

Response fields

results

An array containing the requested results.

[object]

result_id

Ethos' unique identifier for the result. Like all Ethos identifiers, the result_id is case sensitive

integer

test_id

Ethos' unique identifier for the test. Like all Ethos identifiers, the test_id is case sensitive

integer

test_name

Name of the associated test

string

updated_at

Date the result record was last updated in Ethos' database, in the format YYYY-MM-DD

string

portfolio_id

Ethos' unique identifier for the associated portfolio, if applicable

integer

portfolio_name

Name of the associated portfolio, if applicable

string

fund_id

Ethos' unique identifier for the associated fund, if applicable

integer

fund_name

Name of the associated fund, if applicable

string

company_id

Ethos' unique identifier for the associated company, if applicable

integer

company_name

Name of the associated company, if applicable

string

questionnaire_response_id

Ethos' unique identifier for the associated questionnaire response, if applicable

integer

questionnaire_name

Name of the associated questionnaire, if applicable

string

result_pass

Whether or not the result passed

boolean

result_value

Percent of the test that passed

decimal

run_type

Whether the results were scheduled or run ad-hoc

string

rules

A set of fields describing results for rules associated with the test

[object]

rule_id

Ethos' unique identifier for the associated rule

integer

rule_name

Name of the associated rule

string

rule_pass_threshold

Threshold for a test result to pass the rule

decimal

passed

Whether or not the result passed this rule

boolean

pass_percent

Percent of assessed records that passed this rule

decimal

failing_company_ids

IDs of companies that failed this rule

[integer]

failing_fund_ids

IDs of funds that failed this rule

[integer]

offset_results

Number of results offset in the request

integer

paged_results

Number of paged results returned

integer

total_results

Number of total results available based on the request

integer

max_id

Maximum id for all results matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"results" : [
{
"result_id" : 12345,
"test_id" : 5,
"test_name" : "Article 8 Fund Monitoring",
"updated_at" : "2024-06-19",
"portfolio_id" : 12345,
"portfolio_name" : "Article 8 Portfolio",
"fund_id" : null,
"fund_name" : null,
"company_id" : null,
"company_name" : null,
"questionnaire_response_id" : null,
"questionnaire_name" : null,
"result_pass" : true,
"result_value" : 0.926,
"run_type" : "ad_hoc",
"rules" : [
{
"rule_id" : 123,
"rule_name" : "Avoid companies with severe controversies related to UN Global Compact",
"rule_pass_threshold" : 0.8,
"passed" : true,
"pass_percent" : 0.926,
"failing_company_ids" : [123, 456, 789]
"failing_fund_ids" : []
}
]
}
],
"offset_results" : 0 ,
"paged_results" : 1 ,
"total_results" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

/compliance/rules/get

The /compliance/rules/get endpoint allows you to receive basic data about one or more of your Compliance Rules.

Rules are returned in alphabetical order by their name. Results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_rules response body field.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

A list of rule ids to retrieve data for

[integer]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

count

The number of companies to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

The number of companies to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/compliance/rules/get

curl -X POST https://development.ethosesg.com/compliance/rules/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"count": 100,
"offset": 0
}
}'

Response fields

rules

An array containing the requested rules.

[object]

rule_id

Ethos' unique identifier for the rule. Like all Ethos identifiers, the rule_id is case sensitive

integer

name

Name of the rule

string

updated_at

Date the rule record was last updated in Ethos' database, in the format YYYY-MM-DD

string

threshold

Threshold for test results to pass this rule

decimal

direction

Whether test results should be less than or greater than the threshold to pass

string

pass_percent

Percent of assessed records that must pass the rule in order for the rule to be marked as pass

decimal

screen_id

Ethos' unique identifier for the screen attached to this rule

integer

screen_name

Name of the screen attached to this rule

string

controversy_category_id

Ethos' unique identifier for the controversy category attached to this rule

integer

controversy_category_name

Name of the controversy category attached to this rule

string

metric_id

Ethos' unique identifier for the metric attached to this rule

integer

metric_name

Name of the metric attached to this rule

string

cause_id

Ethos' unique identifier for the cause attached to this rule

integer

cause_name

Name of the cause attached to this rule

string

offset_rules

Number of rules offset in the request

integer

paged_rules

Number of paged rules returned

integer

total_rules

Number of total rules available based on the request

integer

max_id

Maximum id for all rules matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"rules" : [
{
"rule_id" : 5523,
"name" : "Avoid companies with >10% revenue from Thermal Coal",
"updated_at" : "2024-06-19",
"threshold" : 0.8,
"direction" : "less_than",
"pass_percent" : 0.8,
"screen_id" : 139,
"screen_name" : "Thermal coal",
"controversy_category_id" : null,
"controversy_category_name" : null,
"metric_id" : null,
"metric_name" : null,
"cause_id" : null,
"cause_name" : null,
}
],
"offset_rules" : 0 ,
"paged_rules" : 1 ,
"total_rules" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

/compliance/tests/get

The /compliance/tests/get endpoint allows you to receive basic data about one or more of your Compliance Tests.

Tests are returned in alphabetical order by their name. Results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_tests response body field.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

A list of test ids to retrieve data for

[integer]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

count

The number of companies to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

The number of companies to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/compliance/tests/get

curl -X POST https://development.ethosesg.com/compliance/tests/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"count": 100,
"offset": 0
}
}'

Response fields

tests

An array containing the requested tests.

[object]

test_id

Ethos' unique identifier for the test. Like all Ethos identifiers, the test_id is case sensitive

integer

name

Name of the test

string

updated_at

Date the test record was last updated in Ethos' database, in the format YYYY-MM-DD

string

client_id

Ethos' unique identifier for the associated client, if applicable

integer

client_name

Name of the associated client, if applicable

string

schedule

Schedule that the test is run. Can be one of never, daily, weekly, monthly, or quarterly

string

silenced

Whether or not notifications for the test have been silenced

boolean

email_schedule

Schedule that emails for the test are sent out. Can be one of never, daily, weekly, monthly, or quarterly

string

email_day

Day of the week that emails for the test are sent out. Only applicable if email_schedule is set to weekly

string

test_rules_count

Number of rules associated with the test

integer

test_runs_count

Number of times the test has been run (number of results)

integer

test_followers

Emails of anyone listed as a follower of the test

[string]

last_run

Date that the test was last run, in the format YYYY-MM-DD

string

last_result_pass

Whether or not the last test result passed

boolean

last_result_value

Percent of the last result that passed

decimal

offset_tests

Number of tests offset in the request

integer

paged_tests

Number of paged tests returned

integer

total_tests

Number of total tests available based on the request

integer

max_id

Maximum id for all tests matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"tests" : [
{
"test_id" : 123,
"name" : "Article 8 Fund Monitoring",
"updated_at" : "2024-06-19",
"client_id" : 12345,
"client_name" : "John Smith",
"schedule" : "weekly",
"silenced" : false,
"email_schedule" : "weekly",
"email_day" : "Monday",
"test_rules_count" : 10,
"test_runs_count" : 54,
"test_followers" : ["john.smith@example.com"],
"last_run" : "2024-12-01",
"last_result_pass" : true,
"last_result_value" : 0.97,
}
],
"offset_tests" : 0 ,
"paged_tests" : 1 ,
"total_tests" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

Funds

Retrieve current data on one or more funds, including fund information, classification, ESG screens, ratings and metrics.

In this section

/funds/get

/funds/screens/get

/funds/ratings/get

/funds/metrics/get

/funds/list

/funds/get

The /funds/get endpoint allows you to receive data about one or more Funds, including classification, expense ratio and AUM, and screens (e.g., whether the fund holds fossil fuel, gambling, nuclear or other types of companies).

Funds are returned in alphabetical order by standard Ethos name. Due to the potentially large amount of data associated with multiple Funds, results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_funds response body field.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

A list of fund ids to retrieve data for

[integer]

symbols

A list of fund symbols (tickers) to retrieve fund data for

[string]

cusips

A list of cusip numbers to retrieve fund data for

[string]

isins

A list of ISIN numbers to retrieve fund data for

[string]

asset_classes

A list of asset classes to filter fund data. Options include Alternatives, Diversified, Cash, Equities, Fixed income, Infrastructure, and Property

[string]

domiciles

A list of domiciles to filter fund data. Current options include Australia, Europe, and United States

[string]

fund_types

A list of fund types to filter fund data. Options include ETF, Index, Mutual Fund, and SMA

[string]

categories

A list of fund categories to filter fund data

[string]

fund_families

A list of fund families to filter fund data

[string]

include_price

Whether or not to include price data (delayed 15-minutes) in the returned information

[true/false]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

count

The number of funds to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

The number of funds to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/funds/get

curl -X POST https://development.ethosesg.com/funds/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"symbols": [String],
"count": 100,
"offset": 0
}
}'

Response fields

funds

An array containing the requested funds.

[object]

fund_id

Ethos' unique identifier for the fund. Like all Ethos identifiers, the fund_id is case sensitive

integer

symbol

Unique symbol (ticker) for the fund. Like all Ethos identifiers, the symbol is case sensitive

string

cusip

Unique CUSIP number of security associated with fund, if available

string

isin

Unique ISIN number of security associated with fund, if available

string

open_figi

Unique OpenFigi identifier, if available

string

name

Name of the fund

string

updated_at

Date the fund record was last updated in Ethos ESG's database

string

price

Share price of the associated security (delayed 15-minutes)

string

classifications

A set of fields describing fund classifications

object

fund_type

Type of fund (ETF, Mutual Fund, or Index)

string

asset_class

Asset class of the fund

string

Example response

API Object

{
"funds" : [
{
"fund_id" : 553,
"symbol" : "VEGN",
"cusip" : "26922A 297",
"isin" : "US26922A2978",
"open_figi" : "BBG00Q6L3CX3",
"name" : "US Vegan Climate ETF",
"updated_at" : "2022-06-19",
"price" : "200.5",
"classifications" : {
"fund_type" : "ETF",
"asset_class" : "Equities",
"category" : "Equity - US Large Blend",
"style" : "Large Blend",
"fund_family" : "Beyond Advisors IC",
},
"logos" : {
"original" : "https://d1bgieexblpmvb.cloudfront.net/funds/logos/beyond_investing.png",
"square" : "https://d1bgieexblpmvb.cloudfront.net/funds/logos/200x200/beyond_investing.png"
},
"financial" : {
"expense_ratio" : "0.006",
"aum" : "73111284"
},
"performance" : {
"return_one_week" : "1.049524",
"return_one_month" : "-0.110756",
"return_three_months" : "7.283246",
"return_one_year" : "18.069027",
"return_two_years" : "-1.680218",
"return_three_years" : "10.446368",
"return_five_years" : "null"
},
"screens" : {
"abortion" : "2.23%",
"advertising" : "0.74%",
"alcohol" : "0%",
"animal_testing" : "0%",
"cannabis" : "0%",
"carbon_emissions_intensity" : "5.58%",
"coal" : "0%",
"contraceptives" : "0.74%",
"deforestation_financing" : "0.74%",
"deforestation_supply_chain" : "2.23%",
"discrimination_cont" : "12.64%",
"environmental_cont" : "15.61%",
"factory_farming" : "0%",
"fast_food" : "0%",
"fossil_fuel" : "0%",
"fur" : "0%",
"gambling" : "0%",
"genetic_engineering" : "0%",
"health_cont" : "6.32%"
"human_trafficking" : "2.23%",
"interest_based" : "21.93%",
"interest_bearing_debt" : "13.75%",
"interest_bearing_securities" : "8.18%",
"misleading_communication" : "10.04%",
"music" : "0.37%",
"no_sbti" : "72.49%",
"nuclear" : "0%",
"oil_and_gas" : "0%",
"opioid_cont" : "0.37%",
"oppressive_cont" : "3.72%",
"pork" : "0%",
"pornography" : "0%",
"predatory_lending" : "1.12%",
"prison_involvement" : "3.35%",
"privacy_cont" : "5.95%",
"single_use_plastic" : "0.37%",
"stem_cell" : "0%",
"sugar" : "0.37%",
"tobacco" : "0%",
"weapons" : "0%"
}
}
],
"offset_funds" : 0 ,
"paged_funds" : 1 ,
"total_funds" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

/funds/screens/get

The /funds/screens/get endpoint allows you to receive ESG Screens data about one or more Funds.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

A list of fund ids to retrieve data for

[integer]

symbols

A list of fund symbols (tickers) to retrieve fund data for

[string]

cusips

A list of cusip numbers to retrieve fund data for

[string]

isins

A list of ISIN numbers to retrieve fund data for

[string]

asset_classes

A list of asset classes to filter fund data. Options include Alternatives, Diversified, Cash, Equities, Fixed income, Infrastructure, and Property

[string]

domiciles

A list of domiciles to filter fund data. Current options include Australia, Europe, and United States

[string]

fund_types

A list of fund types to filter fund data. Options include ETF, Index, Mutual Fund, and SMA

[string]

categories

A list of fund categories to filter fund data

[string]

fund_families

A list of fund families to filter fund data

[string]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

count

The number of funds to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

The number of funds to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/funds/get

curl -X POST https://development.ethosesg.com/funds/screens/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"symbols": [String],
"count": 100,
"offset": 0
}
}'

Response fields

funds

An array containing the requested funds.

[object]

fund_id

Ethos' unique identifier for the fund. Like all Ethos identifiers, the fund_id is case sensitive

integer

symbol

Unique symbol (ticker) for the fund. Like all Ethos identifiers, the symbol is case sensitive

string

cusip

Unique CUSIP number of security associated with fund, if available

string

isin

Unique ISIN number of security associated with fund, if available

string

open_figi

Unique OpenFigi identifier, if available

string

name

Name of the fund

string

updated_at

Date the fund record was last updated in Ethos ESG's database

string

price

Share price of the associated security (delayed 15-minutes)

string

screens

A set of fields describing percent of fund holdings that fail ESG-related screens, as well as percent of revenue derived by held companies from screened activities

object

advertising

object

alcohol

object

alcohol_marketing

object

animal_treatment

object

anti_abortion

Percent of fund holdings that fail company screen: Whether company has been reported to lobby against abortion or donate to politicians or groups working to erode female rights.

object

anti_personnel_mines

object

antisemitism

Percent of fund holdings that fail company screen: Whether company has been reported to be involved in antisemitic or anti-Israel activities. Based on publicly-available information.

object

anti_social_publishing

Percent of fund holdings that fail company screen: Whether company generates revenue from anti-social publishing (including anti-social internet publishing).

object

arctic_drilling

Percent of fund holdings that fail company screen: Whether company is involved in arctic drilling for oil or gas. Does not include service companies or equipment manufacturers.

object

banned_chemicals

object

banned_pharmaceuticals

Percent of fund holdings that fail company screen: Whether company has been reported to be involved in production or trade in controlled substances or pharmaceuticals subject to international ban.

object

biological_chemical_weapons

object

cannabis

Percent of fund holdings that fail company screen: Whether company is involved in the cannabis industry as part of its business model.

object

carbon_emissions_intensity

object

carbon_underground

object

cu_coal

object

cu_oil_gas

object

cu_tar_sands

object

cu_thermal_coal

object

child_safety

object

cluster_munitions

object

coal

Percent of fund holdings that fail company screen: Whether company's primary business model involves coal mining, including thermal or metallurgical (coking).

object

conflict_minerals

Percent of fund holdings that fail company screen: Whether company generates revenue from the extraction or trading of minerals, coal and uranium from conflict areas.

object

contraceptives

Percent of fund holdings that fail company screen: Whether company manufactures contraceptives or derives significant revenue from selling contraceptives.

object

controversial_weapons

object

deforestation_financing

Percent of fund holdings that fail company screen: Whether company is a major financer of deforestation. Defined as providing more than $100M USD to companies involved in deforestation.

object

deforestation_supply_chain

object

depleted_uranium

object

discrimination_cont

object

electrical_utility

Percent of fund holdings that fail company screen: Whether company derives revenue from electrical utility activities.

object

endangered_wildlife

object

environmental_cont

object

eu_sanctions

object

factory_farming

Percent of fund holdings that fail company screen: Whether company has been reported to use factory farming in its supply chain.

object

fast_food

Percent of fund holdings that fail company screen: Whether company is involved in the fast-food industry, and derives at least 10% of its revenue from fast food.

object

firearms

object

food_commodity_derivatives

object

for_profit_health

object

fossil_fuel

object

fur

Percent of fund holdings that fail company screen: Whether company produces or sells fur as a part of its business model.

object

gambling

object

genetic_engineering

Percent of fund holdings that fail company screen: Whether company uses genetic engineering in its product development or other research.

object

health_cont

object

human_rights_cont

object

human_trafficking

Percent of fund holdings that fail company screen: Whether company has been reported to be involved in human trafficking over the past 5 years, either directly or through its supply chain.

object

illegal_activities

object

ilo

object

interest_based

Percent of fund holdings that fail company screen: Whether company offers an interest-based financial product as part of its business model.

object

interest_bearing_debt

Percent of fund holdings that fail company screen: Whether company's debt-to-market-cap ratio is greater than 30%.

object

interest_bearing_securities

object

iran

object

land_use_biodiversity

object

military_contracting

Percent of fund holdings that fail company screen: Whether company generates revenue from military contracts related to weapons or combat operations.

object

misleading_communication

object

music

Percent of fund holdings that fail company screen: Whether company is involved in producing, distributing or selling music as part of its business model.

object

myanmar

object

non_sustainable_palm_oil

object

norges_bank

object

northern_ireland

object

north_korea

object

no_sbti

object

nuclear

Percent of fund holdings that fail company screen: Whether company generates nuclear power or provides supplies enabling nuclear power.

object

oecd

object

oil_and_gas

object

opioid_cont

Percent of fund holdings that fail company screen: Whether company has been reported to be involved in the opiod crisis in the United States.

object

oppressive_cont

object

palestinian_human_rights

Percent of fund holdings that fail company screen: Whether company has been reported to be involved in human rights violations against the Palestinian people. Based on publicly-available information.

object

pharma_cont

Percent of fund holdings that fail company screen: Whether company has been reported to be involved in pharmaceutical-related controversies such as price-gouging or the opioid crisis.

object

pork

Percent of fund holdings that fail company screen: Whether company produces or sells pork as part of its business model.

object

pornography

object

predatory_lending

Percent of fund holdings that fail company screen: Whether company has been reported to engage in predatory lending.

object

prison_involvement

object

privacy_cont

object

pro_life

object

russia

object

single_use_plastic

Percent of fund holdings that fail company screen: Whether company produces or sells single-use plastic items as part of its business model.

object

stem_cell

object

sudan

object

sugar

Percent of fund holdings that fail company screen: Whether company produces or sells sugary products as part of its business model.

object

syria

object

tar_sands

Percent of fund holdings that fail company screen: Whether company is involved in the extraction of tar sands, sometimes called oil sands.

object

thermal_coal

Percent of fund holdings that fail company screen: Whether company's primary business model involves thermal coal mining.

object

tobacco

object

tobacco_gics

object

uk_sanctions

object

undermining_us_elections

object

ungc

object

ungp

object

us_ofac

object

weapons

object

offset_funds

Number of funds offset in the request

integer

paged_funds

Number of paged funds returned

integer

total_funds

Number of total funds available based on the request

integer

max_id

Maximum id for all funds matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"funds" : [
{
"fund_id" : 553,
"symbol" : "VEGN",
"cusip" : "26922A 297",
"isin" : "US26922A2978",
"open_figi" : "BBG00Q6L3CX3",
"name" : "US Vegan Climate ETF",
"updated_at" : "2022-06-19",
"screens" : {
"advertising" : {
"fail_count" : 2,
"revenue_percent" : 0.02,
"updated_at" : "2022-06-19"
},
"..." : {
"fail_count" : 10,
"revenue_percent" : 0.11,
"updated_at" : "2022-06-19"
}
}
}
],
"offset_funds" : 0 ,
"paged_funds" : 1 ,
"total_funds" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

/funds/ratings/get

The /funds/ratings/get endpoint allows you to receive ESG Ratings data about one or more Funds.

Optionally specify the id of a cause (topic) you want to retrieve a Rating for. Defaults to returning ratings for all causes on Ethos.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An object to be used with the request.

object

ids

A list of fund ids to retrieve data for

[integer]

symbols

A list of fund symbols (tickers) to retrieve fund data for

[string]

cusips

A list of cusip numbers to retrieve fund data for

[string]

isins

A list of ISIN numbers to retrieve fund data for

[string]

cause_ids

A list of cause_ids to retrieve fund data for. If not specified, ratings for all causes for requested funds will be returned

[integer]

asset_classes

A list of asset classes to filter fund data. Options include Alternatives, Diversified, Cash, Equities, Fixed income, Infrastructure, and Property

[string]

domiciles

A list of domiciles to filter fund data. Current options include Australia, Europe, and United States

[string]

fund_types

A list of fund types to filter fund data. Options include ETF, Index, Mutual Fund, and SMA

[string]

categories

A list of fund categories to filter fund data

[string]

fund_families

A list of fund families to filter fund data

[string]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

count

The number of funds to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

The number of funds to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/funds/get

curl -X POST https://development.ethosesg.com/funds/ratings/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"symbols": [String],
"count": 100,
"offset": 0
}
}'

Response fields

funds

An array containing the requested funds.

[object]

fund_id

Ethos' unique identifier for the fund. Like all Ethos identifiers, the fund_id is case sensitive

integer

symbol

Unique symbol (ticker) for the fund. Like all Ethos identifiers, the symbol is case sensitive

string

cusip

Unique CUSIP number of security associated with fund, if available

string

isin

Unique ISIN number of security associated with fund, if available

string

open_figi

Unique OpenFigi identifier, if available

string

name

Name of the fund

string

updated_at

Date the fund record was last updated in Ethos ESG's database

string

ratings

A set of fields describing ESG ratings associated with the fund

object

cause

Name of the cause or "Impact Persona" for which the fund is rated. Impact Personas are combinations of causes based on what a client or lead selects in their Impact Assessment.

string

cause_id

Unique id of the cause. Note that this field does not apply to "Impact Personas" (combinations of causes). This field will be a null value for Impact Personas.

integer

client_persona

boolean

date

Date of the rating

date

score

Score of the rating, from 0 (worst) to 100 (best)

integer

rank

Rank of the rating, compared to all funds

integer

percentile

Percentile of the rating, compared to all funds

integer

offset_funds

Number of funds offset in the request

integer

paged_funds

Number of paged funds returned

integer

total_funds

Number of total funds available based on the request

integer

max_id

Maximum id for all funds matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"funds" : [
{
"fund_id" : 2858,
"symbol" : "VEGN",
"cusip" : "26922A 297",
"isin" : "US26922A2978",
"open_figi" : "BBG00Q6L3CX3",
"name" : "US Vegan Climate ETF",
"updated_at" : "2022-06-19",
"ratings" : [
{
"cause" : "Gender equality",
"cause_id" : "37",
"updated_at" : "2022-06-19",
"score" : 88.2,
"rank" : 84,
"percentile" : 0.92
}
]
}
],
"offset_funds" : 0 ,
"paged_funds" : 1 ,
"total_funds" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

/funds/metrics/get

The /funds/metrics/get endpoint allows you to receive ESG Metrics data about one or more Funds.

Optionally specify the id of a Metric you want to retrieve data for. Defaults to all Metrics on Ethos.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An object to be used with the request.

object

ids

A list of fund ids to retrieve data for

[integer]

symbols

A list of fund symbols (tickers) to retrieve fund data for

[string]

cusips

A list of cusip numbers to retrieve fund data for

[string]

isins

A list of ISIN numbers to retrieve fund data for

[string]

metric_ids

A list of metric_ids to retrieve fund data for. If not specified, all metrics for requested funds will be returned

[integer]

asset_classes

A list of asset classes to filter fund data. Options include Alternatives, Diversified, Cash, Equities, Fixed income, Infrastructure, and Property

[string]

domiciles

A list of domiciles to filter fund data. Current options include Australia, Europe, and United States

[string]

fund_types

A list of fund types to filter fund data. Options include ETF, Index, Mutual Fund, and SMA

[string]

categories

A list of fund categories to filter fund data

[string]

fund_families

A list of fund families to filter fund data

[string]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

count

The number of funds to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

The number of funds to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/funds/metrics/get

curl -X POST https://development.ethosesg.com/funds/metrics/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"symbols": [String],
"count": 100,
"offset": 0
}
}'

Response fields

funds

An array containing the requested funds.

[object]

fund_id

Ethos' unique identifier for the fund. Like all Ethos identifiers, the fund_id is case sensitive

integer

symbol

Unique symbol (ticker) for the fund. Like all Ethos identifiers, the symbol is case sensitive

string

cusip

Unique CUSIP number of security associated with fund, if available

string

isin

Unique ISIN number of security associated with fund, if available

string

open_figi

Unique OpenFigi identifier, if available

string

name

Name of the fund

string

updated_at

Date the fund record was last updated in Ethos ESG's database

string

metrics

A set of fields describing ESG metrics associated with the fund

object

name

Name of the metric

string

metric_id

Unique id of the metric

integer

description

Short description of the metric

string

link

Link to metric source, if available

string

uom

Unit of measure of the metric

string

date

Date of the data point

date

esg_category

Primary ESG category of the metric (environment, social or governance)

string

score_base

Base score of the metric, measured according to the unit of measure

integer

normalization_scope

Whether the metric is normalized relative to peers, all funds, or not at all

string

score_normalized

Normalized score of the metric (on a 0-100 scale)

integer

offset_funds

Number of funds offset in the request

integer

paged_funds

Number of paged funds returned

integer

total_funds

Number of total funds available based on the request

integer

max_id

Maximum id for all funds matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"funds" : [
{
"fund_id" : 2858,
"symbol" : "VEGN",
"cusip" : "26922A 297",
"isin" : "US26922A2978",
"open_figi" : "BBG00Q6L3CX3",
"name" : "US Vegan Climate ETF",
"updated_at" : "2022-06-19",
"metrics" : [
{
"name" : "Advertising fines and violations",
"metric_id" : "224",
"description" : "Sum of fines incurred over the past four years from the Federal Trade Commission, related to advertising",
"link" : "https://www.goodjobsfirst.org/violation-tracker",
"uom" : "$ fines",
"updated_at" : "2022-06-19",
"esg_category" : "social",
"score_base" : 42100000,
"score_normalized" : 0
}
]
}
],
"offset_funds" : 0 ,
"paged_funds" : 1 ,
"total_funds" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

/funds/list

The /funds/list endpoint allows you to receive a list of Funds available on Ethos, with basic identifiers for each Fund.

Funds are returned in alphabetical order by name. No paging is included in the response.

If you would like more detailed information about a fund, use the /funds/get endpoint below.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

A list of fund ids to retrieve data for

[integer]

symbols

A list of fund symbols (tickers) to retrieve fund data (identifiers) for

[string]

cusips

A list of cusip numbers to retrieve fund data (identifiers) for

[string]

isins

A list of ISIN numbers to retrieve fund data (identifiers) for

[string]

asset_classes

A list of asset classes to filter fund data. Options include Alternatives, Diversified, Cash, Equities, Fixed income, Infrastructure, and Property

[string]

domiciles

A list of domiciles to filter fund data. Current options include Australia, Europe, and United States

[string]

fund_types

A list of fund types to filter fund data. Options include ETF, Index, Mutual Fund, and SMA

[string]

categories

A list of fund categories to filter fund data

[string]

fund_families

A list of fund families to filter fund data

[string]

Example request

/funds/list

curl -X POST https://development.ethosesg.com/funds/list \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
}'

Response fields

funds

An array containing a list of funds with identifiers.

[object]

fund_id

Ethos' unique identifier for the fund. Like all Ethos identifiers, the company_id is case sensitive

integer

symbol

Unique symbol (ticker) for the fund

string

cusip

Unique CUSIP number associated with fund, if available

string

isin

Unique ISIN number associated with fund, if available

string

open_figi

Unique OpenFigi identifier, if available

string

name

Name of the fund

string

updated_at

Date the fund record was last updated in Ethos ESG's database

string

total_funds

Number of total funds available based on the request

integer

max_id

Maximum id for all funds matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"funds" : [
{
"fund_id" : 553,
"symbol" : "VEGN",
"cusip" : "26922A 297",
"isin" : "US26922A2978",
"open_figi" : "BBG00Q6L3CX3",
"name" : "US Vegan Climate ETF",
"updated_at" : "2022-06-19"
}
],
"total_funds" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

Help

Submit requests for coverage additions or customer support

In this section

/help/coverage_requests/get

/help/coverage_requests/create

/help/tickets/get

/help/tickets/create

/help/coverage_requests/get

The /help/coverage_requests/get endpoint allows you to receive a list of all coverage requests you have made, including status of each request.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

Example request

/help/coverage_requests/get

curl -X POST https://development.ethosesg.com/help/coverage_requests/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
}'

Response fields

coverage_requests

An object containing information about your coverage requests.

object

available_count

Number of available coverage requests. You can add more coverage requests in your account on Ethos under Support > Coverage requests or by contacting Ethos.

integer

in_progress_count

Number of coverage requests currently in progress.

integer

in_progress_requests

An array containing information about your in-progress coverage requests.

[object]

name

Name of the requested entity

string

status

Status of the request

string

created_at

Date the request was made

date

updated_at

Date the request was last updated. This generally refers to the date the status was last changed

date

record_type

Whether the request is for a Company or Fund

string

public_status

Whether the request is for a public or private entity

string

symbol

Symbol (ticker) of the requested entity, if available

string

isin

ISIN of the requested entity, if available

string

cusip

Cusip of the requested entity, if available

string

open_figi

OpenFigi of the requested entity, if available

string

lxid

LoanX ID of the requested entity, if available

string

completed_count

Number of coverage requests completed.

integer

completed_requests

An array containing information about your completed coverage requests.

[object]

name

Name of the requested entity

string

status

Status of the request

string

created_at

Date the request was made

date

updated_at

Date the request was last updated. This generally refers to the date the status was last changed

date

record_type

Whether the request is for a Company or Fund

string

public_status

Whether the request is for a public or private entity

string

symbol

Symbol (ticker) of the requested entity, if available

string

isin

ISIN of the requested entity, if available

string

cusip

Cusip of the requested entity, if available

string

open_figi

OpenFigi of the requested entity, if available

string

lxid

LoanX ID of the requested entity, if available

string

max_id

Maximum id for all of your coverage requests.

integer

request_id

Unique id for the request

string

Example response

API Object

{
"coverage_requests" : {
"available_count" : 18,
"in_progress_count" : 4,
"in_progress_requests" : [{
"name" : Apple,
"status" : "In Progress",
"created_at" : "October 1, 2023",
"updated_at" : "October 2, 2023",
"record_type" : "Company",
"public_status" : "Public",
"symbol" : "AAPL",
"isin" : "US0378331005",
"cusip" : "037833100",
"open_figi" : "BBG000B9XRY4",
"lxid" : ""
}],
"completed_count" : 24,
"completed_requests" : [{
"name" : Apple,
"status" : "In Progress",
"created_at" : "October 1, 2023",
"updated_at" : "October 2, 2023",
"record_type" : "Company",
"public_status" : "Public",
"symbol" : "AAPL",
"isin" : "US0378331005",
"cusip" : "037833100",
"open_figi" : "BBG000B9XRY4",
"lxid" : ""
}],
},
"max_id" : 100
"request_id" : "28HyTu"
}

/help/coverage_requests/create

The /help/coverage_requests/create endpoint allows you to submit one or more requests for coverage additions on Ethos.

You can also view all submitted coverage requests and your remaining requests in your account under Support > Coverage requests.

Note you can test this endpoint with symbols "AAPL" or "PRIVATE.TESTCO" without affecting your available coverage additions.

If you are using Test mode (contact us for more information), coverage requests you create will auto-complete after 2 days.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

coverage_requests

An array of objects to be used with the request. Include information for any coverage request you want to create.

[object]

record_type

Optionally specify if the request is for a Company or Fund. Defaults to Company.

string

public_status

Optionally specify if the requested entity is public or private.

string

name

Optional identifier of holding. Note you must pass at least one identifier for each holding.

string

symbol

Optional identifier of holding. Note you must pass at least one identifier for each holding.

string

isin

Optional identifier of holding. Note you must pass at least one identifier for each holding.

string

cusip

Optional identifier of holding. Note you must pass at least one identifier for each holding.

string

open_figi

Optional identifier of holding. Note you must pass at least one identifier for each holding.

string

lxid

Optional identifier of holding. Note you must pass at least one identifier for each holding.

string

Example request

/help/coverage_requests/create

curl -X POST https://development.ethosesg.com/help/coverage_requests/create \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"coverage_requests": [{
"symbol": String,
"name": String,
"isin": String,
]}
}'

Response fields

created_coverage_requests

An array containing information about successfully-created coverage requests.

[object]

status

Status of the API request (200 or 400)

integer

message

Message of the API request

string

name

Name of the requested entity

string

record_type

Whether the request is for a Company or Fund

string

public_status

Whether the request is for a public or private entity

string

symbol

Symbol (ticker) of the requested entity, if available

string

isin

ISIN of the requested entity, if available

string

cusip

Cusip of the requested entity, if available

string

open_figi

OpenFigi of the requested entity, if available

string

lxid

LoanX ID of the requested entity, if available

string

errors

An array containing information about coverage requests that did not succeed.

[object]

status

Status of the API request

integer

error_message

Error message of the API request

string

error_code

Error code of the API request

string

coverage_requests_summary

An object containing summary information about all of your coverage requests.

object

available_count

Total number of coverage requests available.

integer

in_progress_count

Total number of coverage requests in progress.

integer

completed_count

Total number of coverage requests completed.

integer

max_id

Maximum id for all of your coverage requests.

integer

request_id

Unique id for the request.

string

Example response

API Object

{
"created_coverage_requests" : [{
"status" : 200,
"message" : Successfully created or updated coverage request,
"name" : Apple,
"record_type" : "Company",
"public_status" : "Public",
"symbol" : "AAPL",
"isin" : "US0378331005",
"cusip" : "037833100",
"open_figi" : "BBG000B9XRY4",
"lxid" : ""
}],
"errors" : []
"coverage_requests_summary" : {
"available_count" : 18,
"in_progress_count" : 3,
"completed_count" : 12
},
"max_id" : 100
"request_id" : "28HyTu"
}

/help/tickets/get

The /help/tickets/get endpoint allows you to receive a list of all support tickets you have made, including status of each tickets.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

Example request

/help/tickets/get

curl -X POST https://development.ethosesg.com/help/tickets/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
}'

Response fields

tickets

An object containing information about your support tickets.

object

open_count

Number of currently open tickets.

integer

open_tickets

An array containing information about your open tickets.

[object]

emails

Email addresses associated with the ticket. These are the email addresses that Ethos will use to communicate with about the ticket.

string

CC email addresses associated with the ticket. These are the email addresses that Ethos will cc when communicating about the ticket.

string

status

Status of the ticket.

string

created_at

Date the ticket was created.

date

updated_at

Date the ticket was last updated. This generally refers to the date the status was last changed.

date

message

Message of the ticket.

string

closed_count

Number of tickets closed.

integer

closed_tickets

An array containing information about your closed tickets.

[object]

Email address associated with the ticket. This is the email address that Ethos will use to communicate with about the ticket.

string

status

Status of the ticket.

string

created_at

Date the ticket was created.

date

updated_at

Date the ticket was last updated. This generally refers to the date the status was last changed.

date

message

Message of the ticket.

string

max_id

Maximum id for all of your tickets.

integer

request_id

Unique id for the request.

string

Example response

API Object

{
"tickets" : {
"open_count" : 1,
"open_tickets" : [{
"email" : email@example.co,
"message" : "Support request message",
"created_at" : "October 1, 2023",
"updated_at" : "October 2, 2023",
"status" : "Open"
}],
"closed_count" : 4,
"closed_tickets" : [{
"email" : email@example.co,
"message" : "Support request message",
"created_at" : "October 1, 2023",
"updated_at" : "October 2, 2023",
"status" : "Open"
}],
},
"max_id" : 100
"request_id" : "28HyTu"
}

/help/tickets/create

The /help/tickets/create endpoint allows you to submit one or more support requests (tickets).

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

tickets

An array of objects to be used with the request. Include information for any tickets you want to create.

[object]

emails

Email addresses that Ethos should use to communicate with about this ticket.

[string]

Optional email addresses that Ethos should cc when communicating about this ticket.

[string]

message

Message describing your support request.

string

Example request

/help/tickets/create

curl -X POST https://development.ethosesg.com/help/tickets/create \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"tickets": [{
"emails": [String],
"cc": [String],
"message": String,
]}
}'

Response fields

created_tickets

An array containing information about successfully-created tickets.

[object]

status

Status of the API request (200 or 400)

integer

message

Message of the API request

string

emails

Emails associated with the ticket.

string

Optional cc emails associated with the ticket.

string

message

Message associated with the ticket.

string

errors

An array containing information about any ticket requests that did not succeed.

[object]

status

Status of the API request.

integer

error_message

Error message of the API request

string

error_code

Error code of the API request.

string

tickets_summary

An object containing summary information about all of your tickets.

object

open_count

Total number of open tickets.

integer

closed_count

Total number of closed tickets.

integer

max_id

Maximum id for all of your tickets.

integer

request_id

Unique id for the request.

string

Example response

API Object

{
"created_tickets" : [{
"status" : 200,
"message" : Successfully created ticket,
"emails" : [email@example.co, email2@example.co],
"cc" : [supportinbox@example.co],
"message" : "Support request message",
"status" : "Open"
}],
"errors" : []
"tickets_summary" : {
"open_count" : 3,
"closed_count" : 12
},
"max_id" : 100
"request_id" : "28HyTu"
}

Metrics

Retrieve a list of metrics available on Ethos. Metrics of companies and funds (info above) can be scoped to specific metrics

In this section

/metrics/list

The /metrics/list endpoint allows you to receive a list of Metrics available on Ethos, with basic information about each Metric.

Metrics are returned in alphabetical order by name. Due to the potentially large amount of data associated with multiple Metrics, results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_metrics response body field.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

A list of metric ids to retrieve data for

[integer]

count

The number of metrics to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

The number of metrics to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/metrics/list

curl -X POST https://development.ethosesg.com/metrics/list \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"metric_ids": [Integer],
"count": 100,
"offset": 0
}
}'

Response fields

metrics

An array containing the requested metrics.

[object]

metric_id

Ethos' unique identifier for the metric

integer

name

Name of the metric

string

description

Short description of the metric

string

source

Name of the metric source

string

link

Link to the metric source

string

uom

Unit of measure of the metric

string

updated_at

Date that metric data was last updated

date

esg_category

Primary ESG category of the metric (environment, social or governance)

string

normalization_scope

Whether the metric is normalized relative to peers, all companies, or not at all

string

paged_metrics

Number of paged metrics returned

integer

total_metrics

Number of total metrics available based on the request

integer

max_id

Maximum id for all metrics matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"metrics" : [
{
"metric_id" : 224,
"name" : "Fines and violations",
"description" : "Sum of fines and violations incurred from US government agencies over the previous four years",
"source" : "Violation Tracker",
"link" : "https://www.goodjobsfirst.org/violation-tracker",
"uom" : "$ fines",
"updated_at" : "2021-04-15",
"esg_category" : "governance",
"normalization_scope" : "all"
}
],
"paged_metrics" : 1 ,
"total_metrics" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

Portfolios

Retrieve and submit data on one or more of your Portfolios

In this section

/portfolios/get

/portfolios/update

/portfolios/holdings/get

/portfolios/holdings/update

/portfolios/ratings/get

/portfolios/get

The /portfolios/get endpoint allows you to receive basic data about one or more of your Portfolios.

Portfolios are returned in alphabetical order by their name. Results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_portfolios response body field.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

A list of portfolio ids to retrieve portfolio data for

[integer]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

count

The number of portfolios to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

The number of portfolios to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/portfolios/get

curl -X POST https://development.ethosesg.com/portfolios/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"portfolio_ids": [Integer],
"count": 100,
"offset": 0
}
}'

Response fields

portfolios

An array containing the requested portfolios.

[object]

portfolio_id

Ethos' unique identifier for the portfolio. Like all Ethos identifiers, the portfolio_id is case sensitive

integer

account_number

Optional account number or other ID you would like to use to help identify the portfolio

string

name

Name of the portfolio

string

description

Description of the portfolio

string

value

Value of the portfolio record in Ethos

string

holdings_as_of

As-of date of portfolio holdings

string

created_at

Date the portfolio record was created in Ethos ESG's database

string

updated_at

Date the portfolio record was last updated in Ethos ESG's database

string

offset_portfolios

Number of portfolios offset in the request

integer

paged_portfolios

Number of paged portfolios returned

integer

total_portfolios

Number of total portfolios available based on the request

integer

max_id

Maximum id for all portfolios matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"portfolios" : [
{
"portfolio_id" : 553,
"account_number" : "123456789",
"name" : "Example Portfolio",
"description" : "Europe credit portfolio",
"value" : "120000000",
"holdings_as_of" : "2023-09-30",
"created_at" : "2023-06-19"
"updated_at" : "2023-06-19"
}
],
"offset_portfolios" : 0 ,
"paged_portfolios" : 1 ,
"total_portfolios" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

/portfolios/update

The /portfolios/update endpoint allows you to create or update a Portfolio in your account.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

portfolio_id

Optional Ethos ID for a portfolio in your account. Should only be used to update existing portfolios in your account.

integer

name

Name of the portfolio. If passed, Ethos will use to find an existing portfolio or create a new portfolio in your account.

string

account_number

Optional account number or other local ID you would like to use to help identify the portfolio. If passed, Ethos will use to find an existing portfolio or create a new portfolio in your account.

string

description

Optional description for the portfolio.

string

holdings_as_of

Optional date of holdings for the portfolio. Should be passed in the format of YYYY-MM-DD.

string

value

Optional $USD value field for the portfolio (can be any value metric that is useful for you). Defaults to $100,000.

integer

Example request

/portfolios/update

curl -X POST https://development.ethosesg.com/portfolios/update \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"name": String
}'

Response fields

portfolio

An object containing information about the associated portfolio

object

status

Status of the update attempt

integer

message

Message associated with the update attempt

string

portfolio_id

Ethos' unique identifier for the portfolio. Like all Ethos identifiers, the portfolio_id is case sensitive

integer

account_number

Optional account number or other ID you would like to use to help identify the portfolio

string

name

Name of the portfolio

string

description

Description of the portfolio

string

value

Value of the portfolio record in Ethos

string

holdings_as_of

As-of date of portfolio holdings

string

created_at

Date the portfolio record was created in Ethos ESG's database

string

updated_at

Date the portfolio record was last updated in Ethos ESG's database

string

request_id

Unique id for the request

string

Example response

API Object

{
"portfolio" : {
"status" : 200,
"message" : Successfully added or updated the portfolio,
"portfolio_id" : 553,
"account_number" : "123456789",
"name" : "Example Portfolio",
"description" : "Europe credit portfolio",
"value" : "120000000",
"holdings_as_of" : "2023-09-30",
"created_at" : "2023-06-19"
"updated_at" : "2023-06-19"
},
"max_id" : 100
"request_id" : "28HyTu"
}

/portfolios/holdings/get

The /portfolios/holdings/get endpoint allows you to receive a list of holdings for one or more Portfolios in your account.

Holdings are returned in alphabetical order by standard Ethos name. Due to the potentially large amount of data, results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_portfolios response body field.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An object to be used with the request.

object

ids

A list of portfolio ids to retrieve portfolio holdings for

[integer]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

portfolios_count

The number of portfolios to fetch. Optional.

Default: 10

Maximum: 10

integer

portfolios_offset

The number of portfolios to skip. Optional.

Default: 0

integer

holdings_count

The number of holdings to fetch in each returned portfolio. Optional.

Default: all

integer

holdings_offset

The number of holdings to skip in each returned portfolio. Optional.

Default: 0

integer

Example request

/portfolios/holdings/get

curl -X POST https://development.ethosesg.com/portfolios/holdings/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"portfolio_ids": [Integer],
}
}'

Response fields

portfolios

An array containing the requested portfolios.

[object]

portfolio_id

Ethos' unique identifier for the portfolio. Like all Ethos identifiers, the portfolio_id is case sensitive

integer

name

Name of the portfolio

string

created_at

Date the portfolio record was created in Ethos ESG's database

string

updated_at

Date the portfolio record was last updated in Ethos ESG's database

string

holdings

A set of fields describing portfolio holdings

array

name

Name of the associated company

string

symbol

Symbol (ticker) of the associated company

string

client_id

Client-specified ID of the holding, if available

string

isin

Unique ISIN number of stock associated with company, if available

string

cusip

Unique CUSIP number of stock associated with company, if available

string

open_figi

Unique OpenFigi identifier, if available

string

holding_type

Type of holding (e.g., Company)

string

weight

Weight of the holding within the portfolio

string

offset_portfolios

Number of portfolios offset in the request

integer

paged_portfolios

Number of paged portfolios returned

integer

total_portfolios

Number of total portfolios available based on the request

integer

max_id

Maximum id for all portfolio holdings matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"portfolios" : [
{
"portfolio_id" : 553,
"name" : "Example Portfolio",
"created_at" : "2023-06-19",
"updated_at" : "2023-06-19",
"holdings" : [
"name" : Example Company,
"symbol" : XYZ,
"client_id" : "12345",
"isin" : "248384ABC",
"cusip" : 428334333,
"open_figi" : "BBG093RKMB42",
"holding_type" : "Company",
"weight" : "0.037"
]
}
],
"offset_portfolios" : 0 ,
"paged_portfolios" : 1 ,
"total_portfolios" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

/portfolios/holdings/update

The /portfolios/holdings/update endpoint allows you to create or update a holding in one or more Portfolios in your account.

Note that when you add or update holdings with this endpoint, Ethos initiates a process to update ratings and analysis for the associated portfolio. This process typically takes 30 seconds to 5 minutes, depending on the size of the portfolio. While this process is ongoing, API calls to this endpoint for the same portfolio will return the error message, PORTFOLIO_IMPORTING.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

portfolio_id

Unique Ethos ID for a portfolio in your account. This is required to associate the holding with the correct portfolio.

integer

options

An optional object to be used with the request.

object

reset

Option to reset all portfolio holdings with this request. If true, Ethos will first delete all portfolio holdings and then add all passed holdings below. Defaults to false.

true/false

create_coverage_requests

Option to automatically create coverage requests when needed. If true, Ethos will create a coverage request for the underlying company associated with any passed holding that does not yet exist in Ethos' database, as long as your account has at least 5 available coverage requests (when there are less than 5, please use the coverage request endpoint directly). Defaults to false.

true/false

holdings

An array of objects to be used with the request. Include information for any holdings you want to create or update.

[object]

client_id

Optional identifier of holding. Can be any ID you would like to maintain with the record; client_id gets sent back in the /portfolios/holdings/get endpoint. If client_id is passed, Ethos will prioritize search for a matching client_id. If no existing client_id is found, Ethos will create a new holding record.

[string]

isin

Optional identifier of holding. Note you must pass at least one identifier for each holding.

[string]

cusip

Optional identifier of holding. Note you must pass at least one identifier for each holding.

[string]

open_figi

Optional identifier of holding. Note you must pass at least one identifier for each holding.

[string]

symbol

Optional identifier of holding. Note you must pass at least one identifier for each holding.

[string]

weight

Optional weight of the holding within the portfolio. Should be a value between 0 and 1.

[decimal]

Example request

/portfolios/holdings/update

curl -X POST https://development.ethosesg.com/portfolios/holdings/update \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"portfolio_id": Integer
"holdings": [{
"symbol": String,
"weight": Float,
]}
}'

Response fields

portfolio

An object containing information about the associated portfolio.

object

portfolio_id

Ethos' unique identifier for the portfolio. Like all Ethos identifiers, the portfolio_id is case sensitive

integer

name

Name of the portfolio

string

total_holdings

Total number of holdings in the portfolio, after the update attempt completed

integer

total_weight

Total weight of holdings in the portfolio, after the update attempt completed

decimal

updated

An array containing successfully-updated holdings

[object]

status

Status of the update attempt

integer

message

Message associated with the update attempt

string

name

Name of the associated company

string

symbol

Symbol (ticker) of the associated company

string

client_id

Client-specified ID of the holding, if available

string

isin

Unique ISIN number of stock associated with company, if available

string

cusip

Unique CUSIP number of stock associated with company, if available

string

open_figi

Unique OpenFigi identifier, if available

string

weight

Weight of the holding within the portfolio

string

errors

An array containing error messages for any holdings that did not successfully update

[object]

status

Status of the update attempt

integer

error_message

Message associated with the update attempt

string

error_code

Error code associated with the update attempt

string

created_coverage_requests

An array containing information about successfully-created coverage requests. Only applicable if option "create_coverage_requests" passed with request.

[object]

status

Status of the request (200 or 400)

integer

message

Message of the request

string

name

Name of the requested entity

string

record_type

Whether the request is for a Company or Fund

string

public_status

Whether the request is for a public or private entity

string

symbol

Symbol (ticker) of the requested entity, if available

string

isin

ISIN of the requested entity, if available

string

cusip

Cusip of the requested entity, if available

string

open_figi

OpenFigi of the requested entity, if available

string

lxid

LoanX ID of the requested entity, if available

string

coverage_requests_summary

An object containing summary information about all of your coverage requests.

object

available_count

Total number of coverage requests available.

integer

in_progress_count

Total number of coverage requests in progress.

integer

completed_count

Total number of coverage requests completed.

integer

max_id

Maximum id for all portfolio holdings matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"portfolio" : {
"portfolio_id" : 553,
"name" : "Example Portfolio",
"total_holdings" : "100",
"total_weight" : "100",
},
"updated" : [{
"status" : 200,
"message" : Successfully added or updated XYZ Company,
"name" : XYZ Company,
"symbol" : XYZ,
"client_id" : "12345",
"isin" : 248384ABC,
"cusip" : 428334333,
"open_figi" : "BBG093RKMB42",
"weight" : "0.037"
}],
"errors" : [{
"status" : 400,
"error_message" : Not able to find a company for passed symbol: XYZA. Verify the company exists or submit a coverage request for it to be added to Ethos.,
"error_code" : ITEM_NOT_FOUND
}],
"created_coverage_requests" : [{
"status" : 200,
"message" : Successfully created or updated coverage request,
"id" : 12345,
"name" : Apple,
"record_type" : Company,
"public_status" : Public,
"symbol" : AAPL,
"isin" : US0378331005,
"cusip" : 037833100,
"open_figi" : BBG000B9XRY4,
"lxid" : "",
}],
"coverage_requests_summary" : {
"available_count" : 18,
"in_progress_count" : 3,
"completed_count" : 12
},
"max_id" : 100
"request_id" : "28HyTu"
}

/portfolios/ratings/get

The /portfolios/ratings/get endpoint allows you to receive ESG Ratings data about one or more Portfolios in your account.

Optionally specify the id of a cause (topic) you want to retrieve a Rating for. Defaults to returning ratings for all causes on Ethos.

Portfolios are returned in alphabetical order by standard Ethos name. Due to the potentially large amount of data, results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_portfolios response body field.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An object to be used with the request.

object

ids

A list of portfolio ids to retrieve portfolio data for

[integer]

cause_ids

A list of cause_ids to retrieve portfolio data for. If not specified, ratings for all causes (topics) for requested portfolios will be returned

[integer]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

count

The number of portfolios to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

The number of portfolios to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/portfolios/get

curl -X POST https://development.ethosesg.com/portfolios/ratings/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"portfolio_ids": [Integer],
"count": 100,
"offset": 0
}
}'

Response fields

portfolios

An array containing the requested portfolios.

[object]

portfolio_id

Ethos' unique identifier for the portfolio. Like all Ethos identifiers, the portfolio_id is case sensitive

integer

name

Name of the portfolio

string

updated_at

Date the portfolio record was last updated in Ethos ESG's database

string

ratings

A set of fields describing ESG ratings associated with the portfolio

object

cause

Name of the cause or "Impact Persona" for which the portfolio is rated. Impact Personas are combinations of causes based on what a client or lead selects in their Impact Assessment.

string

cause_id

Unique id of the cause. Note that this field does not apply to "Impact Personas" (combinations of causes). This field will be a null value for Impact Personas.

integer

date

Date of the rating

date

score

Score of the rating, from 0 (worst) to 100 (best)

integer

percentile

Percentile of the rating, compared to all portfolios

integer

offset_portfolios

Number of portfolios offset in the request

integer

paged_portfolios

Number of paged portfolios returned

integer

total_portfolios

Number of total portfolios available based on the request

integer

max_id

Maximum id for all portfolios matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"portfolios" : [
{
"portfolio_id" : 2858,
"name" : "Example Portfolio",
"updated_at" : "2022-06-19",
"ratings" : [
{
"cause" : "Gender equality",
"cause_id" : "37",
"updated_at" : "2022-06-19",
"score" : 88.2,
"percentile" : 0.92
}
]
}
],
"offset_portfolios" : 0 ,
"paged_portfolios" : 1 ,
"total_portfolios" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

Questionnaires

Retrieve data on one or more of your Questionnaires

In this section

/questionnaires/get

/questionnaires/responses/get

/questionnaires/questions/get

/questionnaires/answers/get

/questionnaires/approvals/get

/questionnaires/get

The /questionnaires/get endpoint allows you to receive basic data about one or more of your Questionnaires.

Questionnaires are returned in order by their id. Results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_questionnaires response body field.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

A list of questionnaire ids to retrieve data for

[integer]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

count

The number of questionnaires to fetch.

Default: 100

Minimum: 1

Maximum: 100

integer

offset

The number of questionnaires to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/questionnaires/get

curl -X POST https://development.ethosesg.com/questionnaires/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"count": 100,
"offset": 0
}
}'

Response fields

questionnaires

An array containing the requested questionnaires.

[object]

questionnaire_id

Ethos' unique identifier for the questionnaire_id. Like all Ethos identifiers, the questionnaire_id is case sensitive

integer

title

Title of the questionnaire

string

description

Description of the questionnaire

string

updated_at

Date the questionnaire was last updated in Ethos' database

string

responses_count

Number of associated responses with the questionnaire

integer

percent_completed

Percent completion of the questionnaire, across all associated responses

string

offset_questionnaires

Number of questionnaires offset in the request

integer

paged_questionnaires

Number of paged questionnaires returned

integer

total_questionnaires

Number of total questionnaires available based on the request

integer

max_id

Maximum id for all questionnaires matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"questionnaires" : [
{
"questionnaire_id" : 553,
"title" : "XYZ Questionnaire",
"description" : "Description of the questionnaire",
"updated_at" : "2024-09-30",
"responses_count" : "3"
"percent_completed" : "95%"
}
],
"offset_questionnaires" : 0 ,
"paged_questionnaires" : 1 ,
"total_questionnaires" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

/questionnaires/responses/get

The /questionnaires/responses/get endpoint allows you to receive basic data about one or more Response to your Questionnaires.

Responses are returned in order by their id. Results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_responses response body field.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

A list of questionnaire response ids to retrieve data for

[integer]

status

Retrieve data for responses with a specific status. Options are "In Progress", "Not Started", "Submitted", or "Approved"

string

symbols

A list of company symbols (tickers) to retrieve company data for

[string]

cusips

A list of cusip numbers to retrieve company data for

[string]

isins

A list of ISIN numbers to retrieve company data for

[string]

uuids

A list of UUID numbers to retrieve company data for

[string]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

count

The number of responses to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

The number of responses to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/questionnaires/responses/get

curl -X POST https://development.ethosesg.com/questionnaires/responses/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"symbols": [String],
"count": 100,
"offset": 0
}
}'

Response fields

responses

An array containing the requested responses.

[object]

response_id

Ethos' unique identifier for the response_id. Like all Ethos identifiers, the response_id is case sensitive

integer

questionnaire_id

Ethos' unique identifier for the questionnaire associated with the response

integer

questionnaire_title

Title of the associated questionnaire

string

client_id

Unique identifier for the company; can be any identifier from your internal system

string

company_id

Ethos' unique identifier for the company associated with the response

integer

company_name

Name of the associated company

string

updated_at

Date the response was last updated in Ethos' database

string

status

Status of the response. Can be one of In Progress, Not Started, Submitted, or Approved

string

overdue

Whether or not the response is overdue on its approval deadline

boolean

percent_completed

Percent completion of the response

string

responsible_user

Name of the person assigned to complete the response

string

primary_approver

Name of the person assigned as primary approver for the response

string

secondary_approver

Name of the person assigned as secondary approver for the response

string

submission_deadline

Deadline for the response to be submitted

string

approval_deadline

Deadline for the response to be approved

string

submitted_at

Date the response was submitted

string

approved_at

Date the response was approved

string

offset_responses

Number of responses offset in the request

integer

paged_responses

Number of paged responses returned

integer

total_responses

Number of total responses available based on the request

integer

max_id

Maximum id for all responses matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"responses" : [
{
"response_id" : 1234,
"questionnaire_id" : 13223,
"questionnaire_title" : "Example Questionnaire",
"client_id" : "A6BZ748E",
"company_id" : 74,
"company_name" : "Apple",
"updated_at" : "2024-09-30",
"status" : "In Progress"
"overdue" : false,
"percent_completed" : "100%"
"responsible_user" : "John Smith"
"primary_approver" : "Sarah Jackson"
"secondary_approver" : null
"submission_deadline" : "2024-10-05",
"approval_deadline" : "2024-10-10",
"submitted_at" : "2024-09-30",
"approved_at" : "2024-10-02",
}
],
"offset_responses" : 0 ,
"paged_responses" : 1 ,
"total_responses" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

/questionnaires/questions/get

The /questionnaires/questions/get endpoint allows you to receive basic data about one or more Question.

Questions are returned in order by their id. Questions are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_questions response body field.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

A list of question ids to retrieve data for

[integer]

query

A query term to search questions

string

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

count

The number of questions to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

The number of questions to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/questionnaires/questions/get

curl -X POST https://development.ethosesg.com/questionnaires/questions/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"query": String,
"count": 100,
"offset": 0
}
}'

Response fields

questions

An array containing the requested questions.

[object]

question_id

Ethos' unique identifier for the question_id. Like all Ethos identifiers, the question_id is case sensitive

integer

metric_id

Ethos' unique identifier for a metric associated with the question. Note that not all questions have associated metrics

integer

updated_at

Date the question was last updated in Ethos' database

string

question_text

Text of the question

string

instructions

Instructions for the question

string

question_type

Type of question, such as text or dropdown

string

offset_questions

Number of questions offset in the request

integer

paged_questions

Number of paged questions returned

integer

total_questions

Number of total questions available based on the request

integer

max_id

Maximum id for all questions matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"questions" : [
{
"question_id" : 1234,
"metric_id" : 132,
"updated_at" : "2024-09-30",
"question_text" : "What was the company's total Scope 1 emissions last year, in metric tons?",
"instructions" : "Enter the company's total Scope 1 GHG emissions for the last calendar year, in metric tons."
"question_type" : "integer"
}
],
"offset_questions" : 0 ,
"paged_questions" : 1 ,
"total_questions" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

/questionnaires/answers/get

The /questionnaires/answers/get endpoint allows you to receive basic data about one or more Answer.

Answers are returned in order by their id. Answers are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_answers response body field.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

A list of questionnaire answer ids to retrieve data for

[integer]

question_ids

A list of associated question ids to retrieve data for. Each answer has an associated question

[integer]

response_ids

A list of associated response ids to retrieve data for. Each answer has an associated overall questionnaire response record

[integer]

symbols

A list of company symbols (tickers) to retrieve company data for

[string]

cusips

A list of cusip numbers to retrieve company data for

[string]

isins

A list of ISIN numbers to retrieve company data for

[string]

uuids

A list of UUID numbers to retrieve company data for

[string]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

count

The number of answers to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

The number of answers to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/questionnaires/answers/get

curl -X POST https://development.ethosesg.com/questionnaires/answers/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"symbols": [String],
"count": 100,
"offset": 0
}
}'

Response fields

answers

An array containing the requested answers.

[object]

answer_id

Ethos' unique identifier for the answer_id. Like all Ethos identifiers, the answer_id is case sensitive

integer

question_id

Ethos' unique identifier for the question associated with the answer

integer

question_text

Text of the associated question

string

response_id

Ethos' unique identifier for the response associated with the answer

integer

questionnaire_id

Ethos' unique identifier for the questionnaire associated with the answer

integer

client_id

Unique identifier for the company; can be any identifier from your internal system

string

company_id

Ethos' unique identifier for the company associated with the response

integer

company_name

Name of the associated company

string

updated_at

Date the response was last updated in Ethos' database

string

updated_by

Name of the person that last updated the response

string

answer_text

Text of the answer

string

answer_commentary

Any commentary provided with the answer

string

answer_documents

An array containing any uploaded or linked supporting documentation

[object]

name

Name of the document

string

file_url

File URL of the document

string

offset_answers

Number of answers offset in the request

integer

paged_answers

Number of paged answers returned

integer

total_answers

Number of total answers available based on the request

integer

max_id

Maximum id for all answers matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"answers" : [
{
"answer_id" : 1234,
"question_id" : 553,
"question_text" : "What was the company's total Scope 1 emissions last year, in metric tons?",
"response_id" : 23392,
"questionnaire_id" : 3212,
"client_id" : "A6BZ748E",
"company_id" : 74,
"company_name" : "Apple",
"updated_at" : "2024-09-30",
"updated_by" : "John Smith"
"answer_text" : "10230"
"answer_commentary" : "As reported in the company's sustainability report"
"answer_documents" : [
{
"name" : "Sustainability Report"
"file_url" : "https://xyz.com"
}
],
}
],
"offset_answers" : 0 ,
"paged_answers" : 1 ,
"total_answers" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

/questionnaires/approvals/get

The /questionnaires/approvals/get endpoint allows you to receive basic data about one or more Answer.

Answers are returned in order by their id. Answers are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_answers response body field.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

A list of approval ids to retrieve data for

[integer]

response_ids

A list of associated response ids to retrieve data for. Each approval has an associated overall questionnaire response record

[integer]

status

Retrieve data for responses with a specific status. Options are "Pending", "Approved", or "Rejected"

string

symbols

A list of company symbols (tickers) to retrieve company data for

[string]

cusips

A list of cusip numbers to retrieve company data for

[string]

isins

A list of ISIN numbers to retrieve company data for

[string]

uuids

A list of UUID numbers to retrieve company data for

[string]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

count

The number of approvals to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

The number of approvals to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/questionnaires/approvals/get

curl -X POST https://development.ethosesg.com/questionnaires/approvals/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"symbols": [String],
"count": 100,
"offset": 0
}
}'

Response fields

approvals

An array containing the requested approvals.

[object]

approval_id

Ethos' unique identifier for the approval_id. Like all Ethos identifiers, the approval_id is case sensitive

integer

response_id

Ethos' unique identifier for the response_id. Like all Ethos identifiers, the response_id is case sensitive

integer

client_id

Unique identifier for the company; can be any identifier from your internal system

string

company_id

Ethos' unique identifier for the company associated with the response

integer

company_name

Name of the associated company

string

created_at

Date the approval was created in Ethos' database

string

updated_at

Date the approval was last updated in Ethos' database

string

deadline

Deadline for the approval to be completed

string

status

Status of the approval. Can be one of Pending, Approved, or Rejected

string

requester

Name of the person making the approval request

integer

request_message

Any messsage sent by the requester with the request

string

approvers

An array containing a list of approvers for the approval request

[object]

name

Name of the approver

string

Email of the approver

string

approved_at

Date the approval was approved

string

offset_approvals

Number of approvals offset in the request

integer

paged_approvals

Number of paged approvals returned

integer

total_approvals

Number of total approvals available based on the request

integer

max_id

Maximum id for all approvals matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"approvals" : [
{
"approval_id" : 1234,
"response_id" : 23342,
"client_id" : "A6BZ748E",
"company_id" : 74,
"company_name" : "Apple",
"created_at" : "2024-09-25",
"updated_at" : "2024-09-30",
"updated_by" : "John Smith"
"deadline" : "2024-10-02",
"status" : "Pending"
"requester" : "John Smith"
"request_message" : "Please review and approve"
"approvers" : [
{
"name" : "Sarah Jackson"
"email" : "example@email.com"
}
],
}
],
"offset_approvals" : 0 ,
"paged_approvals" : 1 ,
"total_approvals" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

Reports

Retrieve data on one or more of your Reports

In this section

/reports/get

The /reports/get endpoint allows you to receive basic data about one or more of your Reports.

Reports are returned in order by their id. Results are paginated in groups of 10. Manipulate the count and offset parameters in conjunction with the total_reports response body field.

Request fields

firm_id

Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.

string

secret

Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.

string

options

An optional object to be used with the request. If specified, options must not be null.

object

ids

An optional list of report ids to retrieve report data for

[integer]

symbols

An optional list of symbols (tickers) to retrieve associated reports for

[string]

cusips

An optional list of cusip numbers to retrieve associated reports for

[string]

isins

An optional list of ISIN numbers to retrieve associated reports for

[string]

uuids

An optional list of UUID numbers to retrieve associated reports for

[string]

updated_after

Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"

string

count

The number of reports to fetch.

Default: 100

Minimum: 1

Maximum: 100

integer

offset

The number of reports to skip. The default value is 0.

Default: 0

Minimum: 0

integer

Example request

/reports/get

curl -X POST https://development.ethosesg.com/reports/get \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"options": {
"ids": [Integer],
"count": 10,
"offset": 0
}
}'

Response fields

reports

An array containing the requested reports.

[object]

report_id

Ethos' unique identifier for the report. Like all Ethos identifiers, the report_id is case sensitive

integer

token

Unique token identifier for the report

string

title

Title of the report

string

subtitle

Subtitle of the report, if present

string

created_at

Date the report record was created in Ethos ESG's database

string

updated_at

Date the report record was last updated in Ethos ESG's database

string

filename

Filename of the report

string

link

Link to download the report PDF. This is a time-sensitive link that will expire 1 week after the API call.

string

record_type

Whether the report is focused on a company, fund or portfolio

string

company_id

Associated company id, if present

string

fund_id

Associated fund id, if present

string

offset_reports

Number of reports offset in the request

integer

paged_reports

Number of paged reports returned

integer

total_reports

Number of total reports available based on the request

integer

max_id

Maximum id for all reports matching your request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"reports" : [
{
"report_id" : 553,
"token" : "123456789",
"title" : "ABC Co Scorecard",
"subtitle" : "Company ESG risk scorecard",
"created_at" : "2023-06-19"
"updated_at" : "2023-06-19"
"filename" : "abc-co-scorecard.pdf",
"link" : ""https://ethos-app.s3.eu-west-3.amazonaws.com/accounts/development/352/reports/company-summary-pdf-1705448130-8YMatc7L7i5br9KvXMqbstn2.pdf",
"record_type" : "company",
"company_id" : 1,
"fund_id" : null
}
],
"offset_reports" : 0 ,
"paged_reports" : 1 ,
"total_reports" : 1 ,
"max_id" : 100
"request_id" : "28HyTu"
}

Errors

We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Ethos-related issues. Error fields will be null if no error has occurred.

In this section

Error schema

Error codes

Error schema

error_code

The particular error code. Safe for programmatic use.

string

error_message

A representation of the error code. This may change over time and is not safe for programmatic use.

string

request_id

A unique identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.

string

Error codes

INCORRECT_KEYS

Incorrect firm_id or secret sent with the request

string

NO_IDENTIFIER

No identifier passed for company or fund

string

ITEM_NOT_FOUND

Requested company, fund, cause or metric could not be found in the Ethos database

string

PORTFOLIO_NOT_FOUND

Requested portfolio could not be found in the Ethos database

string

PORTFOLIO_IMPORTING

Requested portfolio is in the process of importing/updating

string

NO_COVERAGE_REQUESTS_AVAILABLE

No coverage requests available to be used. Reach out to Ethos support for additional requests

string

OFFSET_TOO_HIGH

No records available with requested offset paramater

string

INTERNAL_SERVER_ERROR

Error caused by internal Ethos problem. Please contact us for support

string

Ethos API

Better ESG data for your analysis or application

See the API docs

Endpoint schema

Causes Retrieve the list of available causes on Ethos /causes/list

Clients Retrieve information about clients on Ethos /clients/get

Companies Retrieve company-level information, ratings, screens and metrics /companies/get /companies/screens/get /companies/ratings/get /companies/metrics/get Retrieve the list of available companies /companies/list

Compliance Retrieve information about compliance tests, rules and results /compliance/results/get /compliance/rules/get /compliance/tests/get

Funds Retrieve fund-level information, ratings and metrics /funds/get /funds/screens/get /funds/ratings/get /funds/metrics/get Retrieve the list of available funds /funds/list

Help Submit requests for coverage additions or customer support /help/coverage_requests/get /help/coverage_requests/create /help/tickets/get /help/tickets/create

Metrics Retrieve the list of available metrics on Ethos /metrics/list

Portfolios Retrieve and submit data on one or more of your Portfolios /portfolios/get /portfolios/update /portfolios/holdings/get /portfolios/holdings/update /portfolios/ratings/get

Questionnaires Retrieve and submit data on one or more of your Questionnaires /questionnaires/get /questionnaires/responses/get /questionnaires/questions/get /questionnaires/answers/get /questionnaires/approvals/get

Reports Retrieve and submit data on one or more of your Reports /reports/get

API Keys

Every firm on Ethos has a unique firm_id and secret that you can use to access the Ethos API. You can find your firm_id and secret under "Keys" in your account on Ethos.

Protocols and headers

API host

All testing should be done in the Development and Staging environments.

Causes (Topics)

Retrieve a list of causes available on Ethos. Ratings of companies and funds can be scoped to specific causes

In this section

/causes/list

/causes/list

Request fields

Example request

Response fields

Example response

Clients

Retrieve data on one or more of your Clients

In this section

/clients/get

/clients/get

Request fields

Example request

Response fields

Example response

Companies

Retrieve data on one or more companies, including company information, classification, ESG screens, ratings and metrics.

In this section

/companies/get /companies/screens/get /companies/ratings/get /companies/metrics/get /companies/list

/companies/get

Request fields

Example request

Response fields

Example response

/companies/screens/get

Request fields

Example request

Response fields

Example response

/companies/ratings/get

Request fields

Example request

Response fields

Example response

/companies/metrics/get

Request fields

Example request

Response fields

Example response

/companies/list

Request fields

Example request

Response fields

Example response

Compliance

Retrieve data on one or more of your Compliance Tests

In this section

/compliance/results/get /compliance/rules/get /compliance/tests/get

/compliance/results/get

Request fields

Example request

Response fields

Example response

/compliance/rules/get

Request fields

Example request

Response fields

Example response

Causes

Retrieve the list of available causes on Ethos

/causes/list

Clients

Retrieve information about clients on Ethos

/clients/get

Companies

Retrieve company-level information, ratings, screens and metrics

/companies/get

/companies/screens/get

/companies/ratings/get

/companies/metrics/get

Retrieve the list of available companies

/companies/list

Compliance

Retrieve information about compliance tests, rules and results

/compliance/results/get

/compliance/rules/get

/compliance/tests/get

Funds

Retrieve fund-level information, ratings and metrics

/funds/get

/funds/screens/get

/funds/ratings/get

/funds/metrics/get

Retrieve the list of available funds

/funds/list

Help

Submit requests for coverage additions or customer support

/help/coverage_requests/get

/help/coverage_requests/create

/help/tickets/get

/help/tickets/create

Metrics

Retrieve the list of available metrics on Ethos

/metrics/list

Portfolios

Retrieve and submit data on one or more of your Portfolios

/portfolios/get

/portfolios/update

/portfolios/holdings/get

/portfolios/holdings/update

/portfolios/ratings/get

Questionnaires

Retrieve and submit data on one or more of your Questionnaires

/questionnaires/get

/questionnaires/responses/get

/questionnaires/questions/get

/questionnaires/answers/get

/questionnaires/approvals/get

Reports

Retrieve and submit data on one or more of your Reports

/reports/get

/companies/get

/companies/screens/get

/companies/ratings/get

/companies/metrics/get

/companies/list

/compliance/results/get

/compliance/rules/get

/compliance/tests/get

/funds/get

/funds/screens/get

/funds/ratings/get

/funds/metrics/get

/funds/list

/help/coverage_requests/get

/help/coverage_requests/create

/help/tickets/get

/help/tickets/create