| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Returns the individual location records that make up a company's footprint, as a paginated list.
List of summary
Both endpoints resolve the same footprint. They differ in what they give you back.
| List a company's locations | Get footprint summary | |
|---|---|---|
| Returns | The individual location records | Totals and a country breakdown |
| Filters | Country, location type, NAICS | None |
| Pagination | Yes | Single response |
Use this endpoint when you need the sites themselves: what happens at each one, where it is, how large it is, and which building it occupies. It is also the only one of the two that accepts filters, so any question narrowed by country, location type, or activity is answered here.
Use the summary when you only need the size and spread of the footprint, and do not want to page through individual records to get it.
Optional filters
| Parameter | Type | Description |
|---|---|---|
country_code | string | ISO 3166-1 alpha-2 country code, case-insensitive. US, DE, fr. |
location_type_l1 | string | One or more Level 1 location type IDs, comma-separated. |
location_type_l2 | string | One or more Level 2 location type IDs, comma-separated. |
location_type_l3 | string | One or more Level 3 location type IDs, comma-separated. |
naics_code | string | One or more NAICS 2022 codes, comma-separated. Each code is 2, 4, or 6 digits, up to 20 codes per request. |
Filters narrow the resolved footprint. They never change how the footprint itself is defined. ?country_code=FR means resolve this company's footprint, then return only the French locations, which keeps one consistent definition of a footprint across every query.
How location type filters combineMultiple values at the same level are combined with OR. Different levels are combined with AND.
?location_type_l2=general_warehouse,distribution_centerreturns locations classified as either a general warehouse or a distribution centre. Adding&location_type_l1=warehouse_storage_distributionrequires both conditions.Filters match on the taxonomy ID. Responses carry the human-readable name. See Location type taxonomy for the IDs.
Pagination
The endpoint follows the standard Veridion cursor-based pagination contract: page_size, cursor, and max_results on the request, next_cursor and has_more on the response. See Pagination for the parameters and cursor semantics.
Successful responses
When the request is successful, a standard 200 OK HTTP status will be sent along with the expected JSON. The response uses the standard paginated envelope:
| Field | Description |
|---|---|
next_cursor | Cursor for the next page, or null when pagination is complete. |
has_more | Whether another page is available. |
result_count | Total number of locations matching the request, not the size of this page. |
result | Location records on the current page. |
Each entry in result is the same location object returned by Get a location by ID. This endpoint does not introduce a separate representation of a location.
A company that exists but currently has no active locations returns 200 with result_count: 0 and an empty result array.
Response fieldsFor a comprehensive list of all data points returned on a location, see the Response fields and types page.
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; a filter value is malformed, for example a NAICS code that is not 2, 4, or 6 digits, or more than 20 codes;page_size or max_results is out of range; an unrecognised query parameter was supplied; or the cursor is malformed or does not belong to this company and filter combination. |
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 result 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.
200with an empty result means the company exists, but no active location currently matches the request.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.