Developer Documentation v2 · Latest

The Cleartraced ESG Data API

Version 2 retrieves structured company data from our database. It is a superset of v1: every v1 request works here, with more ways to query. The data available depends on your account access level.

Get API Access →

What’s new in v2

●Every identifier (company_name, lei, isin, registration_authority_id, WBA_ID) accepts a single value or an array.

●New WBA_ID identifier matches companies by their WBA identifier, and several identifiers can be combined in one request as a deduplicated union.

●Monetary values are returned in your account currency with originals preserved, and the response always states its currency.

Authentication

Send your API token as a Bearer token in the Authorization header on every request.

curl -X POST "https://api.cleartraced.com/api/v2/get-company-data" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "WBA_ID": "PT_00637" }'

Query Examples

Single value or array

Every identifier accepts a single value or an array. Send a string to match one, or an array to match several.

{ "lei": "549300Q87LKPPD4X9R30" }

{ "lei": ["549300Q87LKPPD4X9R30", "529900MZ8Y3QGPDF6815"] }

WBA IDNew

Match by WBA identifier. The key must be exactly WBA_ID.

{ "WBA_ID": ["PT_00637", "ERIC_0123"] }

Company name with fuzzy search

fuzzy_search applies only to company_name. Off (default) = exact, case-sensitive match. On = case-insensitive substring match.

{ "company_name": "ericsson", "fuzzy_search": true }

Combine identifiers (union)New

Several identifiers in one request return the union of all matches, deduplicated so each report appears once.

{
  "company_name": ["AFRY AB"],
  "lei": ["549300W9JLPW15XIFM52"],
  "isin": ["SE0000949331"],
  "WBA_ID": ["PT_00637"]
}

Filter by reporting year

One year or several. Years outside your account’s subscribed years are never returned.

{ "WBA_ID": "PT_00637", "reporting_year": [2023, 2024, 2025] }

Pagination

Use page (default 1) and limit (default 10, max 100). Request pages incrementally until data comes back as an empty array. Results are ordered by reporting year (newest first), then company name.

{ "lei": "549300W9JLPW15XIFM52", "page": 1, "limit": 25 }

Success Response

A 200 response with matching reports. Fields depend on your account access level. Monetary fields are converted to your account currency; if no exchange rate is available they stay in their original currency.

{
  "status": true,
  "data": [
    {
      "company_name": "AFRY AB",
      "reporting_year": "2024",
      "country_code_2_digit_iso": "SE",
      "registration_authority_id": "556542-9841",
      "lei": "549300Q87LKPPD4X9R30",
      "WBA_ID": "-",
      "isin": ["SE0000314544", "SE0000314551"],
      "revenue": "2 566 000 000",
      "ebit": "217 000 000",
      "currency": "EUR",
      "original_currency": "SEK",
      "original_revenue": "28 523 000 000",
      "original_ebit": "2 416 000 000",
      "scope_1": "8 707",
      "scope_3": "51 317",
      "entity_status": "ACTIVE"
    }
  ]
}

No matching records

A valid, authenticated request that matches nothing returns an empty list with HTTP 200 (not an error). An empty list can also mean the matched companies fall outside your account’s access scope.

{ "status": true, "data": [] }

Conventions & Limits

Case sensitivity

lei, isin, WBA_ID and registration_authority_id are matched exactly and are case-sensitive. company_name is also case-sensitive unless fuzzy_search is true.

Missing values

Any field with no value is returned as the string –, never null.

Units

Monetary fields (revenue, ebit) use the currency named by the currency field. Emissions scope fields are in tonnes of CO₂ equivalent (tCO₂e).

Multiple values per identifier

Each identifier accepts up to 50 values. Any beyond the first 50 are ignored.

Broad queries

Before access filtering, a query scans at most 10,000 matching reports. Prefer specific identifiers over broad fuzzy searches.

Rate limits

Requests are limited to 500 per minute. Every response includes rate-limit headers. When exceeded, the API returns HTTP 429 with a Retry-After value.

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1718012345
Retry-After: 42

Errors

Every error response is a flat JSON object with status: false and a msg string. The HTTP status code is on the response itself.

400

No company identifier

{ "status": false, "msg": "Please provide at least one valid company identifier (company_name, lei, isin, registration_authority_id, or WBA_ID)." }

401

Missing authorization

{ "status": false, "msg": "Missing or invalid Authorization header" }

401

Invalid or revoked key

{ "status": false, "msg": "Invalid or unauthorized API key." }

403

Access not configured

Your account has no locations or whitelisted companies configured. Contact us to configure access.

{ "status": false, "msg": "Access denied - no locations or whitelisted companies configured in your account settings" }

404

Account configuration not found

Your account’s data-access or visible-columns configuration cannot be found. Contact support.

{ "status": false, "msg": "DAC not found" }

429

Rate limit exceeded

{ "status": false, "msg": "Too many requests, please try again after a minute." }

429

Account usage limit reached

Your account’s total API usage limit has been reached. Contact us to raise your limit.

{ "status": false, "msg": "Your account's API usage limit has been reached. Please contact support to raise your account limit." }

500

Server error

{ "status": false, "msg": "Unable to retrieve company data at this time. Please try again later." }

Ready to integrate?

Get API access and start querying structured, source-traceable ESG data for any disclosing company worldwide.

Get API Access → Email us