ESG SaveEcoBot API Documentation

Unless stated otherwise, this page refers to Ukrainian companies and individual entrepreneurs and uses identifiers from Ukrainian public registries.

ESG SaveEcoBot API provides access to ESG profiles of Ukrainian enterprises and individual entrepreneurs through a Bearer API key. The main enterprise identifier in the API is registry_id (EDRPOU for companies or RNOKPP for individual entrepreneurs in Ukraine).

This page helps you quickly understand the API structure, authorization format, and the main response conventions. All ESG SaveEcoBot API responses are returned in JSON format, except file download requests.

The documentation is split into separate pages by entity and data section. Use the navigation on the left to move between sections: from enterprise details to specific data domains, files, and dictionaries.

A separate Changelog page is also available to record important documentation and structure updates.

Interactive API documentation

Interactive Swagger UI documentation provides a visual interface to understand all available endpoints and request/response schemas. It also allows you to test API calls directly in your browser with your Bearer token.

Our OpenAPI spec

You can download our OpenAPI specification file to use it with your favorite API tools and SDK generators.

Authorization

All ESG SaveEcoBot API requests use a Bearer API key. To obtain one, please contact the team at [email protected].

Example request

$ ESG_API_TOKEN="your_api_token"
$ curl "https://esg.saveecobot.com/api/v1/me" \
  -H "Authorization: Bearer $ESG_API_TOKEN" \
  -H "X-Request-Id: crm-sync-2026-05-14-001" \
  -H 'Accept: application/json'

Request ID

If needed, the client may send its own request identifier in the X-Request-Id header. This is useful for debugging and matching logs between your system and ESG SaveEcoBot API:

• if X-Request-Id is provided, the API uses that exact value;
• if X-Request-Id is not provided, the API generates one automatically;
• the value is returned both in the X-Request-Id response header and in stats.request_id.

Response headers

Every API response includes service headers:

• X-Request-Id: request identifier. If you sent one yourself, the API returns the same value. If not, the API generates it automatically.
• X-Response-Time-Ms: response generation time in milliseconds.

Successful response format

{
  "results": {},
  "stats": {
    "request_id": "uuid",
    "response_time_ms": 21
  }
}

Response fields

• results: main data block that depends on the specific request.
• stats.request_id: identifier of the specific HTTP request.
• stats.response_time_ms: request processing time in milliseconds.

Error format

{
  "error": {
    "code": "not_found",
    "message": "Resource not found.",
    "details": null
  },
  "stats": {
    "request_id": "uuid",
    "response_time_ms": 12
  }
}

Response fields

• error.code: machine-readable error code.
• error.message: short textual error description.
• error.details: additional details, if provided.
• stats.request_id: request identifier that can be shared with support.
• stats.response_time_ms: request processing time in milliseconds.

Enterprise block in enterprise responses

All enterprise requests automatically include a short enterprise block inside results, so it is always clear which enterprise the returned data belongs to.

The exception is the enterprise details request, where enterprise already contains the full main data set.

The short block looks like this:

"enterprise": {
  "type": "company",
  "registry_id": "00178353"
}

Fields

• enterprise.type: enterprise type. Possible values: company or fop.
• enterprise.registry_id: enterprise identifier. For company this is EDRPOU, for fop this is RNOKPP.

Pagination

All list endpoints use the same pagination block:

"pagination": {
  "current_page": 1,
  "per_page": 20,
  "total": 57,
  "last_page": 6
}

Pagination fields

• pagination.current_page: current page number.
• pagination.per_page: number of records per page. A fixed value of 20 is used.
• pagination.total: total number of records in the result set.
• pagination.last_page: number of the last available page.

Pagination parameters

• page: page number.

Filtering

All filters in ESG SaveEcoBot API are passed as query parameters in the URL.

For example:

• ?domain=air
• ?report_type_id=9

If a request supports several filters at once, they can be combined in one URL, for example:

$ ESG_API_TOKEN="your_api_token"
$ curl "https://esg.saveecobot.com/api/v1/enterprises/00178353/reports/air?report_type_id=9&page=2" \
  -H "Authorization: Bearer $ESG_API_TOKEN" \
  -H 'Accept: application/json'

Example request

$ ESG_API_TOKEN="your_api_token"
$ curl "https://esg.saveecobot.com/api/v1/me" \
  -H "Authorization: Bearer $ESG_API_TOKEN" \
  -H "X-Request-Id: crm-sync-2026-05-14-001" \
  -H 'Accept: application/json'

Example response

{
  "results": {
    "api_account": {
      "name": "Demo account",
      "all_registry_ids_allowed": false,
      "allowed_registry_ids": ["00178353", "03348471"],
      "billing_cycle": {
        "starts_at": "2026-05-01T00:00:00+03:00",
        "ends_at": "2026-05-31T23:59:59+03:00"
      },
      "limits": {
        "daily": {
          "enterprises": 100,
          "pages": 1000,
          "downloads": 200
        },
        "monthly": {
          "enterprises": 500,
          "pages": 10000,
          "downloads": 2000
        },
        "yearly": {
          "enterprises": 5000,
          "pages": 120000,
          "downloads": 24000
        }
      }
    },
    "current_key": {
      "name": "Production key",
      "last_used_at": "2026-05-14T11:00:00+03:00"
    },
    "usage": {
      "account": {
        "daily": {
          "enterprises": 10,
          "pages": 18,
          "downloads": 3
        }
      },
      "current_key": {
        "daily": {
          "enterprises": 4,
          "pages": 7,
          "downloads": 1
        }
      }
    }
  },
  "stats": { "request_id": "crm-sync-2026-05-14-001", "response_time_ms": 43 }
}

Response fields

results.api_account

• name: account name.