InvestVerte API Documentation

Access ESG (Environmental, Social, Governance) rating data for companies, countries, sectors and ETFs.

Try it — Swagger UI ReDoc reference
Authentication Limits & usage Companies Countries Sectors ETFs Status Codes Example Request

Authentication

The API uses Token Authentication. Include your token in the Authorization header on every request.

Authorization: Token <your_token>

To obtain a token, contact the administrator or use the login endpoint if available.

Limits & usage

Customer subscriptions include 15,000 successful API requests per calendar month, with a burst limit of 30 requests per minute.

  • Only successful responses from API data endpoints consume the monthly allowance.
  • Authentication failures, permission errors, server errors and /api/usage/ do not consume requests.
  • The allowance resets automatically at the start of each calendar month.
  • The subscription page displays warnings at 80% and 95% usage.

Check current usage

GET /api/usage/ returns the current period, allowance and remaining requests. Calling this endpoint does not consume the quota.

{
  "access": {
    "enabled": true,
    "type": "subscription",
    "unlimited": false
  },
  "period": {
    "start": "2026-08-01",
    "end": "2026-09-01",
    "resets_at": "2026-09-01T00:00:00+02:00"
  },
  "usage": {
    "requests": 3750,
    "limit": 15000,
    "remaining": 11250,
    "percentage": 25.0,
    "level": "normal"
  },
  "rate_limit": "30/min"
}

Quota response headers

Successful customer API responses include:

X-API-Quota-Limit: 15000
X-API-Quota-Used: 3751
X-API-Quota-Remaining: 11249
X-API-Quota-Reset: 2026-09-01T00:00:00+02:00
When the minute or monthly limit is reached, the API returns 429 Too Many Requests and a Retry-After header. Do not retry continuously; wait for the indicated delay.

1. Companies

List of Companies

Retrieves a list of all available companies.

  • URL: /api/companies/
  • Method: GET
[
  {
    "symbol": "AAPL",
    "name": "Apple Inc."
  },
  ...
]

Company ESG Rating

Retrieves ESG rating details for a specific company. Choose between AI-generated data (ai) or historical data (legacy).

  • URL: /api/esg/<symbol>
  • Method: GET
  • Query parameters (optional):
    • model (string): ai (default) or legacy
    • year (int): year of the data
    • frequency (string): report frequency (e.g. "Annual", "Quarterly")
[
  {
    "e": 85.5,
    "s": 78.2,
    "g": 90.1,
    "esg": 84.6,
    "year": 2023,
    "frequency": "Annual"
  }
]

2. Countries

List of Countries

  • URL: /api/countries/
  • Method: GET
[
  {
    "country_code": "FR",
    "country_descr": "France"
  },
  ...
]

Country Data

Retrieves average ESG statistics for a specific country.

  • URL: /api/country/<symbol>
  • Method: GET
  • Query parameters (optional):
    • model (string): ai (default) or legacy
    • year (int): year of the data
    • frequency (string): report frequency
[
  {
    "symbol": "FR",
    "name": "France",
    "mean": 75.4,
    "median": 76.2,
    "year": 2023,
    "frequency": "Annual"
  }
]

3. Sectors

List of Sectors

  • URL: /api/sectors/
  • Method: GET
[
  {"sector": "Technology"},
  {"sector": "Finance"},
  ...
]

Sector Data

  • URL: /api/sector/<symbol>
  • Method: GET
  • Query parameters (optional):
    • model (string): ai (default) or legacy

4. ETFs

ETF ratings are the holdings-weighted aggregation of the underlying companies' E/S/G/ESG scores, with independent re-weighting per pillar (holdings with a missing weight or score are excluded and the remaining weights are re-normalized to 100%). ETFs whose ESG coverage is below the reliability threshold are excluded from the results.

List of ETFs

  • URL: /api/etfs/
  • Method: GET
  • Query parameters (optional):
    • model (string): legacy (default) or ai
    • month (string, YYYY-MM): holdings snapshot month. If omitted, the current/latest data is used.
[
  {
    "symbol": "IWDA.AS",
    "name": "iShares Core MSCI World UCITS ETF",
    "exchange": "AS",
    "score_e": 68.4,
    "score_s": 61.2,
    "score_g": 72.9,
    "score_esg": 67.5,
    "coverage_esg": 92.1,
    "nb_holdings_total": 500,
    "band_esg": "good"
  },
  ...
]

ETF ESG Rating

Retrieves the weighted ESG rating for a specific ETF.

  • URL: /api/etf/<symbol>
  • Method: GET
  • Query parameters (optional):
    • model (string): legacy (default) or ai
    • month (string, YYYY-MM): holdings snapshot month. If omitted, the current/latest data is used.
{
  "symbol": "IWDA.AS",
  "name": "iShares Core MSCI World UCITS ETF",
  "exchange": "AS",
  "score_e": 68.4,
  "score_s": 61.2,
  "score_g": 72.9,
  "score_esg": 67.5,
  "coverage_e": 92.1,
  "coverage_s": 92.1,
  "coverage_g": 92.1,
  "coverage_esg": 92.1,
  "nb_valid_esg": 480,
  "nb_missing_esg": 20,
  "nb_holdings_total": 500,
  "band_esg": "good"
}
month selects a specific monthly holdings snapshot, the same way the ETF dashboard lets you pick a past month. If a snapshot doesn't exist for the requested month, the API returns an empty result rather than an error.

Status Codes

  • 200 OK: Request successful.
  • 400 Bad Request: Invalid parameters (e.g. incorrect year).
  • 401 Unauthorized: Missing or invalid authentication token.
  • 403 Forbidden: User is not validated or does not have necessary permissions.
  • 404 Not Found: Resource (symbol, country, sector) does not exist.
  • 429 Too Many Requests: Per-minute or monthly customer quota reached.

Example Request (cURL)

curl -X GET "https://api.investverte.com/api/esg/AAPL?year=2023" \
     -H "Authorization: Token 1234567890abcdef"