| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Retrieves the ESG commitments a company has published on its own web presence, as a paginated list.
When to use it
To assess what a company commits to. Retrieve the full set of a company's published ESG commitments during supplier onboarding or sustainability due diligence.
To check a specific ESG dimension. Filter by pillar or theme to see what a company has committed to on the dimension your assessment is concerned with, and where it is silent.
To evidence a stated programme. Every commitment carries the page it came from, so a claim can be traced to the company's own words for reporting and scorecards.
Filtering the result set
Two optional filters narrow the commitments returned. Both accept exact values only, with no fuzzy matching.
| Parameter | Accepted values |
|---|---|
pillar | Environmental, Social, Governance. |
theme | A theme from the ESG taxonomy, such as Climate Change or Human Rights. |
See ESG risk taxonomy for the full set of pillar and theme values.
Filters narrow the response, and nothing moreThese parameters filter the result set on the API side. They do not change what is collected for the company, and they do not influence whether new data is gathered.
Results pagination
Results are paginated using the same cursor based mechanism as other Veridion APIs. See the Pagination section for the parameters and tokens.
Capping how many commitments you fetch
max_resultscaps the total number of rows returned across a pagination sessionresult_countreports the total number of rows matching your filters and ignores themax_resultscap.
Sendmax_resultson every requestThe cap is not carried in the cursor. If you omit it when requesting a later page, it stops applying and paging continues through the full result set.
Successful response
Every response carries the same envelope, whatever state the request is in.
| Field | What it holds |
|---|---|
veridion_id | The company you requested. |
status | The state of the request. See Response states below. |
active_processing_session | The session currently collecting data for this company, or null where none is running. See Following a processing session below. |
last_computed_at | When the most recent completed collection for this company finished. Independent of your filters and paging: it describes when the data was produced, not which slice you are viewing. null only where no collection has ever completed for this company. |
result_count | Total rows matching your filters across the whole result set, not only this page. |
result | The commitment rows on this page. An empty array where nothing has been collected for the company, and while a new collection is getting under way. |
next_cursor | Cursor for the next page, or null on the last page. |
has_more | Whether more rows match beyond this page. |
Response fieldsFor a comprehensive list of all data points returned on an ESG commitment, see the Response fields and types page.
Response states
status takes one of three values.
status | Meaning | What to do |
|---|---|---|
complete | The commitments held for this company are current. A complete response can also carry an empty result, meaning none are available at present. | Consume what is returned. An empty result is a valid answer rather than an error. |
processing | The company's web presence is being collected in the background. | Request again after a short interval, or watch the processing session for the count to rise. |
not_found | The company was not found in Veridion's data sources. | Check the veridion_id. Repeating the request immediately returns the same answer. |
Branch onstatus, not on the HTTP codeEvery outcome of this endpoint is
200 OK, includingnot_found. Thestatusfield in the body is the answer.
An empty result is not a dead endA
completeresponse with an emptyresultmeans no commitments are available for this company at present. Requesting again later may return them, so you can re-check on your own schedule rather than treating the empty response as final.
A new collection replaces rather than adds to the previous oneWhile a collection is running you receive the commitments from that collection as they are extracted. The previously collected set is not served alongside it, so the two are never mixed.
Plan for the consequence: a company that returned forty commitments an hour ago can return fewer, or none, while a new collection is under way. The set is complete once
statusiscomplete.
Following a processing session
While status is processing, the response carries an active_processing_session, identifying the session collecting data for this company. It is null in every other state, because no session is running. Read more about processing sessions.
Capture it from a processing response if you intend to poll. Pass it to ESG processing status to check on that session, and to see how many commitments are available at request time, without requesting a page again. That endpoint is read-only.
Poll the session rather than re-requesting a pageWhile a collection runs, the session endpoint is the easier way to watch progress: it reports the state of the session and a count, without transferring any commitments. Request a page from this endpoint once the count tells you there is something worth fetching.
For this module that count covers the commitments produced by the session you are polling, so it starts at zero and climbs as pages are processed. It is not a total for the company.
A rising count is progress, not completionCommitments arrive as pages are processed, in batches rather than one by one, so the number climbs in steps while a session runs rather than jumping once at the end. There is no guaranteed rate or batch size, and a count that has not moved for a moment does not mean the session has finished.
Use
statusto determine completion, and the count only to judge whether there is enough to work with and decide to start fetching the results.
Example: commitments returned
{
"veridion_id": "abc-123",
"status": "complete",
"active_processing_session": null,
"last_computed_at": "2026-02-15T10:30:00.000Z",
"result_count": 15,
"result": [
{
"source_url": "https://example.com/sustainability",
"headline": "Our Carbon Commitments",
"relevant_text": "We commit to achieving carbon neutrality by 2030.",
"esg_pillar": "Environmental",
"esg_theme": "Climate Change",
"esg_risk_criteria": "Carbon Footprint"
}
],
"next_cursor": "eyJyIjpbIjE3MjFhM...",
"has_more": true
}Example: nothing held yet, collection in progress
{
"veridion_id": "abc-123",
"status": "processing",
"active_processing_session": "0c5b4e7a-1d52-4a4f-9c3c-1e0e5e8f1a2b",
"last_computed_at": null,
"result_count": 0,
"result": [],
"next_cursor": null,
"has_more": false
}Error responses
400 Bad Request, wherecursoris malformed or no longer matches the current result set.- other standard HTTP error responses, detailed in the Response codes section.
Any error response follows a specific structure. Please see the Error response format section for more details.