Locations
Get location
Retrieve saved location records from Alvys, including shipper and consignee addresses, contact details, receiving hours, and geocoded coordinates.
GET
/
api
/
p
/
v
{version}
/
locations
Get location
curl --request GET \
--url https://integrations.alvys.com/api/p/v{version}/locations \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://integrations.alvys.com/api/p/v{version}/locations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://integrations.alvys.com/api/p/v{version}/locations"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://integrations.alvys.com/api/p/v{version}/locations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://integrations.alvys.com/api/p/v{version}/locations"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://integrations.alvys.com/api/p/v{version}/locations")
.header("Authorization", "Bearer <token>")
.asString();{
"Id": "<string>",
"Name": "<string>",
"CompanyNumber": "<string>",
"Type": "<string>",
"Status": "<string>",
"Email": [
"<string>"
],
"Phone": [
"<string>"
],
"Notes": [
{
"id": "<string>",
"Description": "<string>",
"NoteType": "<string>",
"User": "<string>",
"Time": "2023-11-07T05:31:56Z",
"UserId": "<string>"
}
],
"References": [
{
"Name": "<string>",
"Value": "<string>",
"Id": "<string>",
"ReferenceId": "<string>",
"Type": "<string>",
"Access": "<string>",
"Origin": "<string>"
}
],
"PhysicalAddress": {
"Street": "<string>",
"City": "<string>",
"State": "<string>",
"ZipCode": "<string>",
"Country": "<string>"
},
"Fax": "<string>",
"DateCreated": "2023-11-07T05:31:56Z",
"ExternalId": "<string>"
}{
"Type": "<string>",
"Title": "<string>",
"Status": 123,
"Detail": "<string>",
"Instance": "<string>"
}{
"Type": "<string>",
"Title": "<string>",
"Status": 123,
"Detail": "<string>",
"Instance": "<string>"
}{
"Type": "<string>",
"Title": "<string>",
"Status": 123,
"Detail": "<string>",
"Instance": "<string>"
}{
"Type": "<string>",
"Title": "<string>",
"Status": 123,
"Detail": "<string>",
"Instance": "<string>"
}{
"Type": "<string>",
"Title": "<string>",
"Status": 123,
"Detail": "<string>",
"Instance": "<string>"
}The endpoint for retrieving a single location requires specifying the API version in the path and one identifier in the query: either
Lookup by companyNumber:
id or companyNumber. For details on how versioning works, see the Versioning page.
Request Parameters
Path parameters| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String | Yes | The API version to use. |
| id | String | Conditionally required | The unique Location ID. Required if companyNumber is not provided. |
| companyNumber | String | Conditionally required | The company number. Required if id is not provided. |
Exactly one ofidorcompanyNumbermust be provided.
Example cURL requests
Lookup by id:curl --location 'https://integrations.alvys.com/api/p/v1/locations?id=120f97b9-1aa2-4201-b1aa-24...' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
curl --location 'https://integrations.alvys.com/api/p/v1/locations?companyNumber=MGD0012312345' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| Id | String | Unique location identifier. |
| Name | String | Location name. |
| CompanyNumber | String | Company number for this location. This is provided when uploading files for that company. |
| Type | String | Location type (e.g., Terminal, Shipper/Consignee, Cold Warehouse, Dry Warehouse). |
| Status | String | Location status (e.g., Active, Disabled, Inactive). |
| PhysicalAddress | Object | Address block. |
| PhysicalAddress.Street | String | Street line. |
| PhysicalAddress.City | String | City. |
| PhysicalAddress.State | String | State/Province. |
| PhysicalAddress.ZipCode | String | ZIP/Postal code. |
| Array of String | Email addresses. | |
| Phone | Array of String | Phone numbers. |
| Fax | String | Fax number. |
| DateCreated | String (DateTime) | Creation timestamp (UTC). |
| ExternalId | String | External reference ID (if any). |
| Notes | Array of Object | Notes attached to the location. |
| Notes[].id | String | Note identifier. |
| Notes[].Description | String | Note text. |
| Notes[].NoteType | String | Type/category of the note. |
| Notes[].Time | String (DateTime) | Timestamp of the note (UTC). |
| Notes[].User | String | Author/user who added the note. |
| References | Array of Objects | An optional list of custom references associated with the location. Only values whose reference definition includes the Public API surface are returned. |
Example Response
{
"Id": "loc-45678",
"Name": "Alvys Teminal Group LLC",
"CompanyNumber": "LP-12345",
"Type": "Terminal",
"Status": "Active",
"PhysicalAddress": {
"Street": "001 Main St",
"City": "Dallas",
"State": "TX",
"ZipCode": "70000"
},
"Email": ["terminal@acme.example"],
"Phone": ["+1-214-555-0100"],
"Fax": null,
"DateCreated": "2025-09-08T16:01:26.908Z",
"ExternalId": "EXT-001",
"Notes": [
{
"id": "n-001",
"Description": "24/7 gate access",
"NoteType": "General",
"Time": "2025-09-08T18:10:00Z",
"User": "dispatch@acme.example"
}
]
}
Rate Limits
All endpoints are subject to platform rate limits. See Rate Limits.Authorizations
OAuth 2.0 client-credentials access token. Obtain one from https://auth.alvys.com/oauth/token (grant_type=client_credentials, audience=https://api.alvys.com/public/), then paste it here. The playground sends it as Authorization: Bearer <token>.
Path Parameters
API version (e.g., 1.0)
Example:
"1.0"
Response
OK
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
⌘I
Get location
curl --request GET \
--url https://integrations.alvys.com/api/p/v{version}/locations \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://integrations.alvys.com/api/p/v{version}/locations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://integrations.alvys.com/api/p/v{version}/locations"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://integrations.alvys.com/api/p/v{version}/locations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://integrations.alvys.com/api/p/v{version}/locations"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://integrations.alvys.com/api/p/v{version}/locations")
.header("Authorization", "Bearer <token>")
.asString();{
"Id": "<string>",
"Name": "<string>",
"CompanyNumber": "<string>",
"Type": "<string>",
"Status": "<string>",
"Email": [
"<string>"
],
"Phone": [
"<string>"
],
"Notes": [
{
"id": "<string>",
"Description": "<string>",
"NoteType": "<string>",
"User": "<string>",
"Time": "2023-11-07T05:31:56Z",
"UserId": "<string>"
}
],
"References": [
{
"Name": "<string>",
"Value": "<string>",
"Id": "<string>",
"ReferenceId": "<string>",
"Type": "<string>",
"Access": "<string>",
"Origin": "<string>"
}
],
"PhysicalAddress": {
"Street": "<string>",
"City": "<string>",
"State": "<string>",
"ZipCode": "<string>",
"Country": "<string>"
},
"Fax": "<string>",
"DateCreated": "2023-11-07T05:31:56Z",
"ExternalId": "<string>"
}{
"Type": "<string>",
"Title": "<string>",
"Status": 123,
"Detail": "<string>",
"Instance": "<string>"
}{
"Type": "<string>",
"Title": "<string>",
"Status": 123,
"Detail": "<string>",
"Instance": "<string>"
}{
"Type": "<string>",
"Title": "<string>",
"Status": 123,
"Detail": "<string>",
"Instance": "<string>"
}{
"Type": "<string>",
"Title": "<string>",
"Status": 123,
"Detail": "<string>",
"Instance": "<string>"
}{
"Type": "<string>",
"Title": "<string>",
"Status": 123,
"Detail": "<string>",
"Instance": "<string>"
}