/api/p/v{version}/locations/search

The Locations endpoint provides detailed information about company-related sites such as Terminals, Shippers/Consignees, Cold Warehouses, and Dry Warehouses. The endpoint for searching locations requires specifying the API version in the path and providing filters in the request body. For details on API versioning, see Versioning.

Request Parameters

Path parameters

Parameter	Type	Required	Description
version	String	Yes	The API version to use.

Request body (filters + paging)

Parameter	Type	Required	Description
Page	Integer	No	Page index.
PageSize	Integer	Yes	Page size (must be > 0).
Statuses	Array of String	Yes	Filter by one or more location statuses. Supported values: `"Active"`, `"Disabled"`, `"Inactive"`.
LocationIds	Array of String	Yes	Filter by a set of Location IDs.
CreatedDateRange	Object	No	Filter by creation timestamp range (UTC).
CreatedDateRange.Start	String (DateTime)	No	Start of the date range.
CreatedDateRange.End	String (DateTime)	No	End of the date range.

Example cURL request

curl --location 'https://integrations.alvys.com/api/p/v1/locations/search' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Page": 0,
  "PageSize": 100,
  "Statuses": ["Active", "Disabled"],
  "LocationIds": [],
  "CreatedDateRange": {
    "Start": "2025-01-01T00:00:00Z",
    "End": "2025-09-08T23:59:59Z"
  }
}'

Response Parameters

Parameter	Type	Description
total	integer	The total number of items matching the criteria.
pageSize	integer	The number of items per page.
items[].id	string	Unique identifier of the location.
items[].name	string	Location (company site) name.
items[].companyNumber	string	Company number for this location. This is also provided when uploading files for that company.
items[].type	string	Location type (e.g., Terminal, Shipper/Consignee, Cold Warehouse, Dry Warehouse).
items[].status	string	Location status. Supported values: `"Active"`, `"Disabled"`, `"Inactive"`.
items[].physicalAddress.street	string	The street line of the location’s physical address.
items[].physicalAddress.city	string	The city of the location.
items[].physicalAddress.state	string	The state or province of the location.
items[].physicalAddress.zipCode	string	The postal/ZIP code of the location.
items[].email[]	array of string	A list of email addresses for the location.
items[].phone[]	array of string	A list of phone numbers for the location.
items[].fax	string	The fax number for the location.
items[].dateCreated	string (datetime)	Timestamp when the location was created (UTC).
items[].externalId	string	An external reference identifier, if applicable.
items[].notes[]	array of objects	A list of notes attached to the location.
items[].notes[].id	string	Unique identifier of the note.
items[].notes[].description	string	The text of the note.
items[].notes[].noteType	string	The type/category of the note.
items[].notes[].time	string (datetime)	The timestamp when the note was created (UTC).
items[].notes[].user	string	The user who created the note.

Rate Limit

All endpoints are subject to platform rate limits. See Rate Limits.