Better ESG data for your analysis or application

Endpoint schema

Companies
Retrieve company-level information, ratings and metrics
/companies/get
/companies/screens/get
/companies/ratings/get
/companies/metrics/get
Retrieve the list of available companies
/companies/list
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
Causes
Retrieve the list of available causes on Ethos
/causes/list
Metrics
Retrieve the list of available metrics on Ethos
/metrics/list

Getting started

Every firm on Ethos has a unique client_id and secret that you can use to access the Ethos API. You can find your client_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
Production: https://production.ethosesg.com
The Development environment is unrestricted and supports up to 100 API calls per week (contact us for additional calls). All testing should be done in the Development environment.

Company endpoints

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
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]
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 Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/companies/get \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "symbols": [String],
  8. "count": 100,
  9. "offset": 0
  10. }
  11. }'
  1. const response = await client
  2. . getCompanies (firm_id, secret , {
  3. symbols: [String] ,
  4. count: 100 ,
  5. offset: 0 ,
  6. })
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const companies = response.companies
  1. response = client.Companies.get(firm_id, secret)
  2. companies = response['companies']
  4. # Manipulate the count and offset parameters to paginate
  5. # companies and retrieve all available data
  6. while len (companies) < response[' total_companies' ]:
  7. response = client.Companies.get(firm_id, secret,
  8. offset= len (companies))
  9. companies.extend(response[ 'companies' ])
  1. response = @client .companies. get ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # companies and retrieve all available data
  4. response = @client .companies. get ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_companies = response[ 'companies' ]

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
name
Name of the company
string
updated_at
Date the company record was last updated in Ethos ESG's database
string
classifications
A set of fields describing company classification (sector, industry and peer group)
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
peer_group
Peer group of the company. Peer group 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 business model.
string
advertising_lite
Whether company generates more 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_lite
Whether company generates at least 10% of revenue from the sale 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
cannabis
Whether company is involved in the cannabis industry as part of its business model.
string
cannabis_lite
Whether company generates at least 10% of revenue from the sale of cannabis.
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
coal
Whether company's primary business model involves thermal coal mining.
string
coal_lite
Whether company's primary business model is thermal coal mining, and company generates at least 10% of revenue from thermal coal mining.
string
contraceptives
Whether company manufactures contraceptives or derives significant revenue from selling contraceptives.
string
contraceptives_lite
Whether company derives more than 10% of its revenue from manufacturing or selling contraceptives.
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_financing_lite
Whether company is a major financer of deforestation. Defined as providing more than $250M 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
deforestation_supply_chain_lite
Whether company is involved in deforestation in its supply chain and has been rated in the bottom quintile (lower 20%) by publicly-available sources.
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
discrimination_cont_lite
Whether company has been involved in a "very severe" controversy related to discrimination over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
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
environmental_cont_lite
Whether company has been involved in an environment-related controversy that Ethos has rated as among the most severe over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
factory_farming
Whether company has been reported to use factory farming in its supply chain.
string
factory_farming_lite
Whether company has been reported to use factory farming in its supply chain and is among the bottom third of companies rated by the Better Business Benchmark on Farm Animal Welfare.
string
fast_food
Whether company is considered a fast-food company.
string
fast_food_lite
Whether company generates at least 10% of its revenue from fast-food sales.
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
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
fossil_fuel_lite
Whether company is considered a fossil fuel company and generates at least 10% of revenue from fossil fuel-related activities. Fossil fuel companies include oil and gas, coal, and utilities that use fossil fuels.
string
fur
Whether company produces or sells fur as a part of its business model.
string
fur_lite
Whether company produces or sells fur as a core part of its business model and generates at least 10% of revenue from fur products.
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
gambling_lite
Whether company generates at least 10% of revenue from gambling-related activities.
string
genetic_engineering
Whether company uses genetic engineering in its product development or other research.
string
genetic_engineering_lite
Whether company uses genetic engineering in its product development or other research, and generates at least 10% of revenue from activities that involve genetic engineering.
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
health_cont_lite
Whether company has been involved in a health-related controversy that Ethos has rated as among the most severe 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
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_debt_lite
Whether company's debt-to-market-cap ratio is greater than 33%.
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
interest_bearing_securities_lite
Whether company's ratio of interest-bearing securities to market cap is greater than 33%. 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
military_contracting
Whether company generates revenue from military contracts. Includes companies that have contracts with military or national defense departments, regardless of the nature of those contracts.
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
misleading_communication_lite
Whether company has been involved in a misleading communication-related controversy that Ethos has rated as among the most severe 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
music_lite
Whether company generates more than 10% of revenue from producing, distributing or selling music.
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
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
nuclear_lite
Whether company generates nuclear power or provides supplies enabling nuclear power, and generates at least 10% of revenue from these activities.
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
oil_and_gas_lite
Whether company is considered an oil and gas company and generates at least 10% of revenue from oil and gas-related sales. 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
oppressive_cont_lite
Whether company has been involved in a "very severe" controversy related to an oppressive government over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
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
pork_lite
Whether company generates at least 10% of revenue from the sale of pork or pork-based products.
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
pornography_lite
Whether company generates at least 10% of revenue from activities seeking 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
prison_involvement_lite
Whether company is involved in private prisons or immigrant detention, defined as direct involvement in the operations of a prison or a prison 'harm score' higher than 13 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
privacy_cont_lite
Whether company has been involved in a "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
pro_life_lite
Whether company directly participates in or enables abortion, and generates at least 10% of revenue from activities related to abortion. 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
russia_lite
Whether company generates at least 10% of revenue from activities in Russia, sales to Russia, or sales through partnerships with Russian companies.
string
single_use_plastic
Whether company produces or sells single-use plastic items as part of its business model.
string
single_use_plastic_lite
Whether company produces or sells single-use plastic items as part of its core business model, and generates at least 10% of revenue from selling these items.
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
stem_cell_lite
Whether company generates more than 10% of revenue from stem cell research or activities that depend on such research. Stem cell research may involve 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
sugar_lite
Whether company generates at least 10% of revenue from the sale of sugary products.
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
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_lite
Whether company generates at least 10% of revenue from tobacco products.
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
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
weapons_lite
Whether company generates at least 10% of revenue from the sale of weapons.
string
historical_screens
A set of fields describing whether or not the company failed ESG-related screens in previous years
object
paged_companies
Number of paged companies returned
integer
total_companies
Number of total companies available based on the request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "companies" : [
  3. {
  4. "company_id" : 553
  5. "symbol" : "AAPL"
  6. "cusip" : "37833100"
  7. "isin" : "US0378331005"
  8. "name" : "Apple"
  9. "updated_at" : "2022-06-19"
  10. "price" : "200.5"
  11. "classifications" : {
  12. "sector" : "Technology & Communications"
  13. "industry" : "Software & Services"
  14. "peer_group" : "Big Tech - Major Diversified"
  15. }
  16. "geography" : {
  17. "region" : "United States"
  18. "hq_country" : "United States"
  19. "hq_state" : "California"
  20. "hq_city" : "Cupertino"
  21. }
  22. "financial" : {
  23. "revenue" : 347155005440
  24. "market_value" : 2457875513344
  25. "market_cap" : "mega"
  26. "net_income" : 100555000000
  27. "price" : "168.64"
  28. "earnings_per_share" : "6.015"
  29. "return_on_assets" : "0.2"
  30. "return_on_equity" : "1.46"
  31. "net_invested_capital" : 194730000000
  32. "dividends_per_share" : "0.865"
  33. "net_debt" : 85679000000
  34. "cash_and_short_term" : 63913000000
  35. }
  36. "performance" : {
  37. "return_one_day" : "-2.102473"
  38. "return_one_week" : "-5.29824"
  39. "return_one_month" : "-3.678318"
  40. "return_three_months" : "14.046122"
  41. "return_one_year" : "24.975637"
  42. "return_two_years" : "108.424224"
  43. "return_three_years" : "304.289341"
  44. "return_five_years" : "369.4877506"
  45. }
  46. "executives" : [{
  47. "name" : "Mr. Timothy D. Cook"
  48. "title" : "CEO & Director"
  49. "is_ceo" : true
  50. "age" : 61
  51. "pay" : 16386559
  52. ]}
  53. "screens" : {
  54. "advertising" : pass
  55. "alcohol" : pass
  56. "animal_testing" : pass
  57. "cannabis" : pass
  58. "carbon_emissions_intensity" : pass
  59. "coal" : pass
  60. "contraceptives" : pass
  61. "deforestation_financing" : pass
  62. "deforestation_supply_chain" : pass
  63. "discrimination_cont" : pass
  64. "environmental_cont" : pass
  65. "factory_farming" : pass
  66. "fast_food" : pass
  67. "fossil_fuel" : pass
  68. "fur" : pass
  69. "gambling" : pass
  70. "genetic_engineering" : pass
  71. "health_cont" : pass
  72. "human_trafficking" : fail
  73. "interest_based" : pass
  74. "interest_bearing_debt" : pass
  75. "interest_bearing_securities" : pass
  76. "misleading_communication" : pass
  77. "music" : pass
  78. "no_sbti" : pass
  79. "nuclear" : pass
  80. "oil_and_gas" : pass
  81. "opioid_cont" : pass
  82. "oppressive_cont" : fail
  83. "pork" : pass
  84. "pornography" : pass
  85. "predatory_lending" : pass
  86. "prison_involvement" : pass
  87. "privacy_cont" : fail
  88. "pro_life" : pass
  89. "single_use_plastic" : pass
  90. "stem_cell" : pass
  91. "sugar" : pass
  92. "tobacco" : pass
  93. "weapons" : pass
  94. }
  95. "historical_screens" : {
  96. "2021" : {
  97. "advertising" : pass
  98. "..." : pass
  99. },
  100. "2020" : {
  101. "advertising" : pass
  102. "..." : pass
  103. },
  104. "2019" : {
  105. "advertising" : pass
  106. "..." : pass
  107. },
  108. "2018" : {
  109. "advertising" : pass
  110. "..." : pass
  111. },
  112. "2017" : {
  113. "advertising" : pass
  114. "..." : pass
  115. }
  116. }
  117. }
  118. ],
  119. "paged_companies" : 1 ,
  120. "total_companies" : 1 ,
  121. "request_id" : "28HyTu"
  122. }

/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).

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
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]
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/screens/get
Curl Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/companies/get \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "symbols": [String],
  8. "count": 100,
  9. "offset": 0
  10. }
  11. }'
  1. const response = await client
  2. . getCompanyScreens (firm_id, secret , {
  3. symbols: [String] ,
  4. count: 100 ,
  5. offset: 0 ,
  6. })
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const companies = response.companies
  1. response = client.CompanyScreens.get(firm_id, secret)
  2. companies = response['companies']
  4. # Manipulate the count and offset parameters to paginate
  5. # companies and retrieve all available data
  6. while len (companies) < response[' total_companies' ]:
  7. response = client.CompanyScreens.get(firm_id, secret,
  8. offset= len (companies))
  9. companies.extend(response[ 'companies' ])
  1. response = @client .company_screen_exclusions. get ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # companies and retrieve all available data
  4. response = @client .company_screen_exclusions. get ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_companies = response[ 'companies' ]

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
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 business model.
object
advertising_lite
Whether company generates more 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_lite
Whether company generates at least 10% of revenue from the sale 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
cannabis
Whether company is involved in the cannabis industry as part of its business model.
object
cannabis_lite
Whether company generates at least 10% of revenue from the sale of cannabis.
object
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.
object
coal
Whether company's primary business model involves thermal coal mining.
object
coal_lite
Whether company's primary business model is thermal coal mining, and company generates at least 10% of revenue from thermal coal mining.
object
contraceptives
Whether company manufactures contraceptives or derives significant revenue from selling contraceptives.
object
contraceptives_lite
Whether company derives more than 10% of its revenue from manufacturing or selling contraceptives.
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_financing_lite
Whether company is a major financer of deforestation. Defined as providing more than $250M 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
deforestation_supply_chain_lite
Whether company is involved in deforestation in its supply chain and has been rated in the bottom quintile (lower 20%) by publicly-available sources.
object
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".
object
discrimination_cont_lite
Whether company has been involved in a "very severe" controversy related to discrimination over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
object
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".
object
environmental_cont_lite
Whether company has been involved in an environment-related controversy that Ethos has rated as among the most severe over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
object
factory_farming
Whether company has been reported to use factory farming in its supply chain.
object
factory_farming_lite
Whether company has been reported to use factory farming in its supply chain and is among the bottom third of companies rated by the Better Business Benchmark on Farm Animal Welfare.
object
fast_food
Whether company is considered a fast-food company.
object
fast_food_lite
Whether company generates at least 10% of its revenue from fast-food sales.
object
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.
object
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.
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
fossil_fuel_lite
Whether company is considered a fossil fuel company and generates at least 10% of revenue from fossil fuel-related activities. Fossil fuel companies include oil and gas, coal, and utilities that use fossil fuels.
object
fur
Whether company produces or sells fur as a part of its business model.
object
fur_lite
Whether company produces or sells fur as a core part of its business model and generates at least 10% of revenue from fur products.
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
gambling_lite
Whether company generates at least 10% of revenue from gambling-related activities.
object
genetic_engineering
Whether company uses genetic engineering in its product development or other research.
object
genetic_engineering_lite
Whether company uses genetic engineering in its product development or other research, and generates at least 10% of revenue from activities that involve genetic engineering.
object
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".
object
health_cont_lite
Whether company has been involved in a health-related controversy that Ethos has rated as among the most severe over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
object
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".
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
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_debt_lite
Whether company's debt-to-market-cap ratio is greater than 33%.
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
interest_bearing_securities_lite
Whether company's ratio of interest-bearing securities to market cap is greater than 33%. This is calculated as (cash and equivalents and short-term investments) / market cap.
object
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
object
military_contracting
Whether company generates revenue from military contracts. Includes companies that have contracts with military or national defense departments, regardless of the nature of those contracts.
object
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".
object
misleading_communication_lite
Whether company has been involved in a misleading communication-related controversy that Ethos has rated as among the most severe over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
object
music
Whether company is involved in producing, distributing or selling music as part of its business model.
object
music_lite
Whether company generates more than 10% of revenue from producing, distributing or selling music.
object
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
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
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.
object
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
object
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).
object
nuclear
Whether company generates nuclear power or provides supplies enabling nuclear power.
object
nuclear_lite
Whether company generates nuclear power or provides supplies enabling nuclear power, and generates at least 10% of revenue from these activities.
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
oil_and_gas_lite
Whether company is considered an oil and gas company and generates at least 10% of revenue from oil and gas-related sales. 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
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".
object
oppressive_cont_lite
Whether company has been involved in a "very severe" controversy related to an oppressive government over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
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
pork_lite
Whether company generates at least 10% of revenue from the sale of pork or pork-based products.
object
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.
object
pornography_lite
Whether company generates at least 10% of revenue from activities seeking 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.
object
predatory_lending
Whether company has been reported to engage in predatory lending.
object
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.
object
prison_involvement_lite
Whether company is involved in private prisons or immigrant detention, defined as direct involvement in the operations of a prison or a prison 'harm score' higher than 13 from the nonprofit organization Worth Rises.
object
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".
object
privacy_cont_lite
Whether company has been involved in a "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".
object
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.
object
pro_life_lite
Whether company directly participates in or enables abortion, and generates at least 10% of revenue from activities related to abortion. Participation may include manufacturing of abortifacients and health care companies that perform abortions when not required to by law.
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
russia_lite
Whether company generates at least 10% of revenue from activities in Russia, sales to Russia, or sales through partnerships with Russian companies.
object
single_use_plastic
Whether company produces or sells single-use plastic items as part of its business model.
object
single_use_plastic_lite
Whether company produces or sells single-use plastic items as part of its core business model, and generates at least 10% of revenue from selling these items.
object
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.
object
stem_cell_lite
Whether company generates more than 10% of revenue from stem cell research or activities that depend on such research. Stem cell research may involve 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.
object
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
object
sugar
Whether company produces or sells sugary products as part of its business model.
object
sugar_lite
Whether company generates at least 10% of revenue from the sale of sugary products.
object
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
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_lite
Whether company generates at least 10% of revenue from tobacco products.
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
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.
object
weapons_lite
Whether company generates at least 10% of revenue from the sale of weapons.
object
historical_screens
A set of fields describing whether or not the company failed ESG-related screens in previous years
object
paged_companies
Number of paged companies returned
integer
total_companies
Number of total companies available based on the request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "companies" : [
  3. {
  4. "company_id" : 553
  5. "symbol" : "AAPL"
  6. "cusip" : "37833100"
  7. "isin" : "US0378331005"
  8. "name" : "Apple"
  9. "updated_at" : "2022-06-19"
  10. "screens" : {
  11. "advertising" : {
  12. "pass" : "false"
  13. "revenue_percent" : 0.157
  14. "updated_at" : "2022-06-19"
  15. }
  16. "alcohol" : {
  17. "pass" : "true"
  18. "revenue_percent" : 0
  19. "updated_at" : "2022-06-19"
  20. }
  21. "animal_testing" : {
  22. "pass" : "true"
  23. "revenue_percent" : 0
  24. "updated_at" : "2022-06-19"
  25. }
  26. "cannabis" : {
  27. "pass" : "true"
  28. "revenue_percent" : 0
  29. "updated_at" : "2022-06-19"
  30. }
  31. "carbon_emissions_intensity" : {
  32. "pass" : "true"
  33. "revenue_percent" : 0
  34. "updated_at" : "2022-06-19"
  35. }
  36. "..." : {
  37. "pass" : "true"
  38. "revenue_percent" : 0
  39. "updated_at" : "2022-06-19"
  40. }
  41. }
  42. "historical_screens" : {
  43. "2021" : {
  44. "advertising" : {
  45. "pass" : "false"
  46. "alcohol" : {
  47. "pass" : "true"
  48. "..." : {
  49. "pass" : "true"
  50. },
  51. "2020" : {
  52. "advertising" : {
  53. "pass" : "false"
  54. "alcohol" : {
  55. "pass" : "true"
  56. "..." : {
  57. "pass" : "true"
  58. },
  59. "2019" : {
  60. "advertising" : {
  61. "pass" : "false"
  62. "alcohol" : {
  63. "pass" : "true"
  64. "..." : {
  65. "pass" : "true"
  66. },
  67. "2018" : {
  68. "advertising" : {
  69. "pass" : "false"
  70. "alcohol" : {
  71. "pass" : "true"
  72. "..." : {
  73. "pass" : "true"
  74. },
  75. "2017" : {
  76. "advertising" : {
  77. "pass" : "false"
  78. "alcohol" : {
  79. "pass" : "true"
  80. "..." : {
  81. "pass" : "true"
  82. }
  83. }
  84. }
  85. ],
  86. "paged_companies" : 1 ,
  87. "total_companies" : 1 ,
  88. "request_id" : "28HyTu"
  89. }

/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 or UUID). Optionally specify the id of a cause you want to retrieve a Rating for. Defaults to returning ratings for all causes on Ethos and all "Impact Personas" of your clients and leads.

An "Impact Persona" is a combination of causes based on what a client or lead selects in their Impact Assessment. It can be a single cause or many causes that are important to a client.

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 object to be used with the request. You must specify at least one company identifier (symbol, CUSIP, ISIN or UUID).
object
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]
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]
count
The number of companies to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer

Example request

/companies/ratings/get
Curl Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/companies/ratings/get \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "symbols": [String],
  8. "count": 100,
  9. "offset": 0
  10. }
  11. }'
  1. const response = await client
  2. . getCompanyRatings (firm_id, secret , {
  3. symbols: [String] ,
  4. count: 100 ,
  5. offset: 0 ,
  6. })
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const companies = response.companies
  1. response = client.CompanyRatings.get(firm_id, secret)
  2. companies = response['companies']
  4. # Manipulate the count and offset parameters to paginate
  5. # companies and retrieve all available data
  6. while len (companies) < response[' total_companies' ]:
  7. response = client.CompanyRatings.get(firm_id, secret,
  8. offset= len (companies))
  9. companies.extend(response[ 'companies' ])
  1. response = @client .company_ratings. get ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # companies and retrieve all available data
  4. response = @client .company_ratings. get ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_companies = response[ 'companies' ]

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
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
paged_companies
Number of paged companies returned
integer
total_companies
Number of total companies available based on the request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "companies" : [
  3. {
  4. "company_id" : 553
  5. "symbol" : "AAPL"
  6. "cusip" : "37833100"
  7. "isin" : "US0378331005"
  8. "name" : "Apple"
  9. "updated_at" : "2022-06-19"
  10. "ratings" : [
  11. {
  12. "cause" : "Gender equality"
  13. "cause_id" : "37"
  14. "updated_at" : "2022-06-19"
  15. "score" : 84.1
  16. "rank" : 119
  17. "percentile" : 0.85
  18. }
  19. ]
  20. }
  21. ],
  22. "paged_companies" : 1 ,
  23. "total_companies" : 1 ,
  24. "request_id" : "28HyTu"
  25. }

/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. You must specify at least one company identifier (symbol, CUSIP, ISIN or UUID).
object
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]
metric_ids
A list of metric_ids to retrieve company data for. If not specified, all metrics for requested companies will be returned
[integer]
count
The number of companies to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer

Example request

/companies/metrics/get
Curl Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/companies/metrics/get \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "symbols": [String],
  8. "count": 100,
  9. "offset": 0
  10. }
  11. }'
  1. const response = await client
  2. . getCompanyMetrics (firm_id, secret , {
  3. symbols: [String] ,
  4. count: 100 ,
  5. offset: 0 ,
  6. })
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const companies = response.companies
  1. response = client.CompanyMetrics.get(firm_id, secret)
  2. companies = response['companies']
  4. # Manipulate the count and offset parameters to paginate
  5. # companies and retrieve all available data
  6. while len (companies) < response[' total_companies' ]:
  7. response = client.CompanyMetrics.get(firm_id, secret,
  8. offset= len (companies))
  9. companies.extend(response[ 'companies' ])
  1. response = @client .company_metrics. get ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # companies and retrieve all available data
  4. response = @client .company_metrics. get ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_companies = response[ 'companies' ]

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
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
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
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 peer group. Ethos uses peer averages when no data is available for a company
boolean
paged_companies
Number of paged companies returned
integer
total_companies
Number of total companies available based on the request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "companies" : [
  3. {
  4. "company_id" : 553
  5. "symbol" : "AAPL"
  6. "cusip" : "37833100"
  7. "isin" : "US0378331005"
  8. "name" : "Apple"
  9. "updated_at" : "2022-06-19"
  10. "metrics" : [
  11. {
  12. "name" : "Advertising fines and violations"
  13. "metric_id" : "224"
  14. "description" : "Sum of fines incurred over the past four years from the Federal Trade Commission, related to advertising"
  15. "link" : "https://www.goodjobsfirst.org/violation-tracker"
  16. "uom" : "$ fines"
  17. "updated_at" : "2022-06-30"
  18. "esg_category" : "social"
  19. "score_base" : 113000000
  20. "score_normalized" : 0
  21. "peer_value" : false
  22. }
  23. ]
  24. }
  25. ],
  26. "paged_companies" : 1 ,
  27. "total_companies" : 1 ,
  28. "request_id" : "28HyTu"
  29. }

/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
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]

Example request

/companies/list
Curl Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/companies/list \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. }'
  1. const response = await client
  2. . listCompanies (firm_id, secret )
  3. . catch ((err) => {
  4. // handle error
  5. })
  6. const companies = response.companies
  1. response = client.Companies.list(firm_id, secret)
  2. companies = response['companies']
  1. response = @client .companies. list ( @firm_id , @secret )
  2. total_companies = response[ 'companies' ]

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
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
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "companies" : [
  3. {
  4. "company_id" : 553
  5. "symbol" : "AAPL"
  6. "cusip" : "37833100"
  7. "isin" : "US0378331005"
  8. "name" : "Apple"
  9. "updated_at" : "2022-06-19"
  10. }
  11. ],
  12. "total_companies" : 1 ,
  13. "request_id" : "28HyTu"
  14. }

Fund endpoints

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
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, Balanced, 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]
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 Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/funds/get \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "symbols": [String],
  8. "count": 100,
  9. "offset": 0
  10. }
  11. }'
  1. const response = await client
  2. . getFunds (firm_id, secret , {
  3. symbols: [String] ,
  4. count: 100 ,
  5. offset: 0 ,
  6. })
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const funds = response.funds
  1. response = client.Funds.get(firm_id, secret)
  2. funds = response['funds']
  4. # Manipulate the count and offset parameters to paginate
  5. # funds and retrieve all available data
  6. while len (funds) < response[' total_funds' ]:
  7. response = client.Funds.get(firm_id, secret,
  8. offset= len (funds))
  9. funds.extend(response[ 'funds' ])
  1. response = @client .funds. get ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # funds and retrieve all available data
  4. response = @client .funds. get ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_funds = response[ 'funds' ]

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
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
category
Fund category. More detailed classification than asset class
string
style
Morningstar style of the fund
object
fund_family
Fund family
object
financial
A set of fields basic financial attributes of the fund
object
expense_ratio
Net expense ratio of the fund
string
aum
Total assets under management at the fund
string
performance
A set of fields describing financial performance (returns) of an associated fund. Please note our terms of use for price and performance data.
object
return_one_day
One-day return of fund price, based on end-of-day prices
string
return_one_week
One-week return of fund price, based on end-of-day prices
string
return_one_month
One-month return of fund price, based on end-of-day prices
string
return_three_months
Three-month return of fund price, based on end-of-day prices
string
return_one_year
One-year return of fund price, based on end-of-day prices
string
return_two_years
Two-year return of fund price, based on end-of-day prices
string
return_three_years
Three-year return of fund price, based on end-of-day prices
string
return_five_years
Five-year return of fund price, based on end-of-day prices
string
screens
A set of fields describing percent of fund holdings that fail ESG-related screens
object
advertising
Percent of fund holdings that fail company screen: Whether company is involved in advertising as part of its business model.
string
advertising_lite
Percent of fund holdings that fail company screen: Whether company generates more than 10% of revenue from advertising.
string
alcohol
Percent of fund holdings that fail company screen: 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_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from the sale of alcohol.
string
animal_treatment
Percent of fund holdings that fail company screen: 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
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.
string
cannabis
Percent of fund holdings that fail company screen: Whether company is involved in the cannabis industry as part of its business model.
string
cannabis_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from the sale of cannabis.
string
carbon_emissions_intensity
Percent of fund holdings that fail company screen: 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
coal
Percent of fund holdings that fail company screen: Whether company's primary business model involves thermal coal mining.
string
coal_lite
Percent of fund holdings that fail company screen: Whether company's primary business model is thermal coal mining, and company generates at least 10% of revenue from thermal coal mining.
string
contraceptives
Percent of fund holdings that fail company screen: Whether company manufactures contraceptives or derives significant revenue from selling contraceptives.
string
contraceptives_lite
Percent of fund holdings that fail company screen: Whether company derives more than 10% of its revenue from manufacturing or selling contraceptives.
string
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.
string
deforestation_financing_lite
Percent of fund holdings that fail company screen: Whether company is a major financer of deforestation. Defined as providing more than $250M USD to companies involved in deforestation.
string
deforestation_supply_chain
Percent of fund holdings that fail company screen: 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
deforestation_supply_chain_lite
Percent of fund holdings that fail company screen: Whether company is involved in deforestation in its supply chain and has been rated in the bottom quintile (lower 20%) by publicly-available sources.
string
discrimination_cont
Percent of fund holdings that fail company screen: 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
discrimination_cont_lite
Percent of fund holdings that fail company screen: Whether company has been involved in a "very severe" controversy related to discrimination over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
environmental_cont
Percent of fund holdings that fail company screen: 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
environmental_cont_lite
Percent of fund holdings that fail company screen: Whether company has been involved in an environment-related controversy that Ethos has rated as among the most severe over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
factory_farming
Percent of fund holdings that fail company screen: Whether company has been reported to use factory farming in its supply chain.
string
factory_farming_lite
Percent of fund holdings that fail company screen: Whether company has been reported to use factory farming in its supply chain and is among the bottom third of companies rated by the Better Business Benchmark on Farm Animal Welfare.
string
fast_food
Percent of fund holdings that fail company screen: Whether company is considered a fast-food company.
string
fast_food_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of its revenue from fast-food sales.
string
firearms
Percent of fund holdings that fail company screen: 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
for_profit_health
Percent of fund holdings that fail company screen: 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
Percent of fund holdings that fail company screen: Whether company is involved in fossil fuel production or distribution. Includes oil and gas companies, coal companies, and utilities that use fossil fuels.
string
fossil_fuel_lite
Percent of fund holdings that fail company screen: Whether company is considered a fossil fuel company and generates at least 10% of revenue from fossil fuel-related activities. Fossil fuel companies include oil and gas, coal, and utilities that use fossil fuels.
string
fur
Percent of fund holdings that fail company screen: Whether company produces or sells fur as a part of its business model.
string
fur_lite
Percent of fund holdings that fail company screen: Whether company produces or sells fur as a core part of its business model and generates at least 10% of revenue from fur products.
string
gambling
Percent of fund holdings that fail company screen: 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
gambling_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from gambling-related activities.
string
genetic_engineering
Percent of fund holdings that fail company screen: Whether company uses genetic engineering in its product development or other research.
string
genetic_engineering_lite
Percent of fund holdings that fail company screen: Whether company uses genetic engineering in its product development or other research, and generates at least 10% of revenue from activities that involve genetic engineering.
string
health_cont
Percent of fund holdings that fail company screen: 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
health_cont_lite
Percent of fund holdings that fail company screen: Whether company has been involved in a health-related controversy that Ethos has rated as among the most severe over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
human_rights_cont
Percent of fund holdings that fail company screen: 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
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.
string
interest_based
Percent of fund holdings that fail company screen: Whether company offers an interest-based financial product as part of its business model.
string
interest_bearing_debt
Percent of fund holdings that fail company screen: Whether company's debt-to-market-cap ratio is greater than 30%.
string
interest_bearing_debt_lite
Percent of fund holdings that fail company screen: Whether company's debt-to-market-cap ratio is greater than 33%.
string
interest_bearing_securities
Percent of fund holdings that fail company screen: 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
interest_bearing_securities_lite
Percent of fund holdings that fail company screen: Whether company's ratio of interest-bearing securities to market cap is greater than 33%. This is calculated as (cash and equivalents and short-term investments) / market cap.
string
iran
Percent of fund holdings that fail company screen: 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
military_contracting
Percent of fund holdings that fail company screen: Whether company generates revenue from military contracts. Includes companies that have contracts with military or national defense departments, regardless of the nature of those contracts.
string
misleading_communication
Percent of fund holdings that fail company screen: 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
misleading_communication_lite
Percent of fund holdings that fail company screen: Whether company has been involved in a misleading communication-related controversy that Ethos has rated as among the most severe over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
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.
string
music_lite
Percent of fund holdings that fail company screen: Whether company generates more than 10% of revenue from producing, distributing or selling music.
string
myanmar
Percent of fund holdings that fail company screen: 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
norges_bank
Percent of fund holdings that fail company screen: 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
Percent of fund holdings that fail company screen: 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
Percent of fund holdings that fail company screen: 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
Percent of fund holdings that fail company screen: 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
Percent of fund holdings that fail company screen: Whether company generates nuclear power or provides supplies enabling nuclear power.
string
nuclear_lite
Percent of fund holdings that fail company screen: Whether company generates nuclear power or provides supplies enabling nuclear power, and generates at least 10% of revenue from these activities.
string
oil_and_gas
Percent of fund holdings that fail company screen: Whether company is involved in oil and gas industries. Includes companies involved in the exploration, production, distribution, or marketing of oil and gas.
string
oil_and_gas_lite
Percent of fund holdings that fail company screen: Whether company is considered an oil and gas company and generates at least 10% of revenue from oil and gas-related sales. Includes companies involved in the exploration, production, distribution, or marketing of oil and gas.
string
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.
string
oppressive_cont
Percent of fund holdings that fail company screen: 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
oppressive_cont_lite
Percent of fund holdings that fail company screen: Whether company has been involved in a "very severe" controversy related to an oppressive government over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
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.
string
pork
Percent of fund holdings that fail company screen: Whether company produces or sells pork as part of its business model.
string
pork_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from the sale of pork or pork-based products.
string
pornography
Percent of fund holdings that fail company screen: 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
pornography_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from activities seeking 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
Percent of fund holdings that fail company screen: Whether company has been reported to engage in predatory lending.
string
prison_involvement
Percent of fund holdings that fail company screen: 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
prison_involvement_lite
Percent of fund holdings that fail company screen: Whether company is involved in private prisons or immigrant detention, defined as direct involvement in the operations of a prison or a prison 'harm score' higher than 13 from the nonprofit organization Worth Rises.
string
privacy_cont
Percent of fund holdings that fail company screen: 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
privacy_cont_lite
Percent of fund holdings that fail company screen: Whether company has been involved in a "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
Percent of fund holdings that fail company screen: 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
pro_life_lite
Percent of fund holdings that fail company screen: Whether company directly participates in or enables abortion, and generates at least 10% of revenue from activities related to abortion. Participation may include manufacturing of abortifacients and health care companies that perform abortions when not required to by law.
string
russia
Percent of fund holdings that fail company screen: 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
russia_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from activities in Russia, sales to Russia, or sales through partnerships with Russian companies.
string
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.
string
single_use_plastic_lite
Percent of fund holdings that fail company screen: Whether company produces or sells single-use plastic items as part of its core business model, and generates at least 10% of revenue from selling these items.
string
stem_cell
Percent of fund holdings that fail company screen: 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
stem_cell_lite
Percent of fund holdings that fail company screen: Whether company generates more than 10% of revenue from stem cell research or activities that depend on such research. Stem cell research may involve 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
Percent of fund holdings that fail company screen: 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
Percent of fund holdings that fail company screen: Whether company produces or sells sugary products as part of its business model.
string
sugar_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from the sale of sugary products.
string
syria
Percent of fund holdings that fail company screen: 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
tobacco
Percent of fund holdings that fail company screen: Whether company generates significant revenue from tobacco-related sales. This typically means deriving more than 1% of revenue from tobacco-related sales.
string
tobacco_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from tobacco products.
string
undermining_us_elections
Percent of fund holdings that fail company screen: 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
weapons
Percent of fund holdings that fail company screen: 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
weapons_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from the sale of weapons.
string
paged_funds
Number of paged funds returned
integer
total_funds
Number of total funds available based on the request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "funds" : [
  3. {
  4. "fund_id" : 553
  5. "symbol" : "VEGN"
  6. "cusip" : "26922A 297"
  7. "isin" : "US26922A2978"
  8. "name" : "US Vegan Climate ETF"
  9. "updated_at" : "2022-06-19"
  10. "price" : "200.5"
  11. "classifications" : {
  12. "fund_family" : "Technology & Communications"
  13. "industry" : "Software & Services"
  14. "peer_group" : "Big Tech - Major Diversified"
  15. }
  16. "geography" : {
  17. "region" : "United States"
  18. "hq_country" : "United States"
  19. "hq_state" : "California"
  20. "hq_city" : "Cupertino"
  21. }
  22. "market_cap" : "large"
  23. "screens" : {
  24. "abortion" : "2.23%"
  25. "advertising" : "0.74%"
  26. "alcohol" : "0%"
  27. "animal_testing" : "0%"
  28. "cannabis" : "0%"
  29. "carbon_emissions_intensity" : "5.58%"
  30. "coal" : "0%"
  31. "contraceptives" : "0.74%"
  32. "deforestation_financing" : "0.74%"
  33. "deforestation_supply_chain" : "2.23%"
  34. "discrimination_cont" : "12.64%"
  35. "environmental_cont" : "15.61%"
  36. "factory_farming" : "0%"
  37. "fast_food" : "0%"
  38. "fossil_fuel" : "0%"
  39. "fur" : "0%"
  40. "gambling" : "0%"
  41. "genetic_engineering" : "0%"
  42. "health_cont" : "6.32%"
  43. "human_trafficking" : "2.23%"
  44. "interest_based" : "21.93%"
  45. "interest_bearing_debt" : "13.75%"
  46. "interest_bearing_securities" : "8.18%"
  47. "misleading_communication" : "10.04%"
  48. "music" : "0.37%"
  49. "no_sbti" : "72.49%"
  50. "nuclear" : "0%"
  51. "oil_and_gas" : "0%"
  52. "opioid_cont" : "0.37%"
  53. "oppressive_cont" : "3.72%"
  54. "pork" : "0%"
  55. "pornography" : "0%"
  56. "predatory_lending" : "1.12%"
  57. "prison_involvement" : "3.35%"
  58. "privacy_cont" : "5.95%"
  59. "single_use_plastic" : "0.37%"
  60. "stem_cell" : "0%"
  61. "sugar" : "0.37%"
  62. "tobacco" : "0%"
  63. "weapons" : "0%"
  64. }
  65. }
  66. ],
  67. "paged_funds" : 1 ,
  68. "total_funds" : 1 ,
  69. "request_id" : "28HyTu"
  70. }

/funds/screens/get

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

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
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, Balanced, 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]
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 Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/funds/screens/get \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "symbols": [String],
  8. "count": 100,
  9. "offset": 0
  10. }
  11. }'
  1. const response = await client
  2. . getFundScreens (firm_id, secret , {
  3. symbols: [String] ,
  4. count: 100 ,
  5. offset: 0 ,
  6. })
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const funds = response.funds
  1. response = client.FundScreens.get(firm_id, secret)
  2. funds = response['funds']
  4. # Manipulate the count and offset parameters to paginate
  5. # funds and retrieve all available data
  6. while len (funds) < response[' total_funds' ]:
  7. response = client.FundScreens.get(firm_id, secret,
  8. offset= len (funds))
  9. funds.extend(response[ 'funds' ])
  1. response = @client .fund_screens. get ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # funds and retrieve all available data
  4. response = @client .fund_screens. get ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_funds = response[ 'funds' ]

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
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
Percent of fund holdings that fail company screen: Whether company is involved in advertising as part of its business model.
object
advertising_lite
Percent of fund holdings that fail company screen: Whether company generates more than 10% of revenue from advertising.
object
alcohol
Percent of fund holdings that fail company screen: 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_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from the sale of alcohol.
object
animal_treatment
Percent of fund holdings that fail company screen: 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
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
cannabis
Percent of fund holdings that fail company screen: Whether company is involved in the cannabis industry as part of its business model.
object
cannabis_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from the sale of cannabis.
object
carbon_emissions_intensity
Percent of fund holdings that fail company screen: 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.
object
coal
Percent of fund holdings that fail company screen: Whether company's primary business model involves thermal coal mining.
object
coal_lite
Percent of fund holdings that fail company screen: Whether company's primary business model is thermal coal mining, and company generates at least 10% of revenue from thermal coal mining.
object
contraceptives
Percent of fund holdings that fail company screen: Whether company manufactures contraceptives or derives significant revenue from selling contraceptives.
object
contraceptives_lite
Percent of fund holdings that fail company screen: Whether company derives more than 10% of its revenue from manufacturing or selling contraceptives.
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_financing_lite
Percent of fund holdings that fail company screen: Whether company is a major financer of deforestation. Defined as providing more than $250M USD to companies involved in deforestation.
object
deforestation_supply_chain
Percent of fund holdings that fail company screen: 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
deforestation_supply_chain_lite
Percent of fund holdings that fail company screen: Whether company is involved in deforestation in its supply chain and has been rated in the bottom quintile (lower 20%) by publicly-available sources.
object
discrimination_cont
Percent of fund holdings that fail company screen: 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".
object
discrimination_cont_lite
Percent of fund holdings that fail company screen: Whether company has been involved in a "very severe" controversy related to discrimination over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
object
environmental_cont
Percent of fund holdings that fail company screen: 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".
object
environmental_cont_lite
Percent of fund holdings that fail company screen: Whether company has been involved in an environment-related controversy that Ethos has rated as among the most severe over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
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
factory_farming_lite
Percent of fund holdings that fail company screen: Whether company has been reported to use factory farming in its supply chain and is among the bottom third of companies rated by the Better Business Benchmark on Farm Animal Welfare.
object
fast_food
Percent of fund holdings that fail company screen: Whether company is considered a fast-food company.
object
fast_food_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of its revenue from fast-food sales.
object
firearms
Percent of fund holdings that fail company screen: 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.
object
for_profit_health
Percent of fund holdings that fail company screen: 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.
object
fossil_fuel
Percent of fund holdings that fail company screen: Whether company is involved in fossil fuel production or distribution. Includes oil and gas companies, coal companies, and utilities that use fossil fuels.
object
fossil_fuel_lite
Percent of fund holdings that fail company screen: Whether company is considered a fossil fuel company and generates at least 10% of revenue from fossil fuel-related activities. Fossil fuel companies include oil and gas, coal, and utilities that use fossil fuels.
object
fur
Percent of fund holdings that fail company screen: Whether company produces or sells fur as a part of its business model.
object
fur_lite
Percent of fund holdings that fail company screen: Whether company produces or sells fur as a core part of its business model and generates at least 10% of revenue from fur products.
object
gambling
Percent of fund holdings that fail company screen: 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
gambling_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from gambling-related activities.
object
genetic_engineering
Percent of fund holdings that fail company screen: Whether company uses genetic engineering in its product development or other research.
object
genetic_engineering_lite
Percent of fund holdings that fail company screen: Whether company uses genetic engineering in its product development or other research, and generates at least 10% of revenue from activities that involve genetic engineering.
object
health_cont
Percent of fund holdings that fail company screen: 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".
object
health_cont_lite
Percent of fund holdings that fail company screen: Whether company has been involved in a health-related controversy that Ethos has rated as among the most severe over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
object
human_rights_cont
Percent of fund holdings that fail company screen: 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".
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
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_debt_lite
Percent of fund holdings that fail company screen: Whether company's debt-to-market-cap ratio is greater than 33%.
object
interest_bearing_securities
Percent of fund holdings that fail company screen: 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
interest_bearing_securities_lite
Percent of fund holdings that fail company screen: Whether company's ratio of interest-bearing securities to market cap is greater than 33%. This is calculated as (cash and equivalents and short-term investments) / market cap.
object
iran
Percent of fund holdings that fail company screen: 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
object
military_contracting
Percent of fund holdings that fail company screen: Whether company generates revenue from military contracts. Includes companies that have contracts with military or national defense departments, regardless of the nature of those contracts.
object
misleading_communication
Percent of fund holdings that fail company screen: 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".
object
misleading_communication_lite
Percent of fund holdings that fail company screen: Whether company has been involved in a misleading communication-related controversy that Ethos has rated as among the most severe over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
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
music_lite
Percent of fund holdings that fail company screen: Whether company generates more than 10% of revenue from producing, distributing or selling music.
object
myanmar
Percent of fund holdings that fail company screen: 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
object
norges_bank
Percent of fund holdings that fail company screen: 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
Percent of fund holdings that fail company screen: 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.
object
north_korea
Percent of fund holdings that fail company screen: 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
object
no_sbti
Percent of fund holdings that fail company screen: 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).
object
nuclear
Percent of fund holdings that fail company screen: Whether company generates nuclear power or provides supplies enabling nuclear power.
object
nuclear_lite
Percent of fund holdings that fail company screen: Whether company generates nuclear power or provides supplies enabling nuclear power, and generates at least 10% of revenue from these activities.
object
oil_and_gas
Percent of fund holdings that fail company screen: Whether company is involved in oil and gas industries. Includes companies involved in the exploration, production, distribution, or marketing of oil and gas.
object
oil_and_gas_lite
Percent of fund holdings that fail company screen: Whether company is considered an oil and gas company and generates at least 10% of revenue from oil and gas-related sales. Includes companies involved in the exploration, production, distribution, or marketing of 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
Percent of fund holdings that fail company screen: 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".
object
oppressive_cont_lite
Percent of fund holdings that fail company screen: Whether company has been involved in a "very severe" controversy related to an oppressive government over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
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
pork_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from the sale of pork or pork-based products.
object
pornography
Percent of fund holdings that fail company screen: 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.
object
pornography_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from activities seeking 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.
object
predatory_lending
Percent of fund holdings that fail company screen: Whether company has been reported to engage in predatory lending.
object
prison_involvement
Percent of fund holdings that fail company screen: 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.
object
prison_involvement_lite
Percent of fund holdings that fail company screen: Whether company is involved in private prisons or immigrant detention, defined as direct involvement in the operations of a prison or a prison 'harm score' higher than 13 from the nonprofit organization Worth Rises.
object
privacy_cont
Percent of fund holdings that fail company screen: 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".
object
privacy_cont_lite
Percent of fund holdings that fail company screen: Whether company has been involved in a "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".
object
pro_life
Percent of fund holdings that fail company screen: 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.
object
pro_life_lite
Percent of fund holdings that fail company screen: Whether company directly participates in or enables abortion, and generates at least 10% of revenue from activities related to abortion. Participation may include manufacturing of abortifacients and health care companies that perform abortions when not required to by law.
object
russia
Percent of fund holdings that fail company screen: 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
russia_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from activities in Russia, sales to Russia, or sales through partnerships with Russian companies.
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
single_use_plastic_lite
Percent of fund holdings that fail company screen: Whether company produces or sells single-use plastic items as part of its core business model, and generates at least 10% of revenue from selling these items.
object
stem_cell
Percent of fund holdings that fail company screen: 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.
object
stem_cell_lite
Percent of fund holdings that fail company screen: Whether company generates more than 10% of revenue from stem cell research or activities that depend on such research. Stem cell research may involve 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.
object
sudan
Percent of fund holdings that fail company screen: 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
object
sugar
Percent of fund holdings that fail company screen: Whether company produces or sells sugary products as part of its business model.
object
sugar_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from the sale of sugary products.
object
syria
Percent of fund holdings that fail company screen: 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
object
tobacco
Percent of fund holdings that fail company screen: Whether company generates significant revenue from tobacco-related sales. This typically means deriving more than 1% of revenue from tobacco-related sales.
object
tobacco_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from tobacco products.
object
undermining_us_elections
Percent of fund holdings that fail company screen: 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
weapons
Percent of fund holdings that fail company screen: 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.
object
weapons_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from the sale of weapons.
object
paged_funds
Number of paged funds returned
integer
total_funds
Number of total funds available based on the request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "funds" : [
  3. {
  4. "fund_id" : 553
  5. "symbol" : "VEGN"
  6. "cusip" : "26922A 297"
  7. "isin" : "US26922A2978"
  8. "name" : "US Vegan Climate ETF"
  9. "updated_at" : "2022-06-19"
  10. "screens" : {
  11. "advertising" : {
  12. "fail_count" : 2
  13. "fail_percent" : 0.02
  14. "revenue_percent" : null
  15. "updated_at" : "2022-06-19"
  16. }
  17. "..." : {
  18. "fail_count" : 10
  19. "fail_percent" : 0.11
  20. "revenue_percent" : null
  21. "updated_at" : "2022-06-19"
  22. }
  23. }
  24. }
  25. ],
  26. "paged_funds" : 1 ,
  27. "total_funds" : 1 ,
  28. "request_id" : "28HyTu"
  29. }

/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 you want to retrieve a Rating for. Defaults to returning ratings for all causes on Ethos and all "Impact Personas" of your clients and leads.

An "Impact Persona" is a combination of causes based on what a client or lead selects in their Impact Assessment. It can be a single cause or many causes that are important to a client.

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 object to be used with the request.
object
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, Balanced, 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]
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 Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/funds/ratings/get \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "symbols": [String],
  8. "count": 100,
  9. "offset": 0
  10. }
  11. }'
  1. const response = await client
  2. . getFundRatings (firm_id, secret , {
  3. symbols: [String] ,
  4. count: 100 ,
  5. offset: 0 ,
  6. })
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const funds = response.funds
  1. response = client.FundRatings.get(firm_id, secret)
  2. funds = response['funds']
  4. # Manipulate the count and offset parameters to paginate
  5. # funds and retrieve all available data
  6. while len (funds) < response[' total_funds' ]:
  7. response = client.FundRatings.get(firm_id, secret,
  8. offset= len (funds))
  9. funds.extend(response[ 'funds' ])
  1. response = @client .fund_ratings. get ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # funds and retrieve all available data
  4. response = @client .fund_ratings. get ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_funds = response[ 'funds' ]

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
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
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 funds
integer
percentile
Percentile of the rating, compared to all funds
integer
paged_funds
Number of paged funds returned
integer
total_funds
Number of total funds available based on the request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "funds" : [
  3. {
  4. "fund_id" : 2858
  5. "symbol" : "VEGN"
  6. "cusip" : "26922A 297"
  7. "isin" : "US26922A2978"
  8. "name" : "US Vegan Climate ETF"
  9. "updated_at" : "2022-06-19"
  10. "ratings" : [
  11. {
  12. "cause" : "Gender equality"
  13. "cause_id" : "37"
  14. "updated_at" : "2022-06-19"
  15. "score" : 88.2
  16. "rank" : 84
  17. "percentile" : 0.92
  18. }
  19. ]
  20. }
  21. ],
  22. "paged_funds" : 1 ,
  23. "total_funds" : 1 ,
  24. "request_id" : "28HyTu"
  25. }

/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.

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 object to be used with the request.
object
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, Balanced, 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]
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 Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/funds/metrics/get \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "symbols": [String],
  8. "count": 100,
  9. "offset": 0
  10. }
  11. }'
  1. const response = await client
  2. . getFundMetrics (firm_id, secret , {
  3. symbols: [String] ,
  4. count: 100 ,
  5. offset: 0 ,
  6. })
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const funds = response.funds
  1. response = client.FundMetrics.get(firm_id, secret)
  2. funds = response['funds']
  4. # Manipulate the count and offset parameters to paginate
  5. # funds and retrieve all available data
  6. while len (funds) < response[' total_funds' ]:
  7. response = client.FundMetrics.get(firm_id, secret,
  8. offset= len (funds))
  9. funds.extend(response[ 'funds' ])
  1. response = @client .fund_metrics. get ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # funds and retrieve all available data
  4. response = @client .fund_metrics. get ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_funds = response[ 'funds' ]

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
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
paged_funds
Number of paged funds returned
integer
total_funds
Number of total funds available based on the request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "funds" : [
  3. {
  4. "fund_id" : 2858
  5. "symbol" : "VEGN"
  6. "cusip" : "26922A 297"
  7. "isin" : "US26922A2978"
  8. "name" : "US Vegan Climate ETF"
  9. "updated_at" : "2022-06-19"
  10. "metrics" : [
  11. {
  12. "name" : "Advertising fines and violations"
  13. "metric_id" : "224"
  14. "description" : "Sum of fines incurred over the past four years from the Federal Trade Commission, related to advertising"
  15. "link" : "https://www.goodjobsfirst.org/violation-tracker"
  16. "uom" : "$ fines"
  17. "updated_at" : "2022-06-19"
  18. "esg_category" : "social"
  19. "score_base" : 42100000
  20. "score_normalized" : 0
  21. }
  22. ]
  23. }
  24. ],
  25. "paged_funds" : 1 ,
  26. "total_funds" : 1 ,
  27. "request_id" : "28HyTu"
  28. }

/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
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, Balanced, 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 Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/funds/list \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. }'
  1. const response = await client
  2. . listFunds (firm_id, secret )
  3. . catch ((err) => {
  4. // handle error
  5. })
  6. const funds = response.funds
  1. response = client.Funds.list(firm_id, secret)
  2. funds = response['funds']
  1. response = @client .funds. list ( @firm_id , @secret )
  2. total_funds = response[ 'funds' ]

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
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
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "funds" : [
  3. {
  4. "fund_id" : 553
  5. "symbol" : "VEGN"
  6. "cusip" : "26922A 297"
  7. "isin" : "US26922A2978"
  8. "name" : "US Vegan Climate ETF"
  9. "updated_at" : "2022-06-19"
  10. }
  11. ],
  12. "total_funds" : 1 ,
  13. "request_id" : "28HyTu"
  14. }

Cause endpoints

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

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
cause_ids
A list of cause_ids to retrieve metric data for
[integer]

Example request

/causes/list
Curl Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/causes/list \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "cause_ids": [Integer]
  8. }
  9. }'
  1. const response = await client
  2. . listCauses (firm_id, secret , {
  3. cause_ids: [Integer]
  4. })
  5. . catch ((err) => {
  6. // handle error
  7. })
  8. const causes = response.causes
  1. response = client.Causes.list(firm_id, secret)
  2. causes = response['causes']
  3. response = client.Causes.list(firm_id, secret,
  4. offset= len (causes))
  5. causes.extend(response[ 'causes' ])
  1. response = @client .causes. list ( @firm_id , @secret )
  2. total_companies = response[ 'causes' ]

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
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "causes" : [
  3. {
  4. "cause_id" : 32
  5. "name" : "Sustainable use of water"
  6. "description" : "Promote sustainable management of water everywhere"
  7. "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"
  8. "keywords" : "sustainable farming, industrial agriculture, sustainability, access to water, water stress"
  9. }
  10. ],
  11. "total_causes" : 1 ,
  12. "request_id" : "28HyTu"
  13. }

Metric endpoints

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

/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
metric_ids
A list of metric_ids to retrieve metric 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 Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/metrics/list \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "metric_ids": [Integer],
  8. "count": 100,
  9. "offset": 0
  10. }
  11. }'
  1. const response = await client
  2. . listMetrics (firm_id, secret , {
  3. metric_ids: [Integer]
  4. })
  5. . catch ((err) => {
  6. // handle error
  7. })
  8. const metrics = response.metrics
  1. response = client.Metrics.list(firm_id, secret)
  2. metrics = response['metrics']
  4. # Manipulate the count and offset parameters to paginate
  5. # metrics and retrieve all available data
  6. while len (metrics) < response[' total_metrics' ]:
  7. response = client.Metrics.list(firm_id, secret,
  8. offset= len (metrics))
  9. metrics.extend(response[ 'metrics' ])
  1. response = @client .metrics. list ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # metrics and retrieve all available data
  4. response = @client .metrics. list ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_metrics = response[ 'metrics' ]

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
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "metrics" : [
  3. {
  4. "metric_id" : 224
  5. "name" : "Fines and violations"
  6. "description" : "Sum of fines and violations incurred from US government agencies over the previous four years"
  7. "source" : "Violation Tracker"
  8. "link" : "https://www.goodjobsfirst.org/violation-tracker"
  9. "uom" : "$ fines"
  10. "updated_at" : "2021-04-15"
  11. "esg_category" : "governance"
  12. "normalization_scope" : "all"
  13. }
  14. ],
  15. "paged_metrics" : 1 ,
  16. "total_metrics" : 1 ,
  17. "request_id" : "28HyTu"
  18. }

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
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