Endpoint schema

Companies
Retrieve company-level information, ratings, screens and metrics
/companies/get
/companies/screens/get
/companies/ratings/get
/companies/metrics/get
Retrieve the list of available companies
/companies/list
Causes
Retrieve the list of available causes on Ethos
/causes/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
Help
Submit requests for coverage additions or customer support
/help/coverage_requests/get
/help/coverage_requests/create
/help/tickets/get
/help/tickets/create
Metrics
Retrieve the list of available metrics on Ethos
/metrics/list
Portfolios
Retrieve and submit data on one or more of your Portfolios
/portfolios/get
/portfolios/update
/portfolios/holdings/get
/portfolios/holdings/update
/portfolios/ratings/get
Questionnaires
Retrieve and submit data on one or more of your Questionnaires
/questionnaires/get
/questionnaires/responses/get
/questionnaires/questions/get
/questionnaires/answers/update
/questionnaires/approvals/get
Reports
Retrieve and submit data on one or more of your Reports
/reports/get

API Keys

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

Protocols and headers

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

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

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

API host

Development: https://development.ethosesg.com
Staging: https://staging.ethosesg.com
Production: https://production.ethosesg.com
All testing should be done in the Development and Staging environments.

Companies

Retrieve data on one or more companies, including company information, classification, ESG screens, ratings and metrics.
In this section
/companies/get
/companies/screens/get
/companies/ratings/get
/companies/metrics/get
/companies/list

/companies/get

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

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An optional object to be used with the request. If specified, options must not be null.
object
ids
A list of company ids to retrieve data for
[integer]
symbols
A list of company symbols (tickers) to retrieve company data for
[string]
cusips
A list of cusip numbers to retrieve company data for
[string]
isins
A list of ISIN numbers to retrieve company data for
[string]
uuids
A list of UUID numbers to retrieve company data for
[string]
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string
portfolio_ids
A list of portfolio IDs to retrieve data for held companies
[integer]
include_price
Whether or not to include price data (delayed 15-minutes) in the returned information
[true/false]
count
The number of companies to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer
offset
The number of companies to skip. The default value is 0.
Default: 0
Minimum: 0
integer

Example request

/companies/get
Curl 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
name
Name of the company
string
symbol
Unique symbol (ticker) for the company. Like all Ethos identifiers, the symbol is case sensitive
string
cusip
Unique CUSIP number of stock associated with company, if available
string
isin
Unique ISIN number of stock associated with company, if available
string
uuid
Unique UUID field used by ACA Group, if available
string
open_figi
Unique OpenFigi identifier, if available
string
summary_pdf_link
Link to a 3-page summary PDF of the company, if available
string
updated_at
Date the company record was last updated in Ethos' database
string
deleted_at
Date the company record was deleted from Ethos' database (for example, if it was acquired or ceased to operate). After the initial deletion date, a company will stay in Ethos' database for up to 3 months before being fully removed from the API.
string
classifications
A set of fields describing company classification (sector, industry and sub-industry)
object
sector
Sector of the company. Sector is the broadest classification that Ethos uses; potential values are Basic Materials, Consumer Goods, Energy, Financial, Food & Beverage, Healthcare, Industrials, Real Estate, Services, Technology & Communications, Transportation, and Utilities
string
industry
Industry of the company. Industry is a narrower classification than sector
string
sub_industry
Sub-industry of the company. Sub-industry is the narrowest classification that Ethos uses
string
geography
A set of fields describing company geography
object
region
Global region of the company. Possible values are Asia, Europe, North America ex. US, Rest of World, South America, and United States
string
hq_country
Country of company headquarters
string
hq_state
State or province of company headquarters, if available
string
hq_city
City of company headquarters, if available
string
financial
A set of fields describing company financial highlights
object
revenue
Trailing twelve-month revenue
integer
market_value
Market capitalization
integer
market_cap
Market cap category of company. Possible values are micro (less than $300M), small ($300M - $2B), medium ($2B - $10B), large (more than $10B), and mega (more than $200B)
string
net_income
Trailing twelve-month net income
integer
price
Share price of the associated security (delayed 15-minutes). In order to include this in the response, you must set the "include_price" option to "true" in the request.
string
earnings_per_share
Earnings per share
string
return_on_assets
Return on assets
string
return_on_equity
Return on equity
string
net_invested_capital
Total amount of non-financial assets, net of non-financial liabilities
string
dividends_per_share
Sum of declared dividends issued by a company for every ordinary share outstanding
string
net_debt
Short-term debt + long-term debt - cash and cash equivalents
string
cash_and_short_term
Cash and equivalents and short term investments in marketable securities
string
performance
A set of fields describing financial performance (returns) of an associated stock. Please note our terms of use for price and performance data.
object
return_one_day
One-day return of stock price, based on end-of-day prices
string
return_one_week
One-week return of stock price, based on end-of-day prices
string
return_one_month
One-month return of stock price, based on end-of-day prices
string
return_three_months
Three-month return of stock price, based on end-of-day prices
string
return_one_year
One-year return of stock price, based on end-of-day prices
string
return_two_years
Two-year return of stock price, based on end-of-day prices
string
return_three_years
Three-year return of stock price, based on end-of-day prices
string
return_five_years
Five-year return of stock price, based on end-of-day prices
string
executives
A set of fields describing company executives
[object]
name
Executive name
string
title
Executive title
string
is_ceo
Whether or not the executive is CEO of the company
boolean
age
Executive age
integer
pay
Executive compensation for last available year
integer
screens
A set of fields describing whether or not the company fails ESG-related screens
object
advertising
Whether company is involved in advertising as part of its core business model. This typically includes companies with greater than 10% of revenue from advertising.
string
alcohol
Whether company generates significant revenue from the sale of alcohol. This typically means that the company derives more than 1% of its revenue from alcohol-related sales.
string
alcohol_marketing
Whether company generates significant revenue from the sale of alcohol (generally more than 10% of total revenue), and does not have a policy for the responsible marketing of alcohol.
string
animal_treatment
Whether company has been reported to exploit animals or be involved in cruel treatment of animals, as reported by the nonprofit Cruelty Free Investing.
string
anti_abortion
Whether company has been reported to lobby against abortion or donate to politicians or groups working to erode female rights.
string
anti_personnel_mines
Whether company generates revenue from the sale of anti-personnel mines. Anti-personnel landmines are explosive devices designed to be detonated by the presence, proximity, or contact of a person.
string
antisemitism
Whether company has been reported to be involved in antisemitic or anti-Israel activities. Based on publicly-available information.
string
anti_social_publishing
Whether company generates revenue from anti-social publishing (including anti-social internet publishing).
string
arctic_drilling
Whether company is involved in arctic drilling for oil or gas. Does not include service companies or equipment manufacturers.
string
banned_chemicals
Whether company is involved in producing or selling hazardous chemicals or pesticides. "Hazardous chemicals or pesticides" means any substance mentioned by the European Chemicals Agency within the Prior Informed Consent Regulation or any unregulated hazardous chemicals, non-biological pesticides and hazardous wastes, or ozone-depleting substances as covered by the Montreal Protocol on Substances that Deplete the Ozone Layer (1989) or any similar international treaties (such as polychlorinated biphenyl, dichlorodiphenyltrichloroethane, chlorofluorocarbons, halons and asbestos).
string
banned_pharmaceuticals
Whether company has been reported to be involved in production or trade in controlled substances or pharmaceuticals subject to international ban.
string
biological_chemical_weapons
Whether company has been reported to be involved in producing or selling biological or chemical weapons. Biological and toxin weapons are either microorganisms like virus, bacteria or fungi, or toxic substances produced by living organisms that are produced and released deliberately to cause disease and death in humans, animals or plants. Chemical weapons are chemicals used to cause intentional death or harm through their toxic properties.
string
cannabis
Whether company is involved in the cannabis industry as part of its business model.
string
carbon_emissions_intensity
Whether company's carbon emissions intensity is significantly higher than peers. Carbon intensity is measured as (Scope 1 and 2 emissions) / $M revenue. Threshold for failing this screen is emissions intensity greater than 1 standard deviation above peer average.
string
carbon_underground
Whether company fails the Carbon Underground 200 (CU200) screen. The CU200 identifies the top 200 global publicly-listed coal, oil, and gas reserves owners ranked by the carbon emissions embedded in their reserves.
string
cu_coal
Whether company fails the Carbon Underground 200 (CU200) coal screen. The coal screen identifies the top global publicly-listed coal reserves owners ranked by the carbon emissions embedded in their reserves.
string
cu_oil_gas
Whether company fails the Carbon Underground 200 (CU200) oil and gas screen. The oil and gas screen identifies the top global publicly-listed oil and gas reserves owners ranked by the carbon emissions embedded in their reserves.
string
cu_tar_sands
Whether company fails the Carbon Underground 200 (CU200) tar sands screen. The tar sand screen identifies the top global publicly-listed tar sand reserves owners ranked by the carbon emissions embedded in their reserves.
string
cu_thermal_coal
Whether company fails the Carbon Underground 200 (CU200) thermal coal screen. The thermal coal screen identifies the top global publicly-listed thermal coal reserves owners ranked by the carbon emissions embedded in their reserves.
string
child_safety
Whether company has been involved in controversies related to child safety, including areas such as child labor, child exploitation, human trafficking, stolen identity, deep fakes, or other abuse of children. Based on ongoing monitoring of news stories and public information.
string
cluster_munitions
Whether company generates revenue from the sale of cluster munitions. Cluster munitions are munitions designed to disperse or release explosive submunitions or bomblets. Cluster munitions pose a threat to civilians during conflict by randomly scattering submunitions over a wide area. They pose a threat post-conflict by leaving submunitions that fail to explode upon impact and become de facto landmines. The 2008 Convention on Cluster Munitions prohibits the use, production, transfer, and stockpiling of cluster munitions.
string
coal
Whether company's primary business model involves coal mining, including thermal or metallurgical (coking).
string
conflict_minerals
Whether company generates revenue from the extraction or trading of minerals, coal and uranium from conflict areas.
string
contraceptives
Whether company manufactures contraceptives or derives significant revenue from selling contraceptives.
string
controversial_weapons
Whether company generates significant revenue from the sale of controversial weapons. Controversial weapons include weapons of mass destruction (chemical, biological and nuclear weapons), cluster munitions, antipersonnel mines, incendiary weapons, and other weapons considered to be excessively injurious, to have indiscriminate effects, or to damage the natural environment.
string
deforestation_financing
Whether company is a major financer of deforestation. Defined as providing more than $100M USD to companies involved in deforestation.
string
deforestation_supply_chain
Whether company is involved in deforestation in its supply chain and has been rated in the bottom two quintiles (lower 40%) by publicly-available sources.
string
depleted_uranium
Whether company has been reported to be involved in producing or selling depleted uranium. Depleted uranium is a dense metal produced as a by-product of enrichment of natural uranium for nuclear fuel. It is still radioactive, but at a much lower level than the starting material. It is used in armour-piercing shells and bombs, to give them more penetrating power.
string
discrimination_cont
Whether company has been involved in a "severe" or "very severe" controversy related to customer or employee discrimination over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
electrical_utility
Whether company derives revenue from electrical utility activities.
string
endangered_wildlife
Whether company derives revenue from trade in endangered wildlife; any species described as "endangered" or "critically endangered" in the most recent publication of the International Union for Conservation of Nature (IUCN) Red List; or any species subject to protection under the Convention on International Trade in Endangered Species of Wild Fauna and Flora (1973).
string
environmental_cont
Whether company has been involved in a "very severe" controversy related to the environment over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
eu_sanctions
Whether company is included in the European Union (EU) sanctions list. The EU uses restrictive measures, or sanctions, to promote the objectives of the Common Foreign and Security Policy (CFSP). These include safe-guarding the EU's values, its fundamental interests and security; consolidating and supporting democracy, the rule of law, human rights and the principles of international law; preserving peace; preventing conflicts and strengthening international security. This screen includes only companies specifically listed by the EU.
string
factory_farming
Whether company has been reported to use factory farming in its supply chain.
string
fast_food
Whether company is involved in the fast-food industry, and derives at least 10% of its revenue from fast food.
string
firearms
Whether company generates significant revenue from production or sale of firearms intended for civilian (non-military) use. This typically means deriving more than 1% of revenue from such sales. Firearms include handguns, pistols, shotguns, rifles, revolvers, and ammunition.
string
food_commodity_derivatives
Whether company is involved in food commodity derivatives trading or speculative transactions that may contribute to price inflation in basic agricultural or marine commodities (e.g., wheat, rice, meat, soy, sugar, dairy, fish, corn).
string
for_profit_health
Whether company is a for-profit healthcare provider. Includes for-profit hospitals, home healthcare providers, long-term care providers, and other specialty providers. Does not include pharmaceutical companies, biotech, medical equipment manufacturers, distributors, or other healthcare companies that are not directly involved in providing care.
string
fossil_fuel
Whether company is involved in fossil fuel production or distribution. Includes oil and gas companies, coal companies, and utilities that use fossil fuels.
string
fur
Whether company produces or sells fur as a part of its business model.
string
gambling
Whether company generates significant revenue from gambling-related activities. This typically means that the company derives more than 1% of its revenue from gambling-related activities.
string
genetic_engineering
Whether company uses genetic engineering in its product development or other research.
string
health_cont
Whether company has been involved in a "very severe" controversy related to health and well-being over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
human_rights_cont
Whether company has been involved in a "very severe" controversy related to human rights or involvement with an oppressive government over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
human_trafficking
Whether company has been reported to be involved in human trafficking over the past 5 years, either directly or through its supply chain.
string
illegal_activities
Whether company has products or activities that are deemed illegal under international law or local law where it is headquartered (including recreational cannabis).
string
ilo
Whether company has been involved in a "severe" or "very severe" controversy related to violations of the International Labor Organization (ILO) Conventions. Conventions cover areas such as basic human rights, minimum wages, industrial relations, employment policy, social dialogue, social security and other issues.
string
interest_based
Whether company offers an interest-based financial product as part of its business model.
string
interest_bearing_debt
Whether company's debt-to-market-cap ratio is greater than 30%.
string
interest_bearing_securities
Whether company's ratio of interest-bearing securities to market cap is greater than 30%. This is calculated as (cash and equivalents and short-term investments) / market cap.
string
iran
Whether company has been reported to have involvement in Iran over the past 5 years, either through operations, investment, or partnership with an Iranian entity. Indicates reported involvement, and not necessarily any violation of sanctions
string
land_use_biodiversity
Whether company has faced "high" or "severe" controversies related to land use or biodiversity. Also includes companies that work with soy, cattle or timber and have been reported to have a significant negative impact on deforestation.
string
military_contracting
Whether company generates revenue from military contracts related to weapons or combat operations.
string
misleading_communication
Whether company has been involved in a "severe" or "very severe" controversy related to misleading communication over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
music
Whether company is involved in producing, distributing or selling music as part of its business model.
string
myanmar
Whether company has been reported to have involvement with Myanmar (Burma), or has been reported to support the military government in Myanmar as a supplier or funder. Indicates reported involvement, and not necessarily any violation of sanctions
string
non_sustainable_palm_oil
Whether company is involved in non-sustainable palm-oil production or distribution. Defined as a) not having achieved or committed to achieve Roundtable on Sustainable Palm Oil (RSPO) certification or other internationally-recognized sustainable palm oil certifications, and b) any of the following: involvement in unresolved land rights conflicts, inability to prove the legality of operations, no undertaking of social and environmental impact assessments, not consulting with stakeholders prior to commencing operations, or involvement in illegal logging.
string
norges_bank
Whether company is on the exclusion list created by Norges Bank, the central bank of Norway. The exclusion list is based on recommendations from Norway's Council on Ethics.
string
northern_ireland
Whether company has operations in Northern Ireland and may not be compliant with the Macbride Principles, based on publicly-available information. Based in part on analysis by the Equality Commission for Northern Ireland covering companies with at least 25 employees in Northern Ireland.
string
north_korea
Whether company has been reported to have involvement in North Korea in the past 5 years, either through operations, investment, or partnership with a North Korean entity. Indicates reported involvement, and not necessarily any violation of sanctions
string
no_sbti
Whether company has committed to a "science-based" target to reduce its emissions in line with the Paris Agreement on climate change mitigation. Uses data from the Science-Based Targets Initiative (SBTI).
string
nuclear
Whether company generates nuclear power or provides supplies enabling nuclear power.
string
oecd
Whether company has been involved in a "severe" or "very severe" controversy related to violations of the Organization for Economic Cooperation and Development (OECD) Guidelines for Multinational Enterprises. The guidelines are "non-binding principles and standards for responsible business conduct in a global context consistent with applicable laws and internationally recognised standards."
string
oil_and_gas
Whether company is involved in oil and gas industries. Includes companies involved in the exploration, production, distribution, or marketing of oil and gas.
string
opioid_cont
Whether company has been reported to be involved in the opiod crisis in the United States.
string
oppressive_cont
Whether company has been involved in a "severe" or "very severe" controversy with an oppressive government over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
palestinian_human_rights
Whether company has been reported to be involved in human rights violations against the Palestinian people. Based on publicly-available information.
string
pharma_cont
Whether company has been reported to be involved in pharmaceutical-related controversies such as price-gouging or the opioid crisis.
string
pork
Whether company produces or sells pork as part of its business model.
string
pornography
Whether a core part of company's business seeks to appeal to a prurient interest in sex or to incite sexual excitement. Includes companies that produce pornographic material as well as companies that feature adult entertainment, such as casinos.
string
predatory_lending
Whether company has been reported to engage in predatory lending.
string
prison_involvement
Whether company is involved in private prisons or immigrant detention. Involvement defined as direct involvement in the operations of a prison or a prison 'harm score' of 11 or higher from the nonprofit organization Worth Rises.
string
privacy_cont
Whether company has been involved in a "severe" or "very severe" controversy related to privacy over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
pro_life
Whether company directly participates in or enables abortion. Direct participation may include manufacturing of abortifacients and health care companies that perform abortions when not required to by law.
string
russia
Whether company is headquartered in Russia, has significant operations in Russia, or has significant ties (such as a joint venture or major investment) with Russian companies.
string
single_use_plastic
Whether company produces or sells single-use plastic items as part of its business model.
string
stem_cell
Whether company performs research on human fetuses or embryos that results in the end of pre-natal life, makes use of tissue derived from abortions, or otherwise violates the dignity of a developing person.
string
sudan
Whether company has been reported to have involvement in Sudan over the past 5 years, either through operations, investment, or partnership with a Sudanese entity. Indicates reported involvement, and not necessarily any violation of sanctions
string
sugar
Whether company produces or sells sugary products as part of its business model.
string
syria
Whether company has been reported to have involvement in Syria over the past 5 years, either through operations, investment, or partnership with a Syrian entity. Indicates reported involvement, and not necessarily any violation of sanctions
string
tar_sands
Whether company is involved in the extraction of tar sands, sometimes called oil sands.
string
thermal_coal
Whether company's primary business model involves thermal coal mining.
string
tobacco
Whether company generates significant revenue from tobacco-related sales. This typically means deriving more than 1% of revenue from tobacco-related sales.
string
tobacco_gics
Whether is classified under the GICS Sub-Industry of Tobacco. GICS defines this Sub-Industry as "Manufacturers of cigarettes and other tobacco products such as e-cigarettes. This Sub-Industry excludes companies primarily engaged in producing cannabis related products."
string
uk_sanctions
Whether company is included in the United Kingdom's sanctions list (companies designated or specified under regulations made under the Sanctions and Anti-Money Laundering Act 2018). This screen includes only companies specifically listed by the UK.
string
undermining_us_elections
Whether company has been reported to donate to US members of Congress who voted not to certify the 2020 election results. Data from the transparency group Accountable.US.
string
ungc
Whether company has been involved in a "severe" or "very severe" controversy related to violations of the United Nations Global Compact principles. Principles cover areas such as human rights, freedom from forced labor and discrimination, anti-corruption, and environmental protection.
string
ungp
Whether company has been involved in a "severe" or "very severe" controversy related to violations of the United Nations Guiding Principles (UNGP) on Business and Human Rights. The UNGP's foundational principle for businesses is that they should respect human rights, meaning "they should avoid infringing on the human rights of others and should address adverse human rights impacts with which they are involved."
string
us_ofac
Whether company is included in sanctions lists from the United States Office of Foreign Assets Control (OFAC), including the list of Specially Designated Nationals (SDNs) and non-SDN lists, or the Bureau of Industry and Security Entity List. This screen includes only companies specifically listed by the US.
string
weapons
Whether company generates significant revenue from weapons-related sales, including "conventional" weapons and "controversial" weapons. Controversial weapons include weapons of mass destruction (chemical, biological and nuclear weapons), cluster munitions, antipersonnel mines, incendiary weapons, and other weapons considered to be excessively injurious, to have indiscriminate effects, or to damage the natural environment.
string
offset_companies
Number of companies offset in the request
integer
paged_companies
Number of paged companies returned
integer
total_companies
Number of total companies available based on the request
integer
max_id
Maximum id for all companies matching your request
integer
request_id
Unique id for the request
string

Example response

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

/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
ids
A list of company ids to retrieve data for
[integer]
symbols
A list of company symbols (tickers) to retrieve company data for
[string]
cusips
A list of cusip numbers to retrieve company data for
[string]
isins
A list of ISIN numbers to retrieve company data for
[string]
uuids
A list of UUID numbers to retrieve company data for
[string]
portfolio_ids
A list of portfolio IDs to retrieve data for held companies
[integer]
count
The number of companies to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string
offset
The number of companies to skip. The default value is 0.
Default: 0
Minimum: 0
integer

Example request

/companies/screens/get
Curl 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
uuid
Unique UUID field used by ACA Group, if available
string
open_figi
Unique OpenFigi identifier, if available
string
name
Name of the company
string
updated_at
Date the company record was last updated in Ethos ESG's database
string
screens
A set of fields describing whether or not the company fails ESG-related screens, as well as percent of revenue derived from each screened activity
object
advertising
Whether company is involved in advertising as part of its core business model. This typically includes companies with greater than 10% of revenue from advertising.
object
alcohol
Whether company generates significant revenue from the sale of alcohol. This typically means that the company derives more than 1% of its revenue from alcohol-related sales.
object
alcohol_marketing
Whether company generates significant revenue from the sale of alcohol (generally more than 10% of total revenue), and does not have a policy for the responsible marketing of alcohol.
object
animal_treatment
Whether company has been reported to exploit animals or be involved in cruel treatment of animals, as reported by the nonprofit Cruelty Free Investing.
object
anti_abortion
Whether company has been reported to lobby against abortion or donate to politicians or groups working to erode female rights.
object
anti_personnel_mines
Whether company generates revenue from the sale of anti-personnel mines. Anti-personnel landmines are explosive devices designed to be detonated by the presence, proximity, or contact of a person.
object
antisemitism
Whether company has been reported to be involved in antisemitic or anti-Israel activities. Based on publicly-available information.
object
anti_social_publishing
Whether company generates revenue from anti-social publishing (including anti-social internet publishing).
object
arctic_drilling
Whether company is involved in arctic drilling for oil or gas. Does not include service companies or equipment manufacturers.
object
banned_chemicals
Whether company is involved in producing or selling hazardous chemicals or pesticides. "Hazardous chemicals or pesticides" means any substance mentioned by the European Chemicals Agency within the Prior Informed Consent Regulation or any unregulated hazardous chemicals, non-biological pesticides and hazardous wastes, or ozone-depleting substances as covered by the Montreal Protocol on Substances that Deplete the Ozone Layer (1989) or any similar international treaties (such as polychlorinated biphenyl, dichlorodiphenyltrichloroethane, chlorofluorocarbons, halons and asbestos).
object
banned_pharmaceuticals
Whether company has been reported to be involved in production or trade in controlled substances or pharmaceuticals subject to international ban.
object
biological_chemical_weapons
Whether company has been reported to be involved in producing or selling biological or chemical weapons. Biological and toxin weapons are either microorganisms like virus, bacteria or fungi, or toxic substances produced by living organisms that are produced and released deliberately to cause disease and death in humans, animals or plants. Chemical weapons are chemicals used to cause intentional death or harm through their toxic properties.
object
cannabis
Whether company is involved in the cannabis industry as part of its business model.
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
carbon_underground
Whether company fails the Carbon Underground 200 (CU200) screen. The CU200 identifies the top 200 global publicly-listed coal, oil, and gas reserves owners ranked by the carbon emissions embedded in their reserves.
object
cu_coal
Whether company fails the Carbon Underground 200 (CU200) coal screen. The coal screen identifies the top global publicly-listed coal reserves owners ranked by the carbon emissions embedded in their reserves.
object
cu_oil_gas
Whether company fails the Carbon Underground 200 (CU200) oil and gas screen. The oil and gas screen identifies the top global publicly-listed oil and gas reserves owners ranked by the carbon emissions embedded in their reserves.
object
cu_tar_sands
Whether company fails the Carbon Underground 200 (CU200) tar sands screen. The tar sand screen identifies the top global publicly-listed tar sand reserves owners ranked by the carbon emissions embedded in their reserves.
object
cu_thermal_coal
Whether company fails the Carbon Underground 200 (CU200) thermal coal screen. The thermal coal screen identifies the top global publicly-listed thermal coal reserves owners ranked by the carbon emissions embedded in their reserves.
object
child_safety
Whether company has been involved in controversies related to child safety, including areas such as child labor, child exploitation, human trafficking, stolen identity, deep fakes, or other abuse of children. Based on ongoing monitoring of news stories and public information.
object
cluster_munitions
Whether company generates revenue from the sale of cluster munitions. Cluster munitions are munitions designed to disperse or release explosive submunitions or bomblets. Cluster munitions pose a threat to civilians during conflict by randomly scattering submunitions over a wide area. They pose a threat post-conflict by leaving submunitions that fail to explode upon impact and become de facto landmines. The 2008 Convention on Cluster Munitions prohibits the use, production, transfer, and stockpiling of cluster munitions.
object
coal
Whether company's primary business model involves coal mining, including thermal or metallurgical (coking).
object
conflict_minerals
Whether company generates revenue from the extraction or trading of minerals, coal and uranium from conflict areas.
object
contraceptives
Whether company manufactures contraceptives or derives significant revenue from selling contraceptives.
object
controversial_weapons
Whether company generates significant revenue from the sale of controversial weapons. Controversial weapons include weapons of mass destruction (chemical, biological and nuclear weapons), cluster munitions, antipersonnel mines, incendiary weapons, and other weapons considered to be excessively injurious, to have indiscriminate effects, or to damage the natural environment.
object
deforestation_financing
Whether company is a major financer of deforestation. Defined as providing more than $100M USD to companies involved in deforestation.
object
deforestation_supply_chain
Whether company is involved in deforestation in its supply chain and has been rated in the bottom two quintiles (lower 40%) by publicly-available sources.
object
depleted_uranium
Whether company has been reported to be involved in producing or selling depleted uranium. Depleted uranium is a dense metal produced as a by-product of enrichment of natural uranium for nuclear fuel. It is still radioactive, but at a much lower level than the starting material. It is used in armour-piercing shells and bombs, to give them more penetrating power.
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
electrical_utility
Whether company derives revenue from electrical utility activities.
object
endangered_wildlife
Whether company derives revenue from trade in endangered wildlife; any species described as "endangered" or "critically endangered" in the most recent publication of the International Union for Conservation of Nature (IUCN) Red List; or any species subject to protection under the Convention on International Trade in Endangered Species of Wild Fauna and Flora (1973).
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
eu_sanctions
Whether company is included in the European Union (EU) sanctions list. The EU uses restrictive measures, or sanctions, to promote the objectives of the Common Foreign and Security Policy (CFSP). These include safe-guarding the EU's values, its fundamental interests and security; consolidating and supporting democracy, the rule of law, human rights and the principles of international law; preserving peace; preventing conflicts and strengthening international security. This screen includes only companies specifically listed by the EU.
object
factory_farming
Whether company has been reported to use factory farming in its supply chain.
object
fast_food
Whether company is involved in the fast-food industry, and derives at least 10% of its revenue from fast food.
object
firearms
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
food_commodity_derivatives
Whether company is involved in food commodity derivatives trading or speculative transactions that may contribute to price inflation in basic agricultural or marine commodities (e.g., wheat, rice, meat, soy, sugar, dairy, fish, corn).
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
fur
Whether company produces or sells fur as a part of its business model.
object
gambling
Whether company generates significant revenue from gambling-related activities. This typically means that the company derives more than 1% of its revenue from gambling-related activities.
object
genetic_engineering
Whether company uses genetic engineering in its product development or other research.
object
health_cont
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
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
illegal_activities
Whether company has products or activities that are deemed illegal under international law or local law where it is headquartered (including recreational cannabis).
object
ilo
Whether company has been involved in a "severe" or "very severe" controversy related to violations of the International Labor Organization (ILO) Conventions. Conventions cover areas such as basic human rights, minimum wages, industrial relations, employment policy, social dialogue, social security and other issues.
object
interest_based
Whether company offers an interest-based financial product as part of its business model.
object
interest_bearing_debt
Whether company's debt-to-market-cap ratio is greater than 30%.
object
interest_bearing_securities
Whether company's ratio of interest-bearing securities to market cap is greater than 30%. This is calculated as (cash and equivalents and short-term investments) / market cap.
object
iran
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
land_use_biodiversity
Whether company has faced "high" or "severe" controversies related to land use or biodiversity. Also includes companies that work with soy, cattle or timber and have been reported to have a significant negative impact on deforestation.
object
military_contracting
Whether company generates revenue from military contracts related to weapons or combat operations.
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
music
Whether company is involved in producing, distributing or selling music as part of its business model.
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
non_sustainable_palm_oil
Whether company is involved in non-sustainable palm-oil production or distribution. Defined as a) not having achieved or committed to achieve Roundtable on Sustainable Palm Oil (RSPO) certification or other internationally-recognized sustainable palm oil certifications, and b) any of the following: involvement in unresolved land rights conflicts, inability to prove the legality of operations, no undertaking of social and environmental impact assessments, not consulting with stakeholders prior to commencing operations, or involvement in illegal logging.
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
oecd
Whether company has been involved in a "severe" or "very severe" controversy related to violations of the Organization for Economic Cooperation and Development (OECD) Guidelines for Multinational Enterprises. The guidelines are "non-binding principles and standards for responsible business conduct in a global context consistent with applicable laws and internationally recognised standards."
object
oil_and_gas
Whether company is involved in oil and gas industries. Includes companies involved in the exploration, production, distribution, or marketing of oil and gas.
object
opioid_cont
Whether company has been reported to be involved in the opiod crisis in the United States.
object
oppressive_cont
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
palestinian_human_rights
Whether company has been reported to be involved in human rights violations against the Palestinian people. Based on publicly-available information.
object
pharma_cont
Whether company has been reported to be involved in pharmaceutical-related controversies such as price-gouging or the opioid crisis.
object
pork
Whether company produces or sells pork as part of its business model.
object
pornography
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
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
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
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
russia
Whether company is headquartered in Russia, has significant operations in Russia, or has significant ties (such as a joint venture or major investment) with Russian companies.
object
single_use_plastic
Whether company produces or sells single-use plastic items as part of its business model.
object
stem_cell
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
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
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
tar_sands
Whether company is involved in the extraction of tar sands, sometimes called oil sands.
object
thermal_coal
Whether company's primary business model involves thermal coal mining.
object
tobacco
Whether company generates significant revenue from tobacco-related sales. This typically means deriving more than 1% of revenue from tobacco-related sales.
object
tobacco_gics
Whether is classified under the GICS Sub-Industry of Tobacco. GICS defines this Sub-Industry as "Manufacturers of cigarettes and other tobacco products such as e-cigarettes. This Sub-Industry excludes companies primarily engaged in producing cannabis related products."
object
uk_sanctions
Whether company is included in the United Kingdom's sanctions list (companies designated or specified under regulations made under the Sanctions and Anti-Money Laundering Act 2018). This screen includes only companies specifically listed by the UK.
object
undermining_us_elections
Whether company has been reported to donate to US members of Congress who voted not to certify the 2020 election results. Data from the transparency group Accountable.US.
object
ungc
Whether company has been involved in a "severe" or "very severe" controversy related to violations of the United Nations Global Compact principles. Principles cover areas such as human rights, freedom from forced labor and discrimination, anti-corruption, and environmental protection.
object
ungp
Whether company has been involved in a "severe" or "very severe" controversy related to violations of the United Nations Guiding Principles (UNGP) on Business and Human Rights. The UNGP's foundational principle for businesses is that they should respect human rights, meaning "they should avoid infringing on the human rights of others and should address adverse human rights impacts with which they are involved."
object
us_ofac
Whether company is included in sanctions lists from the United States Office of Foreign Assets Control (OFAC), including the list of Specially Designated Nationals (SDNs) and non-SDN lists, or the Bureau of Industry and Security Entity List. This screen includes only companies specifically listed by the US.
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
offset_companies
Number of companies offset in the request
integer
paged_companies
Number of paged companies returned
integer
total_companies
Number of total companies available based on the request
integer
max_id
Maximum id for all companies matching your request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "companies" : [
  3. {
  4. "company_id" : 553,
  5. "symbol" : "AAPL",
  6. "cusip" : "37833100",
  7. "isin" : "US0378331005",
  8. "uuid" : "II|V1|FactSetId|000C7F-E|17",
  9. "open_figi" : "BBG000B9XRY4",
  10. "name" : "Apple",
  11. "updated_at" : "2022-06-19"
  12. "screens" : {
  13. "advertising" : {
  14. "pass" : "false",
  15. "revenue_percent" : 0.157,
  16. "updated_at" : "2022-06-19"
  17. },
  18. "alcohol" : {
  19. "pass" : "true",
  20. "revenue_percent" : 0,
  21. "updated_at" : "2022-06-19"
  22. },
  23. "animal_testing" : {
  24. "pass" : "true",
  25. "revenue_percent" : 0,
  26. "updated_at" : "2022-06-19"
  27. },
  28. "cannabis" : {
  29. "pass" : "true",
  30. "revenue_percent" : 0,
  31. "updated_at" : "2022-06-19"
  32. },
  33. "carbon_emissions_intensity" : {
  34. "pass" : "true",
  35. "revenue_percent" : 0,
  36. "updated_at" : "2022-06-19"
  37. },
  38. "..." : {
  39. "pass" : "true",
  40. "revenue_percent" : 0,
  41. "updated_at" : "2022-06-19"
  42. }
  43. }
  44. }
  45. ],
  46. "offset_companies" : 0 ,
  47. "paged_companies" : 1 ,
  48. "total_companies" : 1 ,
  49. "max_id" : 100
  50. "request_id" : "28HyTu"
  51. }

/companies/ratings/get

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

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

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.
object
ids
A list of company ids to retrieve data for
[integer]
symbols
A list of company symbols (tickers) to retrieve company data for
[string]
cusips
A list of cusip numbers to retrieve company data for
[string]
isins
A list of ISIN numbers to retrieve company data for
[string]
uuids
A list of UUID numbers to retrieve company data for
[string]
portfolio_ids
A list of portfolio IDs to retrieve data for held companies
[integer]
cause_ids
A list of cause_ids to retrieve company data for. If not specified, ratings for all causes for requested companies will be returned
[integer]
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string
count
The number of companies to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer

Example request

/companies/ratings/get
Curl 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
uuid
Unique UUID field used by ACA Group, if available
string
open_figi
Unique OpenFigi identifier, if available
string
name
Name of the company
string
updated_at
Date the company record was last updated in Ethos ESG's database
string
ratings
A set of fields describing ESG ratings associated with the company
object
cause
Name of the cause or "Impact Persona" for which the company is rated. Impact Personas are combinations of causes based on what a client or lead selects in their Impact Assessment.
string
cause_id
Unique id of the cause. Note that this field does not apply to "Impact Personas" (combinations of causes). This field will be a null value for Impact Personas.
integer
client_persona
Whether or not the cause is an Impact Persona of one or more of your clients or leads. Impact Personas can reflect a single cause or multiple causes, depending on what the client selects in their Impact Assessment.
boolean
date
Date of the rating
date
score
Score of the rating, from 0 (worst) to 100 (best)
integer
rank
Rank of the rating, compared to all companies
integer
percentile
Percentile of the rating, compared to all companies
integer
offset_companies
Number of companies offset in the request
integer
paged_companies
Number of paged companies returned
integer
total_companies
Number of total companies available based on the request
integer
max_id
Maximum id for all companies matching your request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "companies" : [
  3. {
  4. "company_id" : 553,
  5. "symbol" : "AAPL",
  6. "cusip" : "37833100",
  7. "isin" : "US0378331005",
  8. "uuid" : "II|V1|FactSetId|000C7F-E|17",
  9. "open_figi" : "BBG000B9XRY4",
  10. "name" : "Apple",
  11. "updated_at" : "2022-06-19",
  12. "ratings" : [
  13. {
  14. "cause" : "Gender equality",
  15. "cause_id" : "37",
  16. "updated_at" : "2022-06-19",
  17. "score" : 84.1,
  18. "rank" : 119,
  19. "percentile" : 0.85
  20. }
  21. ]
  22. }
  23. ],
  24. "offset_companies" : 0 ,
  25. "paged_companies" : 1 ,
  26. "total_companies" : 1 ,
  27. "max_id" : 100
  28. "request_id" : "28HyTu"
  29. }

/companies/metrics/get

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

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

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An object to be used with the request.
object
ids
A list of company ids to retrieve data for
[integer]
symbols
A list of company symbols (tickers) to retrieve company data for
[string]
cusips
A list of cusip numbers to retrieve company data for
[string]
isins
A list of ISIN numbers to retrieve company data for
[string]
uuids
A list of UUID numbers to retrieve company data for
[string]
portfolio_ids
A list of portfolio IDs to retrieve data for held companies
[integer]
metric_ids
A list of metric_ids to retrieve company data for. If not specified, all metrics for requested companies will be returned
[integer]
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string
count
The number of companies to fetch.
Default: 10
Minimum: 1
Maximum: 10
integer

Example request

/companies/metrics/get
Curl 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
uuid
Unique UUID field used by ACA Group, if available
string
open_figi
Unique OpenFigi identifier, if available
string
name
Name of the company
string
updated_at
Date the company record was last updated in Ethos ESG's database
string
metrics
A set of fields describing ESG metrics associated with the company
object
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 sub-industry. Ethos uses peer averages when no data is available for a company
boolean
offset_companies
Number of companies offset in the request
integer
paged_companies
Number of paged companies returned
integer
total_companies
Number of total companies available based on the request
integer
max_id
Maximum id for all companies matching your request
integer
request_id
Unique id for the request
string

Example response

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

/companies/list

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

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

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An optional object to be used with the request. If specified, options must not be null.
object
ids
A list of company ids to retrieve data for
[integer]
symbols
A list of company symbols (tickers) to retrieve company data (identifiers) for
[string]
cusips
A list of cusip numbers to retrieve company data (identifiers) for
[string]
isins
A list of ISIN numbers to retrieve company data (identifiers) for
[string]
uuids
A list of UUID numbers to retrieve company data for
[string]
portfolio_ids
A list of portfolio IDs to retrieve data for held companies
[integer]

Example request

/companies/list
Curl 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
uuid
Unique UUID field used by ACA Group, if available
string
open_figi
Unique OpenFigi identifier, if available
string
name
Name of the company
string
updated_at
Date the company record was last updated in Ethos ESG's database
string
total_companies
Number of total companies available based on the request
integer
max_id
Maximum id for all companies matching your request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "companies" : [
  3. {
  4. "company_id" : 553,
  5. "symbol" : "AAPL",
  6. "cusip" : "37833100",
  7. "isin" : "US0378331005",
  8. "uuid" : "II|V1|FactSetId|000C7F-E|17",
  9. "open_figi" : "BBG000B9XRY4",
  10. "name" : "Apple",
  11. "updated_at" : "2022-06-19"
  12. }
  13. ],
  14. "total_companies" : 1 ,
  15. "max_id" : 100
  16. "request_id" : "28HyTu"
  17. }

Causes

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
ids
A list of cause ids to retrieve 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
max_id
Maximum id for all causes matching your 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. "max_id" : 100
  13. "request_id" : "28HyTu"
  14. }

Funds

Retrieve current data on one or more funds, including fund information, classification, ESG screens, ratings and metrics.
In this section
/funds/get
/funds/screens/get
/funds/ratings/get
/funds/metrics/get
/funds/list

/funds/get

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

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An optional object to be used with the request. If specified, options must not be null.
object
ids
A list of fund ids to retrieve data for
[integer]
symbols
A list of fund symbols (tickers) to retrieve fund data for
[string]
cusips
A list of cusip numbers to retrieve fund data for
[string]
isins
A list of ISIN numbers to retrieve fund data for
[string]
asset_classes
A list of asset classes to filter fund data. Options include Alternatives, Diversified, Cash, Equities, Fixed income, Infrastructure, and Property
[string]
domiciles
A list of domiciles to filter fund data. Current options include Australia, Europe, and United States
[string]
fund_types
A list of fund types to filter fund data. Options include ETF, Index, Mutual Fund, and SMA
[string]
categories
A list of fund categories to filter fund data
[string]
fund_families
A list of fund families to filter fund data
[string]
include_price
Whether or not to include price data (delayed 15-minutes) in the returned information
[true/false]
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string
count
The number of funds to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer
offset
The number of funds to skip. The default value is 0.
Default: 0
Minimum: 0
integer

Example request

/funds/get
Curl 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
open_figi
Unique OpenFigi identifier, if available
string
name
Name of the fund
string
updated_at
Date the fund record was last updated in Ethos ESG's database
string
price
Share price of the associated security (delayed 15-minutes)
string
classifications
A set of fields describing fund classifications
object
fund_type
Type of fund (ETF, Mutual Fund, or Index)
string
asset_class
Asset class of the fund
string
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 core business model. This typically includes companies with greater 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_marketing
Percent of fund holdings that fail company screen: Whether company generates significant revenue from the sale of alcohol (generally more than 10% of total revenue), and does not have a policy for the responsible marketing of alcohol.
string
animal_treatment
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
anti_personnel_mines
Percent of fund holdings that fail company screen: Whether company generates revenue from the sale of anti-personnel mines. Anti-personnel landmines are explosive devices designed to be detonated by the presence, proximity, or contact of a person.
string
antisemitism
Percent of fund holdings that fail company screen: Whether company has been reported to be involved in antisemitic or anti-Israel activities. Based on publicly-available information.
string
anti_social_publishing
Percent of fund holdings that fail company screen: Whether company generates revenue from anti-social publishing (including anti-social internet publishing).
string
arctic_drilling
Percent of fund holdings that fail company screen: Whether company is involved in arctic drilling for oil or gas. Does not include service companies or equipment manufacturers.
string
banned_chemicals
Percent of fund holdings that fail company screen: Whether company is involved in producing or selling hazardous chemicals or pesticides. "Hazardous chemicals or pesticides" means any substance mentioned by the European Chemicals Agency within the Prior Informed Consent Regulation or any unregulated hazardous chemicals, non-biological pesticides and hazardous wastes, or ozone-depleting substances as covered by the Montreal Protocol on Substances that Deplete the Ozone Layer (1989) or any similar international treaties (such as polychlorinated biphenyl, dichlorodiphenyltrichloroethane, chlorofluorocarbons, halons and asbestos).
string
banned_pharmaceuticals
Percent of fund holdings that fail company screen: Whether company has been reported to be involved in production or trade in controlled substances or pharmaceuticals subject to international ban.
string
biological_chemical_weapons
Percent of fund holdings that fail company screen: Whether company has been reported to be involved in producing or selling biological or chemical weapons. Biological and toxin weapons are either microorganisms like virus, bacteria or fungi, or toxic substances produced by living organisms that are produced and released deliberately to cause disease and death in humans, animals or plants. Chemical weapons are chemicals used to cause intentional death or harm through their toxic properties.
string
cannabis
Percent of fund holdings that fail company screen: Whether company is involved in the cannabis industry as part of its business model.
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
carbon_underground
Percent of fund holdings that fail company screen: Whether company fails the Carbon Underground 200 (CU200) screen. The CU200 identifies the top 200 global publicly-listed coal, oil, and gas reserves owners ranked by the carbon emissions embedded in their reserves.
string
cu_coal
Percent of fund holdings that fail company screen: Whether company fails the Carbon Underground 200 (CU200) coal screen. The coal screen identifies the top global publicly-listed coal reserves owners ranked by the carbon emissions embedded in their reserves.
string
cu_oil_gas
Percent of fund holdings that fail company screen: Whether company fails the Carbon Underground 200 (CU200) oil and gas screen. The oil and gas screen identifies the top global publicly-listed oil and gas reserves owners ranked by the carbon emissions embedded in their reserves.
string
cu_tar_sands
Percent of fund holdings that fail company screen: Whether company fails the Carbon Underground 200 (CU200) tar sands screen. The tar sand screen identifies the top global publicly-listed tar sand reserves owners ranked by the carbon emissions embedded in their reserves.
string
cu_thermal_coal
Percent of fund holdings that fail company screen: Whether company fails the Carbon Underground 200 (CU200) thermal coal screen. The thermal coal screen identifies the top global publicly-listed thermal coal reserves owners ranked by the carbon emissions embedded in their reserves.
string
child_safety
Percent of fund holdings that fail company screen: Whether company has been involved in controversies related to child safety, including areas such as child labor, child exploitation, human trafficking, stolen identity, deep fakes, or other abuse of children. Based on ongoing monitoring of news stories and public information.
string
cluster_munitions
Percent of fund holdings that fail company screen: Whether company generates revenue from the sale of cluster munitions. Cluster munitions are munitions designed to disperse or release explosive submunitions or bomblets. Cluster munitions pose a threat to civilians during conflict by randomly scattering submunitions over a wide area. They pose a threat post-conflict by leaving submunitions that fail to explode upon impact and become de facto landmines. The 2008 Convention on Cluster Munitions prohibits the use, production, transfer, and stockpiling of cluster munitions.
string
coal
Percent of fund holdings that fail company screen: Whether company's primary business model involves coal mining, including thermal or metallurgical (coking).
string
conflict_minerals
Percent of fund holdings that fail company screen: Whether company generates revenue from the extraction or trading of minerals, coal and uranium from conflict areas.
string
contraceptives
Percent of fund holdings that fail company screen: Whether company manufactures contraceptives or derives significant revenue from selling contraceptives.
string
controversial_weapons
Percent of fund holdings that fail company screen: Whether company generates significant revenue from the sale of controversial weapons. Controversial weapons include weapons of mass destruction (chemical, biological and nuclear weapons), cluster munitions, antipersonnel mines, incendiary weapons, and other weapons considered to be excessively injurious, to have indiscriminate effects, or to damage the natural environment.
string
deforestation_financing
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_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
depleted_uranium
Percent of fund holdings that fail company screen: Whether company has been reported to be involved in producing or selling depleted uranium. Depleted uranium is a dense metal produced as a by-product of enrichment of natural uranium for nuclear fuel. It is still radioactive, but at a much lower level than the starting material. It is used in armour-piercing shells and bombs, to give them more penetrating power.
string
discrimination_cont
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
electrical_utility
Percent of fund holdings that fail company screen: Whether company derives revenue from electrical utility activities.
string
endangered_wildlife
Percent of fund holdings that fail company screen: Whether company derives revenue from trade in endangered wildlife; any species described as "endangered" or "critically endangered" in the most recent publication of the International Union for Conservation of Nature (IUCN) Red List; or any species subject to protection under the Convention on International Trade in Endangered Species of Wild Fauna and Flora (1973).
string
environmental_cont
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
eu_sanctions
Percent of fund holdings that fail company screen: Whether company is included in the European Union (EU) sanctions list. The EU uses restrictive measures, or sanctions, to promote the objectives of the Common Foreign and Security Policy (CFSP). These include safe-guarding the EU's values, its fundamental interests and security; consolidating and supporting democracy, the rule of law, human rights and the principles of international law; preserving peace; preventing conflicts and strengthening international security. This screen includes only companies specifically listed by the EU.
string
factory_farming
Percent of fund holdings that fail company screen: Whether company has been reported to use factory farming in its supply chain.
string
fast_food
Percent of fund holdings that fail company screen: Whether company is involved in the fast-food industry, and derives at least 10% of its revenue from fast food.
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
food_commodity_derivatives
Percent of fund holdings that fail company screen: Whether company is involved in food commodity derivatives trading or speculative transactions that may contribute to price inflation in basic agricultural or marine commodities (e.g., wheat, rice, meat, soy, sugar, dairy, fish, corn).
string
for_profit_health
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
fur
Percent of fund holdings that fail company screen: Whether company produces or sells fur as a part of its business model.
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
genetic_engineering
Percent of fund holdings that fail company screen: Whether company uses genetic engineering in its product development or other research.
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
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
illegal_activities
Percent of fund holdings that fail company screen: Whether company has products or activities that are deemed illegal under international law or local law where it is headquartered (including recreational cannabis).
string
ilo
Percent of fund holdings that fail company screen: Whether company has been involved in a "severe" or "very severe" controversy related to violations of the International Labor Organization (ILO) Conventions. Conventions cover areas such as basic human rights, minimum wages, industrial relations, employment policy, social dialogue, social security and other issues.
string
interest_based
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_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
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
land_use_biodiversity
Percent of fund holdings that fail company screen: Whether company has faced "high" or "severe" controversies related to land use or biodiversity. Also includes companies that work with soy, cattle or timber and have been reported to have a significant negative impact on deforestation.
string
military_contracting
Percent of fund holdings that fail company screen: Whether company generates revenue from military contracts related to weapons or combat operations.
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
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
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
non_sustainable_palm_oil
Percent of fund holdings that fail company screen: Whether company is involved in non-sustainable palm-oil production or distribution. Defined as a) not having achieved or committed to achieve Roundtable on Sustainable Palm Oil (RSPO) certification or other internationally-recognized sustainable palm oil certifications, and b) any of the following: involvement in unresolved land rights conflicts, inability to prove the legality of operations, no undertaking of social and environmental impact assessments, not consulting with stakeholders prior to commencing operations, or involvement in illegal logging.
string
norges_bank
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
oecd
Percent of fund holdings that fail company screen: Whether company has been involved in a "severe" or "very severe" controversy related to violations of the Organization for Economic Cooperation and Development (OECD) Guidelines for Multinational Enterprises. The guidelines are "non-binding principles and standards for responsible business conduct in a global context consistent with applicable laws and internationally recognised standards."
string
oil_and_gas
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
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
palestinian_human_rights
Percent of fund holdings that fail company screen: Whether company has been reported to be involved in human rights violations against the Palestinian people. Based on publicly-available information.
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
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
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
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
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
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
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
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
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
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
tar_sands
Percent of fund holdings that fail company screen: Whether company is involved in the extraction of tar sands, sometimes called oil sands.
string
thermal_coal
Percent of fund holdings that fail company screen: Whether company's primary business model involves thermal coal mining.
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_gics
Percent of fund holdings that fail company screen: Whether is classified under the GICS Sub-Industry of Tobacco. GICS defines this Sub-Industry as "Manufacturers of cigarettes and other tobacco products such as e-cigarettes. This Sub-Industry excludes companies primarily engaged in producing cannabis related products."
string
uk_sanctions
Percent of fund holdings that fail company screen: Whether company is included in the United Kingdom's sanctions list (companies designated or specified under regulations made under the Sanctions and Anti-Money Laundering Act 2018). This screen includes only companies specifically listed by the UK.
string
undermining_us_elections
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
ungc
Percent of fund holdings that fail company screen: Whether company has been involved in a "severe" or "very severe" controversy related to violations of the United Nations Global Compact principles. Principles cover areas such as human rights, freedom from forced labor and discrimination, anti-corruption, and environmental protection.
string
ungp
Percent of fund holdings that fail company screen: Whether company has been involved in a "severe" or "very severe" controversy related to violations of the United Nations Guiding Principles (UNGP) on Business and Human Rights. The UNGP's foundational principle for businesses is that they should respect human rights, meaning "they should avoid infringing on the human rights of others and should address adverse human rights impacts with which they are involved."
string
us_ofac
Percent of fund holdings that fail company screen: Whether company is included in sanctions lists from the United States Office of Foreign Assets Control (OFAC), including the list of Specially Designated Nationals (SDNs) and non-SDN lists, or the Bureau of Industry and Security Entity List. This screen includes only companies specifically listed by the US.
string
weapons
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
offset_funds
Number of funds offset in the request
integer
paged_funds
Number of paged funds returned
integer
total_funds
Number of total funds available based on the request
integer
max_id
Maximum id for all funds matching your request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "funds" : [
  3. {
  4. "fund_id" : 553,
  5. "symbol" : "VEGN",
  6. "cusip" : "26922A 297",
  7. "isin" : "US26922A2978",
  8. "open_figi" : "BBG00Q6L3CX3",
  9. "name" : "US Vegan Climate ETF",
  10. "updated_at" : "2022-06-19",
  11. "price" : "200.5",
  12. "classifications" : {
  13. "fund_type" : "ETF",
  14. "asset_class" : "Equities",
  15. "category" : "Equity - US Large Blend",
  16. "style" : "Large Blend",
  17. "fund_family" : "Beyond Advisors IC",
  18. },
  19. "logos" : {
  20. "original" : "https://d1bgieexblpmvb.cloudfront.net/funds/logos/beyond_investing.png",
  21. "square" : "https://d1bgieexblpmvb.cloudfront.net/funds/logos/200x200/beyond_investing.png"
  22. },
  23. "financial" : {
  24. "expense_ratio" : "0.006",
  25. "aum" : "73111284"
  26. },
  27. "performance" : {
  28. "return_one_week" : "1.049524",
  29. "return_one_month" : "-0.110756",
  30. "return_three_months" : "7.283246",
  31. "return_one_year" : "18.069027",
  32. "return_two_years" : "-1.680218",
  33. "return_three_years" : "10.446368",
  34. "return_five_years" : "null"
  35. },
  36. "screens" : {
  37. "abortion" : "2.23%",
  38. "advertising" : "0.74%",
  39. "alcohol" : "0%",
  40. "animal_testing" : "0%",
  41. "cannabis" : "0%",
  42. "carbon_emissions_intensity" : "5.58%",
  43. "coal" : "0%",
  44. "contraceptives" : "0.74%",
  45. "deforestation_financing" : "0.74%",
  46. "deforestation_supply_chain" : "2.23%",
  47. "discrimination_cont" : "12.64%",
  48. "environmental_cont" : "15.61%",
  49. "factory_farming" : "0%",
  50. "fast_food" : "0%",
  51. "fossil_fuel" : "0%",
  52. "fur" : "0%",
  53. "gambling" : "0%",
  54. "genetic_engineering" : "0%",
  55. "health_cont" : "6.32%"
  56. "human_trafficking" : "2.23%",
  57. "interest_based" : "21.93%",
  58. "interest_bearing_debt" : "13.75%",
  59. "interest_bearing_securities" : "8.18%",
  60. "misleading_communication" : "10.04%",
  61. "music" : "0.37%",
  62. "no_sbti" : "72.49%",
  63. "nuclear" : "0%",
  64. "oil_and_gas" : "0%",
  65. "opioid_cont" : "0.37%",
  66. "oppressive_cont" : "3.72%",
  67. "pork" : "0%",
  68. "pornography" : "0%",
  69. "predatory_lending" : "1.12%",
  70. "prison_involvement" : "3.35%",
  71. "privacy_cont" : "5.95%",
  72. "single_use_plastic" : "0.37%",
  73. "stem_cell" : "0%",
  74. "sugar" : "0.37%",
  75. "tobacco" : "0%",
  76. "weapons" : "0%"
  77. }
  78. }
  79. ],
  80. "offset_funds" : 0 ,
  81. "paged_funds" : 1 ,
  82. "total_funds" : 1 ,
  83. "max_id" : 100
  84. "request_id" : "28HyTu"
  85. }

/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
ids
A list of fund ids to retrieve data for
[integer]
symbols
A list of fund symbols (tickers) to retrieve fund data for
[string]
cusips
A list of cusip numbers to retrieve fund data for
[string]
isins
A list of ISIN numbers to retrieve fund data for
[string]
asset_classes
A list of asset classes to filter fund data. Options include Alternatives, Diversified, Cash, Equities, Fixed income, Infrastructure, and Property
[string]
domiciles
A list of domiciles to filter fund data. Current options include Australia, Europe, and United States
[string]
fund_types
A list of fund types to filter fund data. Options include ETF, Index, Mutual Fund, and SMA
[string]
categories
A list of fund categories to filter fund data
[string]
fund_families
A list of fund families to filter fund data
[string]
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string
count
The number of funds to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer
offset
The number of funds to skip. The default value is 0.
Default: 0
Minimum: 0
integer

Example request

/funds/get
Curl 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
open_figi
Unique OpenFigi identifier, if available
string
name
Name of the fund
string
updated_at
Date the fund record was last updated in Ethos ESG's database
string
price
Share price of the associated security (delayed 15-minutes)
string
screens
A set of fields describing percent of fund holdings that fail ESG-related screens, as well as percent of revenue derived by held companies from screened activities
object
advertising
Percent of fund holdings that fail company screen: Whether company is involved in advertising as part of its core business model. This typically includes companies with greater than 10% of revenue from advertising.
object
alcohol
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_marketing
Percent of fund holdings that fail company screen: Whether company generates significant revenue from the sale of alcohol (generally more than 10% of total revenue), and does not have a policy for the responsible marketing of alcohol.
object
animal_treatment
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
anti_personnel_mines
Percent of fund holdings that fail company screen: Whether company generates revenue from the sale of anti-personnel mines. Anti-personnel landmines are explosive devices designed to be detonated by the presence, proximity, or contact of a person.
object
antisemitism
Percent of fund holdings that fail company screen: Whether company has been reported to be involved in antisemitic or anti-Israel activities. Based on publicly-available information.
object
anti_social_publishing
Percent of fund holdings that fail company screen: Whether company generates revenue from anti-social publishing (including anti-social internet publishing).
object
arctic_drilling
Percent of fund holdings that fail company screen: Whether company is involved in arctic drilling for oil or gas. Does not include service companies or equipment manufacturers.
object
banned_chemicals
Percent of fund holdings that fail company screen: Whether company is involved in producing or selling hazardous chemicals or pesticides. "Hazardous chemicals or pesticides" means any substance mentioned by the European Chemicals Agency within the Prior Informed Consent Regulation or any unregulated hazardous chemicals, non-biological pesticides and hazardous wastes, or ozone-depleting substances as covered by the Montreal Protocol on Substances that Deplete the Ozone Layer (1989) or any similar international treaties (such as polychlorinated biphenyl, dichlorodiphenyltrichloroethane, chlorofluorocarbons, halons and asbestos).
object
banned_pharmaceuticals
Percent of fund holdings that fail company screen: Whether company has been reported to be involved in production or trade in controlled substances or pharmaceuticals subject to international ban.
object
biological_chemical_weapons
Percent of fund holdings that fail company screen: Whether company has been reported to be involved in producing or selling biological or chemical weapons. Biological and toxin weapons are either microorganisms like virus, bacteria or fungi, or toxic substances produced by living organisms that are produced and released deliberately to cause disease and death in humans, animals or plants. Chemical weapons are chemicals used to cause intentional death or harm through their toxic properties.
object
cannabis
Percent of fund holdings that fail company screen: Whether company is involved in the cannabis industry as part of its business model.
object
carbon_emissions_intensity
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
carbon_underground
Percent of fund holdings that fail company screen: Whether company fails the Carbon Underground 200 (CU200) screen. The CU200 identifies the top 200 global publicly-listed coal, oil, and gas reserves owners ranked by the carbon emissions embedded in their reserves.
object
cu_coal
Percent of fund holdings that fail company screen: Whether company fails the Carbon Underground 200 (CU200) coal screen. The coal screen identifies the top global publicly-listed coal reserves owners ranked by the carbon emissions embedded in their reserves.
object
cu_oil_gas
Percent of fund holdings that fail company screen: Whether company fails the Carbon Underground 200 (CU200) oil and gas screen. The oil and gas screen identifies the top global publicly-listed oil and gas reserves owners ranked by the carbon emissions embedded in their reserves.
object
cu_tar_sands
Percent of fund holdings that fail company screen: Whether company fails the Carbon Underground 200 (CU200) tar sands screen. The tar sand screen identifies the top global publicly-listed tar sand reserves owners ranked by the carbon emissions embedded in their reserves.
object
cu_thermal_coal
Percent of fund holdings that fail company screen: Whether company fails the Carbon Underground 200 (CU200) thermal coal screen. The thermal coal screen identifies the top global publicly-listed thermal coal reserves owners ranked by the carbon emissions embedded in their reserves.
object
child_safety
Percent of fund holdings that fail company screen: Whether company has been involved in controversies related to child safety, including areas such as child labor, child exploitation, human trafficking, stolen identity, deep fakes, or other abuse of children. Based on ongoing monitoring of news stories and public information.
object
cluster_munitions
Percent of fund holdings that fail company screen: Whether company generates revenue from the sale of cluster munitions. Cluster munitions are munitions designed to disperse or release explosive submunitions or bomblets. Cluster munitions pose a threat to civilians during conflict by randomly scattering submunitions over a wide area. They pose a threat post-conflict by leaving submunitions that fail to explode upon impact and become de facto landmines. The 2008 Convention on Cluster Munitions prohibits the use, production, transfer, and stockpiling of cluster munitions.
object
coal
Percent of fund holdings that fail company screen: Whether company's primary business model involves coal mining, including thermal or metallurgical (coking).
object
conflict_minerals
Percent of fund holdings that fail company screen: Whether company generates revenue from the extraction or trading of minerals, coal and uranium from conflict areas.
object
contraceptives
Percent of fund holdings that fail company screen: Whether company manufactures contraceptives or derives significant revenue from selling contraceptives.
object
controversial_weapons
Percent of fund holdings that fail company screen: Whether company generates significant revenue from the sale of controversial weapons. Controversial weapons include weapons of mass destruction (chemical, biological and nuclear weapons), cluster munitions, antipersonnel mines, incendiary weapons, and other weapons considered to be excessively injurious, to have indiscriminate effects, or to damage the natural environment.
object
deforestation_financing
Percent of fund holdings that fail company screen: Whether company is a major financer of deforestation. Defined as providing more than $100M USD to companies involved in deforestation.
object
deforestation_supply_chain
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
depleted_uranium
Percent of fund holdings that fail company screen: Whether company has been reported to be involved in producing or selling depleted uranium. Depleted uranium is a dense metal produced as a by-product of enrichment of natural uranium for nuclear fuel. It is still radioactive, but at a much lower level than the starting material. It is used in armour-piercing shells and bombs, to give them more penetrating power.
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
electrical_utility
Percent of fund holdings that fail company screen: Whether company derives revenue from electrical utility activities.
object
endangered_wildlife
Percent of fund holdings that fail company screen: Whether company derives revenue from trade in endangered wildlife; any species described as "endangered" or "critically endangered" in the most recent publication of the International Union for Conservation of Nature (IUCN) Red List; or any species subject to protection under the Convention on International Trade in Endangered Species of Wild Fauna and Flora (1973).
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
eu_sanctions
Percent of fund holdings that fail company screen: Whether company is included in the European Union (EU) sanctions list. The EU uses restrictive measures, or sanctions, to promote the objectives of the Common Foreign and Security Policy (CFSP). These include safe-guarding the EU's values, its fundamental interests and security; consolidating and supporting democracy, the rule of law, human rights and the principles of international law; preserving peace; preventing conflicts and strengthening international security. This screen includes only companies specifically listed by the EU.
object
factory_farming
Percent of fund holdings that fail company screen: Whether company has been reported to use factory farming in its supply chain.
object
fast_food
Percent of fund holdings that fail company screen: Whether company is involved in the fast-food industry, and derives at least 10% of its revenue from fast food.
object
firearms
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
food_commodity_derivatives
Percent of fund holdings that fail company screen: Whether company is involved in food commodity derivatives trading or speculative transactions that may contribute to price inflation in basic agricultural or marine commodities (e.g., wheat, rice, meat, soy, sugar, dairy, fish, corn).
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
fur
Percent of fund holdings that fail company screen: Whether company produces or sells fur as a part of its business model.
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
genetic_engineering
Percent of fund holdings that fail company screen: Whether company uses genetic engineering in its product development or other research.
object
health_cont
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
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
illegal_activities
Percent of fund holdings that fail company screen: Whether company has products or activities that are deemed illegal under international law or local law where it is headquartered (including recreational cannabis).
object
ilo
Percent of fund holdings that fail company screen: Whether company has been involved in a "severe" or "very severe" controversy related to violations of the International Labor Organization (ILO) Conventions. Conventions cover areas such as basic human rights, minimum wages, industrial relations, employment policy, social dialogue, social security and other issues.
object
interest_based
Percent of fund holdings that fail company screen: Whether company offers an interest-based financial product as part of its business model.
object
interest_bearing_debt
Percent of fund holdings that fail company screen: Whether company's debt-to-market-cap ratio is greater than 30%.
object
interest_bearing_securities
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
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
land_use_biodiversity
Percent of fund holdings that fail company screen: Whether company has faced "high" or "severe" controversies related to land use or biodiversity. Also includes companies that work with soy, cattle or timber and have been reported to have a significant negative impact on deforestation.
object
military_contracting
Percent of fund holdings that fail company screen: Whether company generates revenue from military contracts related to weapons or combat operations.
object
misleading_communication
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
music
Percent of fund holdings that fail company screen: Whether company is involved in producing, distributing or selling music as part of its business model.
object
myanmar
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
non_sustainable_palm_oil
Percent of fund holdings that fail company screen: Whether company is involved in non-sustainable palm-oil production or distribution. Defined as a) not having achieved or committed to achieve Roundtable on Sustainable Palm Oil (RSPO) certification or other internationally-recognized sustainable palm oil certifications, and b) any of the following: involvement in unresolved land rights conflicts, inability to prove the legality of operations, no undertaking of social and environmental impact assessments, not consulting with stakeholders prior to commencing operations, or involvement in illegal logging.
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
oecd
Percent of fund holdings that fail company screen: Whether company has been involved in a "severe" or "very severe" controversy related to violations of the Organization for Economic Cooperation and Development (OECD) Guidelines for Multinational Enterprises. The guidelines are "non-binding principles and standards for responsible business conduct in a global context consistent with applicable laws and internationally recognised standards."
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
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
palestinian_human_rights
Percent of fund holdings that fail company screen: Whether company has been reported to be involved in human rights violations against the Palestinian people. Based on publicly-available information.
object
pharma_cont
Percent of fund holdings that fail company screen: Whether company has been reported to be involved in pharmaceutical-related controversies such as price-gouging or the opioid crisis.
object
pork
Percent of fund holdings that fail company screen: Whether company produces or sells pork as part of its business model.
object
pornography
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
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
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
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
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
single_use_plastic
Percent of fund holdings that fail company screen: Whether company produces or sells single-use plastic items as part of its business model.
object
stem_cell
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
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
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
tar_sands
Percent of fund holdings that fail company screen: Whether company is involved in the extraction of tar sands, sometimes called oil sands.
object
thermal_coal
Percent of fund holdings that fail company screen: Whether company's primary business model involves thermal coal mining.
object
tobacco
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_gics
Percent of fund holdings that fail company screen: Whether is classified under the GICS Sub-Industry of Tobacco. GICS defines this Sub-Industry as "Manufacturers of cigarettes and other tobacco products such as e-cigarettes. This Sub-Industry excludes companies primarily engaged in producing cannabis related products."
object
uk_sanctions
Percent of fund holdings that fail company screen: Whether company is included in the United Kingdom's sanctions list (companies designated or specified under regulations made under the Sanctions and Anti-Money Laundering Act 2018). This screen includes only companies specifically listed by the UK.
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
ungc
Percent of fund holdings that fail company screen: Whether company has been involved in a "severe" or "very severe" controversy related to violations of the United Nations Global Compact principles. Principles cover areas such as human rights, freedom from forced labor and discrimination, anti-corruption, and environmental protection.
object
ungp
Percent of fund holdings that fail company screen: Whether company has been involved in a "severe" or "very severe" controversy related to violations of the United Nations Guiding Principles (UNGP) on Business and Human Rights. The UNGP's foundational principle for businesses is that they should respect human rights, meaning "they should avoid infringing on the human rights of others and should address adverse human rights impacts with which they are involved."
object
us_ofac
Percent of fund holdings that fail company screen: Whether company is included in sanctions lists from the United States Office of Foreign Assets Control (OFAC), including the list of Specially Designated Nationals (SDNs) and non-SDN lists, or the Bureau of Industry and Security Entity List. This screen includes only companies specifically listed by the US.
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
offset_funds
Number of funds offset in the request
integer
paged_funds
Number of paged funds returned
integer
total_funds
Number of total funds available based on the request
integer
max_id
Maximum id for all funds matching your request
integer
request_id
Unique id for the request
string

Example response

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

/funds/ratings/get

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

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

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
ids
A list of fund ids to retrieve data for
[integer]
symbols
A list of fund symbols (tickers) to retrieve fund data for
[string]
cusips
A list of cusip numbers to retrieve fund data for
[string]
isins
A list of ISIN numbers to retrieve fund data for
[string]
cause_ids
A list of cause_ids to retrieve fund data for. If not specified, ratings for all causes for requested funds will be returned
[integer]
asset_classes
A list of asset classes to filter fund data. Options include Alternatives, Diversified, Cash, Equities, Fixed income, Infrastructure, and Property
[string]
domiciles
A list of domiciles to filter fund data. Current options include Australia, Europe, and United States
[string]
fund_types
A list of fund types to filter fund data. Options include ETF, Index, Mutual Fund, and SMA
[string]
categories
A list of fund categories to filter fund data
[string]
fund_families
A list of fund families to filter fund data
[string]
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string
count
The number of funds to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer
offset
The number of funds to skip. The default value is 0.
Default: 0
Minimum: 0
integer

Example request

/funds/get
Curl 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
open_figi
Unique OpenFigi identifier, if available
string
name
Name of the fund
string
updated_at
Date the fund record was last updated in Ethos ESG's database
string
ratings
A set of fields describing ESG ratings associated with the fund
object
cause
Name of the cause or "Impact Persona" for which the fund is rated. Impact Personas are combinations of causes based on what a client or lead selects in their Impact Assessment.
string
cause_id
Unique id of the cause. Note that this field does not apply to "Impact Personas" (combinations of causes). This field will be a null value for Impact Personas.
integer
client_persona
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
offset_funds
Number of funds offset in the request
integer
paged_funds
Number of paged funds returned
integer
total_funds
Number of total funds available based on the request
integer
max_id
Maximum id for all funds matching your request
integer
request_id
Unique id for the request
string

Example response

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

/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
ids
A list of fund ids to retrieve data for
[integer]
symbols
A list of fund symbols (tickers) to retrieve fund data for
[string]
cusips
A list of cusip numbers to retrieve fund data for
[string]
isins
A list of ISIN numbers to retrieve fund data for
[string]
metric_ids
A list of metric_ids to retrieve fund data for. If not specified, all metrics for requested funds will be returned
[integer]
asset_classes
A list of asset classes to filter fund data. Options include Alternatives, Diversified, Cash, Equities, Fixed income, Infrastructure, and Property
[string]
domiciles
A list of domiciles to filter fund data. Current options include Australia, Europe, and United States
[string]
fund_types
A list of fund types to filter fund data. Options include ETF, Index, Mutual Fund, and SMA
[string]
categories
A list of fund categories to filter fund data
[string]
fund_families
A list of fund families to filter fund data
[string]
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string
count
The number of funds to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer
offset
The number of funds to skip. The default value is 0.
Default: 0
Minimum: 0
integer

Example request

/funds/metrics/get
Curl 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
open_figi
Unique OpenFigi identifier, if available
string
name
Name of the fund
string
updated_at
Date the fund record was last updated in Ethos ESG's database
string
metrics
A set of fields describing ESG metrics associated with the fund
object
name
Name of the metric
string
metric_id
Unique id of the metric
integer
description
Short description of the metric
string
link
Link to metric source, if available
string
uom
Unit of measure of the metric
string
date
Date of the data point
date
esg_category
Primary ESG category of the metric (environment, social or governance)
string
score_base
Base score of the metric, measured according to the unit of measure
integer
normalization_scope
Whether the metric is normalized relative to peers, all funds, or not at all
string
score_normalized
Normalized score of the metric (on a 0-100 scale)
integer
offset_funds
Number of funds offset in the request
integer
paged_funds
Number of paged funds returned
integer
total_funds
Number of total funds available based on the request
integer
max_id
Maximum id for all funds matching your request
integer
request_id
Unique id for the request
string

Example response

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

/funds/list

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

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

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An optional object to be used with the request. If specified, options must not be null.
object
ids
A list of fund ids to retrieve data for
[integer]
symbols
A list of fund symbols (tickers) to retrieve fund data (identifiers) for
[string]
cusips
A list of cusip numbers to retrieve fund data (identifiers) for
[string]
isins
A list of ISIN numbers to retrieve fund data (identifiers) for
[string]
asset_classes
A list of asset classes to filter fund data. Options include Alternatives, Diversified, Cash, Equities, Fixed income, Infrastructure, and Property
[string]
domiciles
A list of domiciles to filter fund data. Current options include Australia, Europe, and United States
[string]
fund_types
A list of fund types to filter fund data. Options include ETF, Index, Mutual Fund, and SMA
[string]
categories
A list of fund categories to filter fund data
[string]
fund_families
A list of fund families to filter fund data
[string]

Example request

/funds/list
Curl 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
open_figi
Unique OpenFigi identifier, if available
string
name
Name of the fund
string
updated_at
Date the fund record was last updated in Ethos ESG's database
string
total_funds
Number of total funds available based on the request
integer
max_id
Maximum id for all funds matching your request
integer
request_id
Unique id for the request
string

Example response

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

Help

Submit requests for coverage additions or customer support
In this section
/help/coverage_requests/get
/help/coverage_requests/create
/help/tickets/get
/help/tickets/create

/help/coverage_requests/get

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An optional object to be used with the request. If specified, options must not be null.
object
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string

Example request

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

Response fields

coverage_requests
An object containing information about your coverage requests.
object
available_count
Number of available coverage requests. You can add more coverage requests in your account on Ethos under Support > Coverage requests or by contacting Ethos.
integer
in_progress_count
Number of coverage requests currently in progress.
integer
in_progress_requests
An array containing information about your in-progress coverage requests.
[object]
name
Name of the requested entity
string
status
Status of the request
string
created_at
Date the request was made
date
updated_at
Date the request was last updated. This generally refers to the date the status was last changed
date
record_type
Whether the request is for a Company or Fund
string
public_status
Whether the request is for a public or private entity
string
symbol
Symbol (ticker) of the requested entity, if available
string
isin
ISIN of the requested entity, if available
string
cusip
Cusip of the requested entity, if available
string
open_figi
OpenFigi of the requested entity, if available
string
lxid
LoanX ID of the requested entity, if available
string
completed_count
Number of coverage requests completed.
integer
completed_requests
An array containing information about your completed coverage requests.
[object]
name
Name of the requested entity
string
status
Status of the request
string
created_at
Date the request was made
date
updated_at
Date the request was last updated. This generally refers to the date the status was last changed
date
record_type
Whether the request is for a Company or Fund
string
public_status
Whether the request is for a public or private entity
string
symbol
Symbol (ticker) of the requested entity, if available
string
isin
ISIN of the requested entity, if available
string
cusip
Cusip of the requested entity, if available
string
open_figi
OpenFigi of the requested entity, if available
string
lxid
LoanX ID of the requested entity, if available
string
max_id
Maximum id for all of your coverage requests.
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "coverage_requests" : {
  3. "available_count" : 18,
  4. "in_progress_count" : 4,
  5. "in_progress_requests" : [{
  6. "name" : Apple,
  7. "status" : "In Progress",
  8. "created_at" : "October 1, 2023",
  9. "updated_at" : "October 2, 2023",
  10. "record_type" : "Company",
  11. "public_status" : "Public",
  12. "symbol" : "AAPL",
  13. "isin" : "US0378331005",
  14. "cusip" : "037833100",
  15. "open_figi" : "BBG000B9XRY4",
  16. "lxid" : ""
  17. }],
  18. "completed_count" : 24,
  19. "completed_requests" : [{
  20. "name" : Apple,
  21. "status" : "In Progress",
  22. "created_at" : "October 1, 2023",
  23. "updated_at" : "October 2, 2023",
  24. "record_type" : "Company",
  25. "public_status" : "Public",
  26. "symbol" : "AAPL",
  27. "isin" : "US0378331005",
  28. "cusip" : "037833100",
  29. "open_figi" : "BBG000B9XRY4",
  30. "lxid" : ""
  31. }],
  32. },
  33. "max_id" : 100
  34. "request_id" : "28HyTu"
  35. }

/help/coverage_requests/create

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

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

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

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
coverage_requests
An array of objects to be used with the request. Include information for any coverage request you want to create.
[object]
record_type
Optionally specify if the request is for a Company or Fund. Defaults to Company.
string
public_status
Optionally specify if the requested entity is public or private.
string
name
Optional identifier of holding. Note you must pass at least one identifier for each holding.
string
symbol
Optional identifier of holding. Note you must pass at least one identifier for each holding.
string
isin
Optional identifier of holding. Note you must pass at least one identifier for each holding.
string
cusip
Optional identifier of holding. Note you must pass at least one identifier for each holding.
string
open_figi
Optional identifier of holding. Note you must pass at least one identifier for each holding.
string
lxid
Optional identifier of holding. Note you must pass at least one identifier for each holding.
string

Example request

/help/coverage_requests/create
Curl Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/help/coverage_requests/create \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "coverage_requests": [{
  7. "symbol": String,
  8. "name": String,
  9. "isin": String,
  10. ]}
  11. }'
  1. const response = await client
  2. . createCoverageRequests (firm_id, secret , [{
  3. symbol: String ,
  4. name: String ,
  5. isin: String ,
  6. }])
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const created_coverage_requests = response.created_coverage_requests
  1. response = client.CoverageRequests.create(firm_id, secret, [{
  2. symbol: String
  3. name: String
  4. isin: String
  5. }])
  1. response = @client .coverage_requests. create ( @firm_id , @secret , [{symbol: String, name: String, isin: String}] )

Response fields

created_coverage_requests
An array containing information about successfully-created coverage requests.
[object]
status
Status of the API request (200 or 400)
integer
message
Message of the API request
string
name
Name of the requested entity
string
record_type
Whether the request is for a Company or Fund
string
public_status
Whether the request is for a public or private entity
string
symbol
Symbol (ticker) of the requested entity, if available
string
isin
ISIN of the requested entity, if available
string
cusip
Cusip of the requested entity, if available
string
open_figi
OpenFigi of the requested entity, if available
string
lxid
LoanX ID of the requested entity, if available
string
errors
An array containing information about coverage requests that did not succeed.
[object]
status
Status of the API request
integer
error_message
Error message of the API request
string
error_code
Error code of the API request
string
coverage_requests_summary
An object containing summary information about all of your coverage requests.
object
available_count
Total number of coverage requests available.
integer
in_progress_count
Total number of coverage requests in progress.
integer
completed_count
Total number of coverage requests completed.
integer
max_id
Maximum id for all of your coverage requests.
integer
request_id
Unique id for the request.
string

Example response

API Object
  1. {
  2. "created_coverage_requests" : [{
  3. "status" : 200,
  4. "message" : Successfully created or updated coverage request,
  5. "name" : Apple,
  6. "record_type" : "Company",
  7. "public_status" : "Public",
  8. "symbol" : "AAPL",
  9. "isin" : "US0378331005",
  10. "cusip" : "037833100",
  11. "open_figi" : "BBG000B9XRY4",
  12. "lxid" : ""
  13. }],
  14. "errors" : []
  15. "coverage_requests_summary" : {
  16. "available_count" : 18,
  17. "in_progress_count" : 3,
  18. "completed_count" : 12
  19. },
  20. "max_id" : 100
  21. "request_id" : "28HyTu"
  22. }

/help/tickets/get

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An optional object to be used with the request. If specified, options must not be null.
object
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string

Example request

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

Response fields

tickets
An object containing information about your support tickets.
object
open_count
Number of currently open tickets.
integer
open_tickets
An array containing information about your open tickets.
[object]
emails
Email addresses associated with the ticket. These are the email addresses that Ethos will use to communicate with about the ticket.
string
cc
CC email addresses associated with the ticket. These are the email addresses that Ethos will cc when communicating about the ticket.
string
status
Status of the ticket.
string
created_at
Date the ticket was created.
date
updated_at
Date the ticket was last updated. This generally refers to the date the status was last changed.
date
message
Message of the ticket.
string
closed_count
Number of tickets closed.
integer
closed_tickets
An array containing information about your closed tickets.
[object]
email
Email address associated with the ticket. This is the email address that Ethos will use to communicate with about the ticket.
string
status
Status of the ticket.
string
created_at
Date the ticket was created.
date
updated_at
Date the ticket was last updated. This generally refers to the date the status was last changed.
date
message
Message of the ticket.
string
max_id
Maximum id for all of your tickets.
integer
request_id
Unique id for the request.
string

Example response

API Object
  1. {
  2. "tickets" : {
  3. "open_count" : 1,
  4. "open_tickets" : [{
  5. "email" : email@example.co,
  6. "message" : "Support request message",
  7. "created_at" : "October 1, 2023",
  8. "updated_at" : "October 2, 2023",
  9. "status" : "Open"
  10. }],
  11. "closed_count" : 4,
  12. "closed_tickets" : [{
  13. "email" : email@example.co,
  14. "message" : "Support request message",
  15. "created_at" : "October 1, 2023",
  16. "updated_at" : "October 2, 2023",
  17. "status" : "Open"
  18. }],
  19. },
  20. "max_id" : 100
  21. "request_id" : "28HyTu"
  22. }

/help/tickets/create

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
tickets
An array of objects to be used with the request. Include information for any tickets you want to create.
[object]
emails
Email addresses that Ethos should use to communicate with about this ticket.
[string]
cc
Optional email addresses that Ethos should cc when communicating about this ticket.
[string]
message
Message describing your support request.
string

Example request

/help/tickets/create
Curl Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/help/tickets/create \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "tickets": [{
  7. "emails": [String],
  8. "cc": [String],
  9. "message": String,
  10. ]}
  11. }'
  1. const response = await client
  2. . createTickets (firm_id, secret , [{
  3. emails: [String] ,
  4. cc: [String] ,
  5. message: String ,
  6. }])
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const created_tickets = response.created_tickets
  1. response = client.Tickets.create(firm_id, secret, [{
  2. emails: [String]
  3. cc: [String]
  4. message: String
  5. }])
  1. response = @client .tickets. create ( @firm_id , @secret , [{emails: [String], cc: [String], message: String}] )

Response fields

created_tickets
An array containing information about successfully-created tickets.
[object]
status
Status of the API request (200 or 400)
integer
message
Message of the API request
string
emails
Emails associated with the ticket.
string
cc
Optional cc emails associated with the ticket.
string
message
Message associated with the ticket.
string
errors
An array containing information about any ticket requests that did not succeed.
[object]
status
Status of the API request.
integer
error_message
Error message of the API request
string
error_code
Error code of the API request.
string
tickets_summary
An object containing summary information about all of your tickets.
object
open_count
Total number of open tickets.
integer
closed_count
Total number of closed tickets.
integer
max_id
Maximum id for all of your tickets.
integer
request_id
Unique id for the request.
string

Example response

API Object
  1. {
  2. "created_tickets" : [{
  3. "status" : 200,
  4. "message" : Successfully created ticket,
  5. "emails" : [email@example.co, email2@example.co],
  6. "cc" : [supportinbox@example.co],
  7. "message" : "Support request message",
  8. "status" : "Open"
  9. }],
  10. "errors" : []
  11. "tickets_summary" : {
  12. "open_count" : 3,
  13. "closed_count" : 12
  14. },
  15. "max_id" : 100
  16. "request_id" : "28HyTu"
  17. }

Metrics

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

/metrics/list

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

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An optional object to be used with the request. If specified, options must not be null.
object
ids
A list of metric ids to retrieve data for
[integer]
count
The number of metrics to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer
offset
The number of metrics to skip. The default value is 0.
Default: 0
Minimum: 0
integer

Example request

/metrics/list
Curl 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
max_id
Maximum id for all metrics matching your 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. "max_id" : 100
  18. "request_id" : "28HyTu"
  19. }

Portfolios

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

/portfolios/get

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

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An optional object to be used with the request. If specified, options must not be null.
object
ids
A list of portfolio ids to retrieve portfolio data for
[integer]
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string
count
The number of portfolios to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer
offset
The number of portfolios to skip. The default value is 0.
Default: 0
Minimum: 0
integer

Example request

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

Response fields

portfolios
An array containing the requested portfolios.
[object]
portfolio_id
Ethos' unique identifier for the portfolio. Like all Ethos identifiers, the portfolio_id is case sensitive
integer
account_number
Optional account number or other ID you would like to use to help identify the portfolio
string
name
Name of the portfolio
string
description
Description of the portfolio
string
value
Value of the portfolio record in Ethos
string
holdings_as_of
As-of date of portfolio holdings
string
created_at
Date the portfolio record was created in Ethos ESG's database
string
updated_at
Date the portfolio record was last updated in Ethos ESG's database
string
offset_portfolios
Number of portfolios offset in the request
integer
paged_portfolios
Number of paged portfolios returned
integer
total_portfolios
Number of total portfolios available based on the request
integer
max_id
Maximum id for all portfolios matching your request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "portfolios" : [
  3. {
  4. "portfolio_id" : 553,
  5. "account_number" : "123456789",
  6. "name" : "Example Portfolio",
  7. "description" : "Europe credit portfolio",
  8. "value" : "120000000",
  9. "holdings_as_of" : "2023-09-30",
  10. "created_at" : "2023-06-19"
  11. "updated_at" : "2023-06-19"
  12. }
  13. ],
  14. "offset_portfolios" : 0 ,
  15. "paged_portfolios" : 1 ,
  16. "total_portfolios" : 1 ,
  17. "max_id" : 100
  18. "request_id" : "28HyTu"
  19. }

/portfolios/update

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
portfolio_id
Optional Ethos ID for a portfolio in your account. Should only be used to update existing portfolios in your account.
integer
name
Name of the portfolio. If passed, Ethos will use to find an existing portfolio or create a new portfolio in your account.
string
account_number
Optional account number or other local ID you would like to use to help identify the portfolio. If passed, Ethos will use to find an existing portfolio or create a new portfolio in your account.
string
description
Optional description for the portfolio.
string
holdings_as_of
Optional date of holdings for the portfolio. Should be passed in the format of YYYY-MM-DD.
string
value
Optional $USD value field for the portfolio (can be any value metric that is useful for you). Defaults to $100,000.
integer
Example request
/portfolios/update
Curl Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/portfolios/update \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "name": String
  7. }'
  1. const response = await client
  2. . updatePortfolio (firm_id, secret, name)
  3. . catch ((err) => {
  4. // handle error
  5. })
  6. const portfolio = response.portfolio
  1. response = client.Portfolios.update(firm_id, secret, name)
  1. response = @client .portfolios. update ( @firm_id , @secret , @name )

Response fields

portfolio
An object containing information about the associated portfolio
object
status
Status of the update attempt
integer
message
Message associated with the update attempt
string
portfolio_id
Ethos' unique identifier for the portfolio. Like all Ethos identifiers, the portfolio_id is case sensitive
integer
account_number
Optional account number or other ID you would like to use to help identify the portfolio
string
name
Name of the portfolio
string
description
Description of the portfolio
string
value
Value of the portfolio record in Ethos
string
holdings_as_of
As-of date of portfolio holdings
string
created_at
Date the portfolio record was created in Ethos ESG's database
string
updated_at
Date the portfolio record was last updated in Ethos ESG's database
string
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "portfolio" : {
  3. "status" : 200,
  4. "message" : Successfully added or updated the portfolio,
  5. "portfolio_id" : 553,
  6. "account_number" : "123456789",
  7. "name" : "Example Portfolio",
  8. "description" : "Europe credit portfolio",
  9. "value" : "120000000",
  10. "holdings_as_of" : "2023-09-30",
  11. "created_at" : "2023-06-19"
  12. "updated_at" : "2023-06-19"
  13. },
  14. "max_id" : 100
  15. "request_id" : "28HyTu"
  16. }

/portfolios/holdings/get

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

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An object to be used with the request.
object
ids
A list of portfolio ids to retrieve portfolio holdings for
[integer]
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string
portfolios_count
The number of portfolios to fetch. Optional.
Default: 10
Maximum: 10
integer
portfolios_offset
The number of portfolios to skip. Optional.
Default: 0
integer
holdings_count
The number of holdings to fetch in each returned portfolio. Optional.
Default: all
integer
holdings_offset
The number of holdings to skip in each returned portfolio. Optional.
Default: 0
integer

Example request

/portfolios/holdings/get
Curl Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/portfolios/holdings/get \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "portfolio_ids": [Integer],
  8. }
  9. }'
  1. const response = await client
  2. . getPortfolioHoldings (firm_id, secret , {
  3. portfolio_ids: [Integer] ,
  4. })
  5. . catch ((err) => {
  6. // handle error
  7. })
  8. const portfolios = response.portfolios
  1. response = client.PortfolioHoldings.get(firm_id, secret)
  2. portfolios = response['portfolios']
  1. response = @client .portfolio_holdings. get ( @firm_id , @secret )

Response fields

portfolios
An array containing the requested portfolios.
[object]
portfolio_id
Ethos' unique identifier for the portfolio. Like all Ethos identifiers, the portfolio_id is case sensitive
integer
name
Name of the portfolio
string
created_at
Date the portfolio record was created in Ethos ESG's database
string
updated_at
Date the portfolio record was last updated in Ethos ESG's database
string
holdings
A set of fields describing portfolio holdings
array
name
Name of the associated company
string
symbol
Symbol (ticker) of the associated company
string
client_id
Client-specified ID of the holding, if available
string
isin
Unique ISIN number of stock associated with company, if available
string
cusip
Unique CUSIP number of stock associated with company, if available
string
open_figi
Unique OpenFigi identifier, if available
string
holding_type
Type of holding (e.g., Company)
string
weight
Weight of the holding within the portfolio
string
offset_portfolios
Number of portfolios offset in the request
integer
paged_portfolios
Number of paged portfolios returned
integer
total_portfolios
Number of total portfolios available based on the request
integer
max_id
Maximum id for all portfolio holdings matching your request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "portfolios" : [
  3. {
  4. "portfolio_id" : 553,
  5. "name" : "Example Portfolio",
  6. "created_at" : "2023-06-19",
  7. "updated_at" : "2023-06-19",
  8. "holdings" : [
  9. "name" : Example Company,
  10. "symbol" : XYZ,
  11. "client_id" : "12345",
  12. "isin" : "248384ABC",
  13. "cusip" : 428334333,
  14. "open_figi" : "BBG093RKMB42",
  15. "holding_type" : "Company",
  16. "weight" : "0.037"
  17. ]
  18. }
  19. ],
  20. "offset_portfolios" : 0 ,
  21. "paged_portfolios" : 1 ,
  22. "total_portfolios" : 1 ,
  23. "max_id" : 100
  24. "request_id" : "28HyTu"
  25. }

/portfolios/holdings/update

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

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
portfolio_id
Unique Ethos ID for a portfolio in your account. This is required to associate the holding with the correct portfolio.
integer
options
An optional object to be used with the request.
object
reset
Option to reset all portfolio holdings with this request. If true, Ethos will first delete all portfolio holdings and then add all passed holdings below. Defaults to false.
true/false
create_coverage_requests
Option to automatically create coverage requests when needed. If true, Ethos will create a coverage request for the underlying company associated with any passed holding that does not yet exist in Ethos' database, as long as your account has at least 5 available coverage requests (when there are less than 5, please use the coverage request endpoint directly). Defaults to false.
true/false
holdings
An array of objects to be used with the request. Include information for any holdings you want to create or update.
[object]
client_id
Optional identifier of holding. Can be any ID you would like to maintain with the record; client_id gets sent back in the /portfolios/holdings/get endpoint. If client_id is passed, Ethos will prioritize search for a matching client_id. If no existing client_id is found, Ethos will create a new holding record.
[string]
isin
Optional identifier of holding. Note you must pass at least one identifier for each holding.
[string]
cusip
Optional identifier of holding. Note you must pass at least one identifier for each holding.
[string]
open_figi
Optional identifier of holding. Note you must pass at least one identifier for each holding.
[string]
symbol
Optional identifier of holding. Note you must pass at least one identifier for each holding.
[string]
weight
Optional weight of the holding within the portfolio. Should be a value between 0 and 1.
[decimal]
Example request
/portfolios/holdings/update
Curl Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/portfolios/holdings/update \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "portfolio_id": Integer
  7. "holdings": [{
  8. "symbol": String,
  9. "weight": Float,
  10. ]}
  11. }'
  1. const response = await client
  2. . updatePortfolioHoldings (firm_id, secret, portfolio_id , [{
  3. symbol: String ,
  4. weight: Float ,
  5. }])
  6. . catch ((err) => {
  7. // handle error
  8. })
  9. const updated = response.updated
  1. response = client.PortfolioHoldings.update(firm_id, secret, portfolio_id, [{
  2. symbol: String
  3. weight: Float
  4. }])
  1. response = @client .portfolio_holdings. update ( @firm_id , @secret , @portfolio_id , [{symbol: String, weight: Float}] )

Response fields

portfolio
An object containing information about the associated portfolio.
object
portfolio_id
Ethos' unique identifier for the portfolio. Like all Ethos identifiers, the portfolio_id is case sensitive
integer
name
Name of the portfolio
string
total_holdings
Total number of holdings in the portfolio, after the update attempt completed
integer
total_weight
Total weight of holdings in the portfolio, after the update attempt completed
decimal
updated
An array containing successfully-updated holdings
[object]
status
Status of the update attempt
integer
message
Message associated with the update attempt
string
name
Name of the associated company
string
symbol
Symbol (ticker) of the associated company
string
client_id
Client-specified ID of the holding, if available
string
isin
Unique ISIN number of stock associated with company, if available
string
cusip
Unique CUSIP number of stock associated with company, if available
string
open_figi
Unique OpenFigi identifier, if available
string
weight
Weight of the holding within the portfolio
string
errors
An array containing error messages for any holdings that did not successfully update
[object]
status
Status of the update attempt
integer
error_message
Message associated with the update attempt
string
error_code
Error code associated with the update attempt
string
created_coverage_requests
An array containing information about successfully-created coverage requests. Only applicable if option "create_coverage_requests" passed with request.
[object]
status
Status of the request (200 or 400)
integer
message
Message of the request
string
name
Name of the requested entity
string
record_type
Whether the request is for a Company or Fund
string
public_status
Whether the request is for a public or private entity
string
symbol
Symbol (ticker) of the requested entity, if available
string
isin
ISIN of the requested entity, if available
string
cusip
Cusip of the requested entity, if available
string
open_figi
OpenFigi of the requested entity, if available
string
lxid
LoanX ID of the requested entity, if available
string
coverage_requests_summary
An object containing summary information about all of your coverage requests.
object
available_count
Total number of coverage requests available.
integer
in_progress_count
Total number of coverage requests in progress.
integer
completed_count
Total number of coverage requests completed.
integer
max_id
Maximum id for all portfolio holdings matching your request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "portfolio" : {
  3. "portfolio_id" : 553,
  4. "name" : "Example Portfolio",
  5. "total_holdings" : "100",
  6. "total_weight" : "100",
  7. },
  8. "updated" : [{
  9. "status" : 200,
  10. "message" : Successfully added or updated XYZ Company,
  11. "name" : XYZ Company,
  12. "symbol" : XYZ,
  13. "client_id" : "12345",
  14. "isin" : 248384ABC,
  15. "cusip" : 428334333,
  16. "open_figi" : "BBG093RKMB42",
  17. "weight" : "0.037"
  18. }],
  19. "errors" : [{
  20. "status" : 400,
  21. "error_message" : Not able to find a company for passed symbol: XYZA. Verify the company exists or submit a coverage request for it to be added to Ethos.,
  22. "error_code" : ITEM_NOT_FOUND
  23. }],
  24. "created_coverage_requests" : [{
  25. "status" : 200,
  26. "message" : Successfully created or updated coverage request,
  27. "id" : 12345,
  28. "name" : Apple,
  29. "record_type" : Company,
  30. "public_status" : Public,
  31. "symbol" : AAPL,
  32. "isin" : US0378331005,
  33. "cusip" : 037833100,
  34. "open_figi" : BBG000B9XRY4,
  35. "lxid" : "",
  36. }],
  37. "coverage_requests_summary" : {
  38. "available_count" : 18,
  39. "in_progress_count" : 3,
  40. "completed_count" : 12
  41. },
  42. "max_id" : 100
  43. "request_id" : "28HyTu"
  44. }

/portfolios/ratings/get

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

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

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An object to be used with the request.
object
ids
A list of portfolio ids to retrieve portfolio data for
[integer]
cause_ids
A list of cause_ids to retrieve portfolio data for. If not specified, ratings for all causes (topics) for requested portfolios will be returned
[integer]
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string
count
The number of portfolios to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer
offset
The number of portfolios to skip. The default value is 0.
Default: 0
Minimum: 0
integer

Example request

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

Response fields

portfolios
An array containing the requested portfolios.
[object]
portfolio_id
Ethos' unique identifier for the portfolio. Like all Ethos identifiers, the portfolio_id is case sensitive
integer
name
Name of the portfolio
string
updated_at
Date the portfolio record was last updated in Ethos ESG's database
string
ratings
A set of fields describing ESG ratings associated with the portfolio
object
cause
Name of the cause or "Impact Persona" for which the portfolio is rated. Impact Personas are combinations of causes based on what a client or lead selects in their Impact Assessment.
string
cause_id
Unique id of the cause. Note that this field does not apply to "Impact Personas" (combinations of causes). This field will be a null value for Impact Personas.
integer
date
Date of the rating
date
score
Score of the rating, from 0 (worst) to 100 (best)
integer
percentile
Percentile of the rating, compared to all portfolios
integer
offset_portfolios
Number of portfolios offset in the request
integer
paged_portfolios
Number of paged portfolios returned
integer
total_portfolios
Number of total portfolios available based on the request
integer
max_id
Maximum id for all portfolios matching your request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "portfolios" : [
  3. {
  4. "portfolio_id" : 2858,
  5. "name" : "Example Portfolio",
  6. "updated_at" : "2022-06-19",
  7. "ratings" : [
  8. {
  9. "cause" : "Gender equality",
  10. "cause_id" : "37",
  11. "updated_at" : "2022-06-19",
  12. "score" : 88.2,
  13. "percentile" : 0.92
  14. }
  15. ]
  16. }
  17. ],
  18. "offset_portfolios" : 0 ,
  19. "paged_portfolios" : 1 ,
  20. "total_portfolios" : 1 ,
  21. "max_id" : 100
  22. "request_id" : "28HyTu"
  23. }

Questionnaires

Retrieve data on one or more of your Questionnaires
In this section
/questionnaires/get
/questionnaires/responses/get
/questionnaires/questions/get
/questionnaires/answers/get
/questionnaires/approvals/get

/questionnaires/get

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

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An optional object to be used with the request. If specified, options must not be null.
object
ids
A list of questionnaire ids to retrieve data for
[integer]
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string
count
The number of questionnaires to fetch.
Default: 100
Minimum: 1
Maximum: 100
integer
offset
The number of questionnaires to skip. The default value is 0.
Default: 0
Minimum: 0
integer

Example request

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

Response fields

questionnaires
An array containing the requested questionnaires.
[object]
questionnaire_id
Ethos' unique identifier for the questionnaire_id. Like all Ethos identifiers, the questionnaire_id is case sensitive
integer
title
Title of the questionnaire
string
description
Description of the questionnaire
string
updated_at
Date the questionnaire was last updated in Ethos' database
string
responses_count
Number of associated responses with the questionnaire
integer
percent_completed
Percent completion of the questionnaire, across all associated responses
string
offset_questionnaires
Number of questionnaires offset in the request
integer
paged_questionnaires
Number of paged questionnaires returned
integer
total_questionnaires
Number of total questionnaires available based on the request
integer
max_id
Maximum id for all questionnaires matching your request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "questionnaires" : [
  3. {
  4. "questionnaire_id" : 553,
  5. "title" : "XYZ Questionnaire",
  6. "description" : "Description of the questionnaire",
  7. "updated_at" : "2024-09-30",
  8. "responses_count" : "3"
  9. "percent_completed" : "95%"
  10. }
  11. ],
  12. "offset_questionnaires" : 0 ,
  13. "paged_questionnaires" : 1 ,
  14. "total_questionnaires" : 1 ,
  15. "max_id" : 100
  16. "request_id" : "28HyTu"
  17. }

/questionnaires/responses/get

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

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An optional object to be used with the request. If specified, options must not be null.
object
ids
A list of questionnaire response ids to retrieve data for
[integer]
status
Retrieve data for responses with a specific status. Options are "In Progress", "Not Started", "Submitted", or "Approved"
string
symbols
A list of company symbols (tickers) to retrieve company data for
[string]
cusips
A list of cusip numbers to retrieve company data for
[string]
isins
A list of ISIN numbers to retrieve company data for
[string]
uuids
A list of UUID numbers to retrieve company data for
[string]
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string
count
The number of responses to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer
offset
The number of responses to skip. The default value is 0.
Default: 0
Minimum: 0
integer

Example request

/questionnaires/responses/get
Curl Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/questionnaires/responses/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. . getQuestionnaireResponses (firm_id, secret , {
  3. symbols: [String] ,
  4. count: 100 ,
  5. offset: 0 ,
  6. })
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const responses = response.responses
  1. response = client.Responses.get(firm_id, secret)
  2. responses = response['responses']
  4. # Manipulate the count and offset parameters to paginate
  5. # responses and retrieve all available data
  6. while len (responses) < response[' total_responses' ]:
  7. response = client.Responses.get(firm_id, secret,
  8. offset= len (responses))
  9. responses.extend(response[ 'responses' ])
  1. response = @client .responses. get ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # responses and retrieve all available data
  4. response = @client .responses. get ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_responses = response[ 'responses' ]

Response fields

responses
An array containing the requested responses.
[object]
response_id
Ethos' unique identifier for the response_id. Like all Ethos identifiers, the response_id is case sensitive
integer
questionnaire_id
Ethos' unique identifier for the questionnaire associated with the response
integer
questionnaire_title
Title of the associated questionnaire
string
company_id
Ethos' unique identifier for the company associated with the response
integer
company_name
Name of the associated company
string
updated_at
Date the response was last updated in Ethos' database
string
status
Status of the response. Can be one of In Progress, Not Started, Submitted, or Approved
string
overdue
Whether or not the response is overdue on its approval deadline
boolean
percent_completed
Percent completion of the response
string
responsible_user
Name of the person assigned to complete the response
string
primary_approver
Name of the person assigned as primary approver for the response
string
secondary_approver
Name of the person assigned as secondary approver for the response
string
submission_deadline
Deadline for the response to be submitted
string
approval_deadline
Deadline for the response to be approved
string
submitted_at
Date the response was submitted
string
approved_at
Date the response was approved
string
offset_responses
Number of responses offset in the request
integer
paged_responses
Number of paged responses returned
integer
total_responses
Number of total responses available based on the request
integer
max_id
Maximum id for all responses matching your request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "responses" : [
  3. {
  4. "response_id" : 1234,
  5. "questionnaire_id" : 13223,
  6. "questionnaire_title" : "Example Questionnaire",
  7. "company_id" : 74,
  8. "company_name" : "Apple",
  9. "updated_at" : "2024-09-30",
  10. "status" : "In Progress"
  11. "overdue" : false,
  12. "percent_completed" : "100%"
  13. "responsible_user" : "John Smith"
  14. "primary_approver" : "Sarah Jackson"
  15. "secondary_approver" : null
  16. "submission_deadline" : "2024-10-05",
  17. "approval_deadline" : "2024-10-10",
  18. "submitted_at" : "2024-09-30",
  19. "approved_at" : "2024-10-02",
  20. }
  21. ],
  22. "offset_responses" : 0 ,
  23. "paged_responses" : 1 ,
  24. "total_responses" : 1 ,
  25. "max_id" : 100
  26. "request_id" : "28HyTu"
  27. }

/questionnaires/questions/get

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

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An optional object to be used with the request. If specified, options must not be null.
object
ids
A list of question ids to retrieve data for
[integer]
query
A query term to search questions
string
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string
count
The number of questions to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer
offset
The number of questions to skip. The default value is 0.
Default: 0
Minimum: 0
integer

Example request

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

Response fields

questions
An array containing the requested questions.
[object]
question_id
Ethos' unique identifier for the question_id. Like all Ethos identifiers, the question_id is case sensitive
integer
metric_id
Ethos' unique identifier for a metric associated with the question. Note that not all questions have associated metrics
integer
updated_at
Date the question was last updated in Ethos' database
string
question_text
Text of the question
string
instructions
Instructions for the question
string
question_type
Type of question, such as text or dropdown
string
offset_questions
Number of questions offset in the request
integer
paged_questions
Number of paged questions returned
integer
total_questions
Number of total questions available based on the request
integer
max_id
Maximum id for all questions matching your request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "questions" : [
  3. {
  4. "question_id" : 1234,
  5. "metric_id" : 132,
  6. "updated_at" : "2024-09-30",
  7. "question_text" : "What was the company's total Scope 1 emissions last year, in metric tons?",
  8. "instructions" : "Enter the company's total Scope 1 GHG emissions for the last calendar year, in metric tons."
  9. "question_type" : "integer"
  10. }
  11. ],
  12. "offset_questions" : 0 ,
  13. "paged_questions" : 1 ,
  14. "total_questions" : 1 ,
  15. "max_id" : 100
  16. "request_id" : "28HyTu"
  17. }

/questionnaires/answers/get

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

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An optional object to be used with the request. If specified, options must not be null.
object
ids
A list of questionnaire answer ids to retrieve data for
[integer]
question_ids
A list of associated question ids to retrieve data for. Each answer has an associated question
[integer]
response_ids
A list of associated response ids to retrieve data for. Each answer has an associated overall questionnaire response record
[integer]
symbols
A list of company symbols (tickers) to retrieve company data for
[string]
cusips
A list of cusip numbers to retrieve company data for
[string]
isins
A list of ISIN numbers to retrieve company data for
[string]
uuids
A list of UUID numbers to retrieve company data for
[string]
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string
count
The number of answers to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer
offset
The number of answers to skip. The default value is 0.
Default: 0
Minimum: 0
integer

Example request

/questionnaires/answers/get
Curl Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/questionnaires/answers/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. . getQuestionnaireAnswers (firm_id, secret , {
  3. symbols: [String] ,
  4. count: 100 ,
  5. offset: 0 ,
  6. })
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const answers = response.answers
  1. response = client.Answers.get(firm_id, secret)
  2. answers = response['answers']
  4. # Manipulate the count and offset parameters to paginate
  5. # answers and retrieve all available data
  6. while len (answers) < response[' total_answers' ]:
  7. response = client.Answers.get(firm_id, secret,
  8. offset= len (answers))
  9. answers.extend(response[ 'answers' ])
  1. response = @client .answers. get ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # answers and retrieve all available data
  4. response = @client .answers. get ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_answers = response[ 'answers' ]

Response fields

answers
An array containing the requested answers.
[object]
answer_id
Ethos' unique identifier for the answer_id. Like all Ethos identifiers, the answer_id is case sensitive
integer
question_id
Ethos' unique identifier for the question associated with the answer
integer
question_text
Text of the associated question
string
response_id
Ethos' unique identifier for the response associated with the answer
integer
questionnaire_id
Ethos' unique identifier for the questionnaire associated with the answer
integer
company_id
Ethos' unique identifier for the company associated with the response
integer
company_name
Name of the associated company
string
updated_at
Date the response was last updated in Ethos' database
string
updated_by
Name of the person that last updated the response
string
answer_text
Text of the answer
string
answer_commentary
Any commentary provided with the answer
string
answer_documents
An array containing any uploaded or linked supporting documentation
[object]
name
Name of the document
string
file_url
File URL of the document
string
offset_answers
Number of answers offset in the request
integer
paged_answers
Number of paged answers returned
integer
total_answers
Number of total answers available based on the request
integer
max_id
Maximum id for all answers matching your request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "answers" : [
  3. {
  4. "answer_id" : 1234,
  5. "question_id" : 553,
  6. "question_text" : "What was the company's total Scope 1 emissions last year, in metric tons?",
  7. "response_id" : 23392,
  8. "questionnaire_id" : 3212,
  9. "company_id" : 74,
  10. "company_name" : "Apple",
  11. "updated_at" : "2024-09-30",
  12. "updated_by" : "John Smith"
  13. "answer_text" : "10230"
  14. "answer_commentary" : "As reported in the company's sustainability report"
  15. "answer_documents" : [
  16. {
  17. "name" : "Sustainability Report"
  18. "file_url" : "https://xyz.com"
  19. }
  20. ],
  21. }
  22. ],
  23. "offset_answers" : 0 ,
  24. "paged_answers" : 1 ,
  25. "total_answers" : 1 ,
  26. "max_id" : 100
  27. "request_id" : "28HyTu"
  28. }

/questionnaires/approvals/get

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

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An optional object to be used with the request. If specified, options must not be null.
object
ids
A list of approval ids to retrieve data for
[integer]
response_ids
A list of associated response ids to retrieve data for. Each approval has an associated overall questionnaire response record
[integer]
status
Retrieve data for responses with a specific status. Options are "Pending", "Approved", or "Rejected"
string
symbols
A list of company symbols (tickers) to retrieve company data for
[string]
cusips
A list of cusip numbers to retrieve company data for
[string]
isins
A list of ISIN numbers to retrieve company data for
[string]
uuids
A list of UUID numbers to retrieve company data for
[string]
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string
count
The number of approvals to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer
offset
The number of approvals to skip. The default value is 0.
Default: 0
Minimum: 0
integer

Example request

/questionnaires/approvals/get
Curl Node Python Ruby
  1. curl -X POST https://development.ethosesg.com/questionnaires/approvals/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. . getQuestionnaireApprovals (firm_id, secret , {
  3. symbols: [String] ,
  4. count: 100 ,
  5. offset: 0 ,
  6. })
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const approvals = response.approvals
  1. response = client.Approvals.get(firm_id, secret)
  2. approvals = response['approvals']
  4. # Manipulate the count and offset parameters to paginate
  5. # approvals and retrieve all available data
  6. while len (approvals) < response[' total_approvals' ]:
  7. response = client.Approvals.get(firm_id, secret,
  8. offset= len (approvals))
  9. approvals.extend(response[ 'approvals' ])
  1. response = @client .approvals. get ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # approvals and retrieve all available data
  4. response = @client .approvals. get ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_approvals = response[ 'approvals' ]

Response fields

approvals
An array containing the requested approvals.
[object]
approval_id
Ethos' unique identifier for the approval_id. Like all Ethos identifiers, the approval_id is case sensitive
integer
response_id
Ethos' unique identifier for the response_id. Like all Ethos identifiers, the response_id is case sensitive
integer
company_id
Ethos' unique identifier for the company associated with the response
integer
company_name
Name of the associated company
string
created_at
Date the approval was created in Ethos' database
string
updated_at
Date the approval was last updated in Ethos' database
string
deadline
Deadline for the approval to be completed
string
status
Status of the approval. Can be one of Pending, Approved, or Rejected
string
requester
Name of the person making the approval request
integer
request_message
Any messsage sent by the requester with the request
string
approvers
An array containing a list of approvers for the approval request
[object]
name
Name of the approver
string
email
Email of the approver
string
approved_at
Date the approval was approved
string
offset_approvals
Number of approvals offset in the request
integer
paged_approvals
Number of paged approvals returned
integer
total_approvals
Number of total approvals available based on the request
integer
max_id
Maximum id for all approvals matching your request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "approvals" : [
  3. {
  4. "approval_id" : 1234,
  5. "response_id" : 23342,
  6. "company_id" : 74,
  7. "company_name" : "Apple",
  8. "created_at" : "2024-09-25",
  9. "updated_at" : "2024-09-30",
  10. "updated_by" : "John Smith"
  11. "deadline" : "2024-10-02",
  12. "status" : "Pending"
  13. "requester" : "John Smith"
  14. "request_message" : "Please review and approve"
  15. "approvers" : [
  16. {
  17. "name" : "Sarah Jackson"
  18. "email" : "example@email.com"
  19. }
  20. ],
  21. }
  22. ],
  23. "offset_approvals" : 0 ,
  24. "paged_approvals" : 1 ,
  25. "total_approvals" : 1 ,
  26. "max_id" : 100
  27. "request_id" : "28HyTu"
  28. }

Reports

Retrieve data on one or more of your Reports
In this section
/reports/get

/reports/get

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

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

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An optional object to be used with the request. If specified, options must not be null.
object
ids
An optional list of report ids to retrieve report data for
[integer]
symbols
An optional list of symbols (tickers) to retrieve associated reports for
[string]
cusips
An optional list of cusip numbers to retrieve associated reports for
[string]
isins
An optional list of ISIN numbers to retrieve associated reports for
[string]
uuids
An optional list of UUID numbers to retrieve associated reports for
[string]
updated_after
Optionally get only records updated after a specific date. Should be in the format "YYYY-MM-DD"
string
count
The number of reports to fetch.
Default: 100
Minimum: 1
Maximum: 100
integer
offset
The number of reports to skip. The default value is 0.
Default: 0
Minimum: 0
integer

Example request

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

Response fields

reports
An array containing the requested reports.
[object]
report_id
Ethos' unique identifier for the report. Like all Ethos identifiers, the report_id is case sensitive
integer
token
Unique token identifier for the report
string
title
Title of the report
string
subtitle
Subtitle of the report, if present
string
created_at
Date the report record was created in Ethos ESG's database
string
updated_at
Date the report record was last updated in Ethos ESG's database
string
filename
Filename of the report
string
link
Link to download the report PDF. This is a time-sensitive link that will expire 1 week after the API call.
string
record_type
Whether the report is focused on a company, fund or portfolio
string
company_id
Associated company id, if present
string
fund_id
Associated fund id, if present
string
offset_reports
Number of reports offset in the request
integer
paged_reports
Number of paged reports returned
integer
total_reports
Number of total reports available based on the request
integer
max_id
Maximum id for all reports matching your request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "reports" : [
  3. {
  4. "report_id" : 553,
  5. "token" : "123456789",
  6. "title" : "ABC Co Scorecard",
  7. "subtitle" : "Company ESG risk scorecard",
  8. "created_at" : "2023-06-19"
  9. "updated_at" : "2023-06-19"
  10. "filename" : "abc-co-scorecard.pdf",
  11. "link" : ""https://ethos-app.s3.eu-west-3.amazonaws.com/accounts/development/352/reports/company-summary-pdf-1705448130-8YMatc7L7i5br9KvXMqbstn2.pdf",
  12. "record_type" : "company",
  13. "company_id" : 1,
  14. "fund_id" : null
  15. }
  16. ],
  17. "offset_reports" : 0 ,
  18. "paged_reports" : 1 ,
  19. "total_reports" : 1 ,
  20. "max_id" : 100
  21. "request_id" : "28HyTu"
  22. }

Errors

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

Error schema

error_code
The particular error code. Safe for programmatic use.
string
error_message
A representation of the error code. This may change over time and is not safe for programmatic use.
string
request_id
A unique identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
string

Error codes

INCORRECT_KEYS
Incorrect firm_id or secret sent with the request
string
NO_IDENTIFIER
No identifier passed for company or fund
string
ITEM_NOT_FOUND
Requested company, fund, cause or metric could not be found in the Ethos database
string
PORTFOLIO_NOT_FOUND
Requested portfolio could not be found in the Ethos database
string
PORTFOLIO_IMPORTING
Requested portfolio is in the process of importing/updating
string
NO_COVERAGE_REQUESTS_AVAILABLE
No coverage requests available to be used. Reach out to Ethos support for additional requests
string
OFFSET_TOO_HIGH
No records available with requested offset paramater
string
INTERNAL_SERVER_ERROR
Error caused by internal Ethos problem. Please contact us for support
string