| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Returns aggregate information about a company's footprint without retrieving the individual location records.
It applies the same footprint expansion rules as the list endpoint, so the two views always describe the same set of locations.
Summary or locations list
Both endpoints resolve the same footprint. They differ in what they give you back.
| Get footprint summary | List a company's locations | |
|---|---|---|
| Returns | Totals and a country breakdown | The individual location records |
| Filters | None | Country, location type, NAICS |
| Pagination | Single response | Yes |
Use this endpoint when you need the size and spread of a footprint: how many sites a company runs, and how they are distributed across countries. It answers that in one call, whatever the size of the footprint.
Use the list endpoint when you need the sites themselves, or when the question is narrower than a whole footprint.
Narrower totals come from the list endpointThe summary takes no filters, so it cannot answer a question such as how many distribution centres a company runs in France.
Call the list endpoint with the filters you need and read
result_count, which reports the total number of matching locations rather than the size of the page. Apage_sizeof 1 is enough if you only want the number.
Successful responses
When the request is successful, a standard 200 OK HTTP status will be sent along with the expected JSON.
| Field name (key) | Type | Description |
|---|---|---|
| total_locations | integer | Total number of active locations in the resolved footprint. |
| countries_covered | integer | Number of distinct countries represented in the footprint. |
| by_country | array | Location counts broken down by country. |
| by_country[].country_code | string | ISO 3166-1 alpha-2 country code. |
| by_country[].country_name | string | Country name in English. |
| by_country[].total_locations | integer | Number of locations in that country. |
A company that exists but currently has no active locations returns 200 with total_locations: 0, countries_covered: 0, and an empty by_country array.
Error responses
If the request is unsuccessful, the API will return one of the below HTTP status responses:
| Status | When |
|---|---|
400 Bad Request | veridion_id is not a 16-character Veridion ID, or an unrecognised query parameter was supplied. |
403 Forbidden | The account's quota for this endpoint is exhausted, or the token lacks access to it. |
404 Not Found | No operational company exists for the given ID. This is also the response for a legal entity ID, which does not identify an operational company. |
503 Service Unavailable | The service is temporarily unable to serve the request. |
404and an empty footprint mean different things
404means the ID does not identify an operational company Veridion knows about. A legal entity ID or a retired ID both land here.
200withtotal_locations: 0means the company exists, but has no location that is currently active.The distinction is deliberate, and the two should be handled differently.
Any error response follows a specific structure. Please see the Error response format section for more details.