Ethos API docs

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/holdings/get

/portfolios/holdings/update

/portfolios/ratings/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

Production: https://production.ethosesg.com

The Development environment is unrestricted and supports up to 100 API calls per week (contact us for additional calls). All testing should be done in the Development environment.

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

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]

include_price

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

[true/false]

count

The number of companies to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

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

Default: 0

Minimum: 0

integer

Example request

/companies/get

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

Response fields

companies

An array containing the requested companies.

[object]

company_id

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

integer

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

classifications

A set of fields describing company classification (sector, industry and peer group)

object

sector

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

string

industry

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

string

peer_group

Peer group of the company. Peer group is the narrowest classification that Ethos uses

string

geography

A set of fields describing company geography

object

region

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

string

hq_country

Country of company headquarters

string

hq_state

State or province of company headquarters, if available

string

hq_city

City of company headquarters, if available

string

financial

A set of fields describing company financial highlights

object

revenue

Trailing twelve-month revenue

integer

market_value

Market capitalization

integer

market_cap

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

string

net_income

Trailing twelve-month net income

integer

price

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

string

earnings_per_share

Earnings per share

string

return_on_assets

Return on assets

string

return_on_equity

Return on equity

string

net_invested_capital

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

string

dividends_per_share

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

string

net_debt

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

string

cash_and_short_term

Cash and equivalents and short term investments in marketable securities

string

performance

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

object

return_one_day

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

string

return_one_week

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

string

return_one_month

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

string

return_three_months

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

string

return_one_year

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

string

return_two_years

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

string

return_three_years

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

string

return_five_years

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

string

executives

A set of fields describing company executives

[object]

name

Executive name

string

title

Executive title

string

is_ceo

Whether or not the executive is CEO of the company

boolean

age

Executive age

integer

pay

Executive compensation for last available year

integer

screens

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

object

advertising

Whether company is involved in advertising as part of its business model.

string

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

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

arctic_drilling

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

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

coal

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

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

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

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

factory_farming

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

string

fast_food

Whether company is considered a fast-food company.

string

firearms

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

string

for_profit_health

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

string

fossil_fuel

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

string

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

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

military_contracting

Whether company generates revenue from military contracts. Includes companies that have contracts with military or national defense departments, regardless of the nature of those contracts.

string

misleading_communication

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

string

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

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

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

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

undermining_us_elections

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

string

weapons

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

string

historical_screens

A set of fields describing whether or not the company failed ESG-related screens in previous years

object

paged_companies

Number of paged companies returned

integer

total_companies

Number of total companies available based on the request

integer

request_id

Unique id for the request

string

Example response

API Object

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

/companies/screens/get

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

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

Request fields

firm_id

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

string

secret

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

string

options

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

object

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

offset

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

Default: 0

Minimum: 0

integer

Example request

/companies/screens/get

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

Response fields

companies

An array containing the requested companies.

[object]

company_id

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

integer

symbol

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

string

cusip

Unique CUSIP number of stock associated with company, if available

string

isin

Unique ISIN number of stock associated with company, if available

string

uuid

Unique UUID field used by ACA Group, if available

string

open_figi

Unique OpenFigi identifier, if available

string

name

Name of the company

string

updated_at

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

string

screens

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

object

advertising

Whether company is involved in advertising as part of its business model.

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

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

arctic_drilling

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

object

cannabis

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

object

carbon_emissions_intensity

object

carbon_underground

object

cu_coal

object

cu_oil_gas

object

cu_tar_sands

object

cu_thermal_coal

object

coal

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

object

contraceptives

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

object

controversial_weapons

object

deforestation_financing

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

object

deforestation_supply_chain

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

object

discrimination_cont

object

environmental_cont

object

factory_farming

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

object

fast_food

Whether company is considered a fast-food company.

object

firearms

object

for_profit_health

object

fossil_fuel

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

object

fur

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

object

gambling

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

object

genetic_engineering

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

object

health_cont

object

human_rights_cont

object

human_trafficking

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

object

interest_based

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

object

interest_bearing_debt

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

object

interest_bearing_securities

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

object

iran

object

military_contracting

Whether company generates revenue from military contracts. Includes companies that have contracts with military or national defense departments, regardless of the nature of those contracts.

object

misleading_communication

object

music

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

object

myanmar

object

norges_bank

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

object

northern_ireland

object

north_korea

object

no_sbti

object

nuclear

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

object

oil_and_gas

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

object

opioid_cont

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

object

oppressive_cont

object

pharma_cont

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

object

pork

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

object

pornography

object

predatory_lending

Whether company has been reported to engage in predatory lending.

object

prison_involvement

object

privacy_cont

object

pro_life

object

russia

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

object

single_use_plastic

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

object

stem_cell

object

sudan

object

sugar

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

object

syria

object

tar_sands

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

object

thermal_coal

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

object

tobacco

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

object

undermining_us_elections

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

object

weapons

object

historical_screens

A set of fields describing whether or not the company failed ESG-related screens in previous years

object

paged_companies

Number of paged companies returned

integer

total_companies

Number of total companies available based on the request

integer

request_id

Unique id for the request

string

Example response

API Object

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

/companies/ratings/get

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

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

Request fields

firm_id

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

string

secret

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

string

options

An object to be used with the request. You must specify at least one company identifier (symbol, CUSIP, ISIN, UUID or portfolio_ids).

object

symbols

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

[string]

cusips

A list of cusip numbers to retrieve company data for

[string]

isins

A list of ISIN numbers to retrieve company data for

[string]

uuids

A list of UUID numbers to retrieve company data for

[string]

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]

count

The number of companies to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

Example request

/companies/ratings/get

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

Response fields

companies

An array containing the requested companies.

[object]

company_id

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

integer

symbol

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

string

cusip

Unique CUSIP number of stock associated with company, if available

string

isin

Unique ISIN number of stock associated with company, if available

string

uuid

Unique UUID field used by ACA Group, if available

string

open_figi

Unique OpenFigi identifier, if available

string

name

Name of the company

string

updated_at

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

string

ratings

A set of fields describing ESG ratings associated with the company

object

cause

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

string

cause_id

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

integer

client_persona

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

boolean

date

Date of the rating

date

score

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

integer

rank

Rank of the rating, compared to all companies

integer

percentile

Percentile of the rating, compared to all companies

integer

paged_companies

Number of paged companies returned

integer

total_companies

Number of total companies available based on the request

integer

request_id

Unique id for the request

string

Example response

API Object

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

/companies/metrics/get

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

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

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

Request fields

firm_id

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

string

secret

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

string

options

An object to be used with the request. You must specify at least one company identifier (symbol, CUSIP, ISIN, UUID or portfolio_ids).

object

symbols

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

[string]

cusips

A list of cusip numbers to retrieve company data for

[string]

isins

A list of ISIN numbers to retrieve company data for

[string]

uuids

A list of UUID numbers to retrieve company data for

[string]

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]

count

The number of companies to fetch.

Default: 10

Minimum: 1

Maximum: 10

integer

Example request

/companies/metrics/get

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

Response fields

companies

An array containing the requested companies.

[object]

company_id

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

integer

symbol

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

string

cusip

Unique CUSIP number of stock associated with company, if available

string

isin

Unique ISIN number of stock associated with company, if available

string

uuid

Unique UUID field used by ACA Group, if available

string

open_figi

Unique OpenFigi identifier, if available

string

name

Name of the company

string

updated_at

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

string

metrics

A set of fields describing ESG metrics associated with the company

object

name

Name of the metric

string

metric_id

Unique id of the metric

integer

description

Short description of the metric

string

link

Link to metric source, if available

string

uom

Unit of measure of the metric

string

date

Date of the data point

string

esg_category

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

string

score_base

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

integer

normalization_scope

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

string

score_normalized

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

integer

peer_value

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

boolean

paged_companies

Number of paged companies returned

integer

total_companies

Number of total companies available based on the request

integer

request_id

Unique id for the request

string

Example response

API Object

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

/companies/list

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

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

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

Request fields

firm_id

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

string

secret

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

string

options

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

object

symbols

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

[string]

cusips

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

[string]

isins

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

[string]

uuids

A list of UUID numbers to retrieve company data for

[string]

portfolio_ids

A list of portfolio IDs to retrieve data for held companies

[integer]

Example request

/companies/list

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

Response fields

companies

An array containing a list of companies with identifiers.

[object]

company_id

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

integer

symbol

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

string

cusip

Unique CUSIP number of stock associated with company, if available

string

isin

Unique ISIN number of stock associated with company, if available

string

uuid

Unique UUID field used by ACA Group, if available

string

open_figi

Unique OpenFigi identifier, if available

string

name

Name of the company

string

updated_at

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

string

total_companies

Number of total companies available based on the request

integer

request_id

Unique id for the request

string

Example response

API Object

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

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

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

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

Request fields

firm_id

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

string

secret

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

string

options

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

object

cause_ids

A list of cause_ids to retrieve metric data for

[integer]

Example request

/causes/list

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

Response fields

causes

An array containing the requested causes.

[object]

cause_id

Ethos' unique identifier for the cause

integer

name

Name of the cause

string

description

Short description of the cause

string

problem

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

string

keywords

Keywords associated with the cause

string

total_causes

Number of total causes available based on the request

integer

request_id

Unique id for the request

string

Example response

API Object

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

Funds

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

In this section

/funds/get

/funds/screens/get

/funds/ratings/get

/funds/metrics/get

/funds/list

/funds/get

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

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

Request fields

firm_id

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

string

secret

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

string

options

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

object

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]

count

The number of funds to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

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

Default: 0

Minimum: 0

integer

Example request

/funds/get

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

Response fields

funds

An array containing the requested funds.

[object]

fund_id

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

integer

symbol

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

string

cusip

Unique CUSIP number of security associated with fund, if available

string

isin

Unique ISIN number of security associated with fund, if available

string

open_figi

Unique OpenFigi identifier, if available

string

name

Name of the fund

string

updated_at

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

string

price

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

string

classifications

A set of fields describing fund classifications

object

fund_type

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

string

asset_class

Asset class of the fund

string

Example response

API Object

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

/funds/screens/get

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

Request fields

firm_id

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

string

secret

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

string

options

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

object

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]

count

The number of funds to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

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

Default: 0

Minimum: 0

integer

Example request

/funds/get

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

Response fields

funds

An array containing the requested funds.

[object]

fund_id

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

integer

symbol

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

string

cusip

Unique CUSIP number of security associated with fund, if available

string

isin

Unique ISIN number of security associated with fund, if available

string

open_figi

Unique OpenFigi identifier, if available

string

name

Name of the fund

string

updated_at

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

string

price

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

string

screens

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

object

advertising

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

object

alcohol

object

animal_treatment

object

anti_abortion

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

object

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

cannabis

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

object

carbon_emissions_intensity

object

carbon_underground

object

cu_coal

object

cu_oil_gas

object

cu_tar_sands

object

cu_thermal_coal

object

coal

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

object

contraceptives

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

object

controversial_weapons

object

deforestation_financing

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

object

deforestation_supply_chain

object

discrimination_cont

object

environmental_cont

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 considered a fast-food company.

object

firearms

object

for_profit_health

object

fossil_fuel

object

fur

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

object

gambling

object

genetic_engineering

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

object

health_cont

object

human_rights_cont

object

human_trafficking

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

object

interest_based

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

object

interest_bearing_debt

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

object

interest_bearing_securities

object

iran

object

military_contracting

object

misleading_communication

object

music

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

object

myanmar

object

norges_bank

object

northern_ireland

object

north_korea

object

no_sbti

object

nuclear

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

object

oil_and_gas

object

opioid_cont

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

object

oppressive_cont

object

pharma_cont

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

object

pork

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

object

pornography

object

predatory_lending

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

object

prison_involvement

object

privacy_cont

object

pro_life

object

russia

object

single_use_plastic

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

object

stem_cell

object

sudan

object

sugar

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

object

syria

object

tar_sands

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

object

thermal_coal

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

object

tobacco

object

undermining_us_elections

object

weapons

object

paged_funds

Number of paged funds returned

integer

total_funds

Number of total funds available based on the request

integer

request_id

Unique id for the request

string

Example response

API Object

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

/funds/ratings/get

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

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

Request fields

firm_id

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

string

secret

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

string

options

An object to be used with the request.

object

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]

count

The number of funds to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

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

Default: 0

Minimum: 0

integer

Example request

/funds/get

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

Response fields

funds

An array containing the requested funds.

[object]

fund_id

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

integer

symbol

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

string

cusip

Unique CUSIP number of security associated with fund, if available

string

isin

Unique ISIN number of security associated with fund, if available

string

open_figi

Unique OpenFigi identifier, if available

string

name

Name of the fund

string

updated_at

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

string

ratings

A set of fields describing ESG ratings associated with the fund

object

cause

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

string

cause_id

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

integer

client_persona

boolean

date

Date of the rating

date

score

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

integer

rank

Rank of the rating, compared to all funds

integer

percentile

Percentile of the rating, compared to all funds

integer

paged_funds

Number of paged funds returned

integer

total_funds

Number of total funds available based on the request

integer

request_id

Unique id for the request

string

Example response

API Object

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

/funds/metrics/get

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

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

Request fields

firm_id

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

string

secret

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

string

options

An object to be used with the request.

object

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]

count

The number of funds to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

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

Default: 0

Minimum: 0

integer

Example request

/funds/metrics/get

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

Response fields

funds

An array containing the requested funds.

[object]

fund_id

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

integer

symbol

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

string

cusip

Unique CUSIP number of security associated with fund, if available

string

isin

Unique ISIN number of security associated with fund, if available

string

open_figi

Unique OpenFigi identifier, if available

string

name

Name of the fund

string

updated_at

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

string

metrics

A set of fields describing ESG metrics associated with the fund

object

name

Name of the metric

string

metric_id

Unique id of the metric

integer

description

Short description of the metric

string

link

Link to metric source, if available

string

uom

Unit of measure of the metric

string

date

Date of the data point

date

esg_category

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

string

score_base

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

integer

normalization_scope

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

string

score_normalized

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

integer

paged_funds

Number of paged funds returned

integer

total_funds

Number of total funds available based on the request

integer

request_id

Unique id for the request

string

Example response

API Object

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

/funds/list

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

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

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

Request fields

firm_id

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

string

secret

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

string

options

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

object

symbols

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

[string]

cusips

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

[string]

isins

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

[string]

asset_classes

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

[string]

domiciles

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

[string]

fund_types

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

[string]

categories

A list of fund categories to filter fund data

[string]

fund_families

A list of fund families to filter fund data

[string]

Example request

/funds/list

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

Response fields

funds

An array containing a list of funds with identifiers.

[object]

fund_id

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

integer

symbol

Unique symbol (ticker) for the fund

string

cusip

Unique CUSIP number associated with fund, if available

string

isin

Unique ISIN number associated with fund, if available

string

open_figi

Unique OpenFigi identifier, if available

string

name

Name of the fund

string

updated_at

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

string

total_funds

Number of total funds available based on the request

integer

request_id

Unique id for the request

string

Example response

API Object

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

Help

Submit requests for coverage additions or customer support

In this section

/help/coverage_requests/get

/help/coverage_requests/create

/help/tickets/get

/help/tickets/create

/help/coverage_requests/get

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

Request fields

firm_id

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

string

secret

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

string

Example request

/help/coverage_requests/get

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

Response fields

coverage_requests

An object containing information about your coverage requests.

object

available_count

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

integer

in_progress_count

Number of coverage requests currently in progress.

integer

in_progress_requests

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

[object]

name

Name of the requested entity

string

status

Status of the request

string

created_at

Date the request was made

date

updated_at

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

date

record_type

Whether the request is for a Company or Fund

string

public_status

Whether the request is for a public or private entity

string

symbol

Symbol (ticker) of the requested entity, if available

string

isin

ISIN of the requested entity, if available

string

cusip

Cusip of the requested entity, if available

string

open_figi

OpenFigi of the requested entity, if available

string

lxid

LoanX ID of the requested entity, if available

string

completed_count

Number of coverage requests completed.

integer

completed_requests

An array containing information about your completed coverage requests.

[object]

name

Name of the requested entity

string

status

Status of the request

string

created_at

Date the request was made

date

updated_at

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

date

record_type

Whether the request is for a Company or Fund

string

public_status

Whether the request is for a public or private entity

string

symbol

Symbol (ticker) of the requested entity, if available

string

isin

ISIN of the requested entity, if available

string

cusip

Cusip of the requested entity, if available

string

open_figi

OpenFigi of the requested entity, if available

string

lxid

LoanX ID of the requested entity, if available

string

request_id

Unique id for the request

string

Example response

API Object

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

/help/coverage_requests/create

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

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

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

Request fields

firm_id

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

string

secret

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

string

coverage_requests

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

[object]

record_type

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

[string]

public_status

Optionally specify if the requested entity is public or private.

[string]

name

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

[string]

symbol

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

[string]

isin

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

[string]

cusip

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

[string]

open_figi

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

[string]

lxid

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

[string]

Example request

/help/coverage_requests/create

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

Response fields

created_coverage_requests

An array containing information about successfully-created coverage requests.

[object]

status

Status of the API request (200 or 400)

integer

message

Message of the API request

string

name

Name of the requested entity

string

record_type

Whether the request is for a Company or Fund

string

public_status

Whether the request is for a public or private entity

string

symbol

Symbol (ticker) of the requested entity, if available

string

isin

ISIN of the requested entity, if available

string

cusip

Cusip of the requested entity, if available

string

open_figi

OpenFigi of the requested entity, if available

string

lxid

LoanX ID of the requested entity, if available

string

errors

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

[object]

status

Status of the API request

integer

error_message

Error message of the API request

string

error_code

Error code of the API request

string

coverage_requests_summary

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

object

available_count

Total number of coverage requests available.

integer

in_progress_count

Total number of coverage requests in progress.

integer

completed_count

Total number of coverage requests completed.

integer

request_id

Unique id for the request

string

Example response

API Object

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

/help/tickets/get

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

Request fields

firm_id

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

string

secret

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

string

Example request

/help/tickets/get

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

Response fields

tickets

An object containing information about your support tickets.

object

open_count

Number of currently open tickets.

integer

open_tickets

An array containing information about your open tickets.

[object]

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

closed_count

Number of tickets closed.

integer

closed_tickets

An array containing information about your closed tickets.

[object]

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

string

status

Status of the ticket

string

created_at

Date the ticket was created

date

updated_at

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

date

message

Message of the ticket

string

request_id

Unique id for the request

string

Example response

API Object

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

/help/tickets/create

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

Request fields

firm_id

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

string

secret

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

string

tickets

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

[object]

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

[string]

message

Message describing your support request.

[string]

Example request

/help/tickets/create

curl -X POST https://development.ethosesg.com/help/tickets/create \
-H 'Content-Type: application/json' \
-d '{
"firm_id": String,
"secret": String,
"tickets": [{
"email": 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

Email 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

request_id

Unique id for the request

string

Example response

API Object

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

Metrics

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

In this section

/metrics/list

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

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

Request fields

firm_id

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

string

secret

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

string

options

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

object

metric_ids

A list of metric_ids to retrieve metric data for

[integer]

count

The number of metrics to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

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

Default: 0

Minimum: 0

integer

Example request

/metrics/list

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

Response fields

metrics

An array containing the requested metrics.

[object]

metric_id

Ethos' unique identifier for the metric

integer

name

Name of the metric

string

description

Short description of the metric

string

source

Name of the metric source

string

link

Link to the metric source

string

uom

Unit of measure of the metric

string

updated_at

Date that metric data was last updated

date

esg_category

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

string

normalization_scope

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

string

paged_metrics

Number of paged metrics returned

integer

total_metrics

Number of total metrics available based on the request

integer

request_id

Unique id for the request

string

Example response

API Object

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

Portfolios

Retrieve and submit data on one or more of your Portfolios

In this section

/portfolios/get

/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

portfolio_ids

A list of portfolio ids to retrieve portfolio data for

[integer]

count

The number of portfolios to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

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

Default: 0

Minimum: 0

integer

Example request

/portfolios/get

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

Response fields

portfolios

An array containing the requested portfolios.

[object]

portfolio_id

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

integer

name

Name of the portfolio

string

updated_at

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

string

paged_portfolios

Number of paged portfolios returned

integer

total_portfolios

Number of total portfolios available based on the request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"portfolios" : [
{
"portfolio_id" : 553,
"name" : "Example Portfolio",
"updated_at" : "2023-06-19"
}
],
"paged_portfolios" : 1 ,
"total_portfolios" : 1 ,
"request_id" : "28HyTu"
}

/portfolios/holdings/get

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

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

Request fields

firm_id

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

string

secret

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

string

options

An object to be used with the request.

object

portfolio_ids

A list of portfolio ids to retrieve portfolio holdings for

[integer]

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/holdings/get

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

Response fields

portfolios

An array containing the requested portfolios.

[object]

portfolio_id

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

integer

name

Name of the portfolio

string

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

isin

Unique ISIN number of stock associated with company, if available

string

cusip

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

holding_type

Type of holding (e.g., Company)

string

weight

Weight of the holding within the portfolio

string

paged_portfolios

Number of paged portfolios returned

integer

total_portfolios

Number of total portfolios available based on the request

integer

request_id

Unique id for the request

string

Example response

API Object

{
"portfolios" : [
{
"portfolio_id" : 553,
"name" : "Example Portfolio",
"created_at" : "2023-06-19",
"updated_at" : "2023-06-19",
"holdings" : [
"name" : Example Company,
"symbol" : XYZ,
"isin" : 248384ABC,
"cusip" : 428334333,
"uuid" : "II|V1|FactSetId|052hefh",
"open_figi" : "BBG093RKMB42",
"holding_type" : "Company",
"weight" : "0.037"
]
}
],
"paged_portfolios" : 1 ,
"total_portfolios" : 1 ,
"request_id" : "28HyTu"
}

/portfolios/holdings/update

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

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

Request fields

firm_id

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

string

secret

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

string

portfolio_id

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

integer

options

An optional object to be used with the request.

object

reset

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

true/false

holdings

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

[object]

symbol

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]

isin

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]

weight

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

[decimal]

Example request

/portfolios/holdings/update

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

Response fields

portfolio

An object containing information about the associated portfolio.

object

portfolio_id

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

integer

name

Name of the portfolio

string

total_holdings

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

integer

total_weight

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

decimal

updated

An array containing successfully-updated holdings

[object]

status

Status of the update attempt

integer

message

Message associated with the update attempt

string

name

Name of the associated company

string

symbol

Symbol (ticker) of the associated company

string

isin

Unique ISIN number of stock associated with company, if available

string

cusip

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

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

request_id

Unique id for the request

string

Example response

API Object

{
"portfolio" : {
"portfolio_id" : 553,
"name" : "Example Portfolio",
"total_holdings" : "100",
"total_weight" : "100",
},
"updated" : [{
"status" : 200,
"message" : Successfully added or updated XYZ Company,
"name" : XYZ Company,
"symbol" : XYZ,
"isin" : 248384ABC,
"cusip" : 428334333,
"uuid" : "II|V1|FactSetId|052hefh",
"open_figi" : "BBG093RKMB42",
"weight" : "0.037"
}],
"errors" : [{
"status" : 400,
"error_message" : Not able to find a company for passed symbol: XYZA. Verify the company exists or submit a coverage request for it to be added to Ethos.,
"error_code" : ITEM_NOT_FOUND
}],
"request_id" : "28HyTu"
}

/portfolios/ratings/get

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

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

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

Request fields

firm_id

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

string

secret

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

string

options

An object to be used with the request.

object

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

count

The number of portfolios to fetch.

Default: 10

Minimum: 1

Maximum: 100

integer

offset

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

Default: 0

Minimum: 0

integer

Example request

/portfolios/get

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

Response fields

portfolios

An array containing the requested portfolios.

[object]

portfolio_id

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

integer

name

Name of the portfolio

string

updated_at

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

string

ratings

A set of fields describing ESG ratings associated with the portfolio

object

cause

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

string

cause_id

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

integer

date

Date of the rating

date

score

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

integer

percentile

Percentile of the rating, compared to all portfolios

integer

paged_portfolios

Number of paged portfolios returned

integer

total_portfolios

Number of total portfolios available based on the request

integer

request_id

Unique id for the request

string

Example response

API Object

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

Errors

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

In this section

Error schema

Error codes

Error schema

error_code

The particular error code. Safe for programmatic use.

string

error_message

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

string

request_id

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

string

Error codes

INCORRECT_KEYS

Incorrect firm_id or secret sent with the request

string

NO_IDENTIFIER

No identifier passed for company or fund

string

ITEM_NOT_FOUND

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

string

PORTFOLIO_NOT_FOUND

Requested portfolio could not be found in the Ethos database

string

PORTFOLIO_IMPORTING

Requested portfolio is in the process of importing/updating

string

NO_COVERAGE_REQUESTS_AVAILABLE

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

string

OFFSET_TOO_HIGH

No records available with requested offset paramater

string

INTERNAL_SERVER_ERROR

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

string

Ethos API

Better ESG data for your analysis or application

See the API docs

Endpoint schema

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/holdings/get /portfolios/holdings/update /portfolios/ratings/get

API Keys

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

Protocols and headers

API host

The Development environment is unrestricted and supports up to 100 API calls per week (contact us for additional calls). All testing should be done in the Development environment.

Companies

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

In this section

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

/companies/get

Request fields

Example request

Response fields

Example response

/companies/screens/get

Request fields

Example request

Response fields

Example response

/companies/ratings/get

Request fields

Example request

Response fields

Example response

/companies/metrics/get

Request fields

Example request

Response fields

Example response

/companies/list

Request fields

Example request

Response fields

Example response

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

Request fields

Example request

Response fields

Example response

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

Request fields

Example request

Response fields

Example response

/funds/screens/get

Request fields

Example request

Response fields

Example response

/funds/ratings/get

Request fields

Example request

Response fields

Example response

/funds/metrics/get

Request fields

Example request

Response fields

Example response

/funds/list

Request fields

Example request

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/holdings/get

/portfolios/holdings/update

/portfolios/ratings/get

/companies/get

/companies/screens/get

/companies/ratings/get

/companies/metrics/get

/companies/list

/funds/get

/funds/screens/get

/funds/ratings/get

/funds/metrics/get

/funds/list

/help/coverage_requests/get

/help/coverage_requests/create

/help/tickets/get

/help/tickets/create

/portfolios/get

/portfolios/holdings/get

/portfolios/holdings/update

/portfolios/ratings/get

Error schema

Error codes