Get location

GET

api

{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));

<?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))

}

{
  "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>"
    }
  ],
  "PhysicalAddress": {
    "Street": "<string>",
    "City": "<string>",
    "State": "<string>",
    "ZipCode": "<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 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 of id or companyNumber must 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'

Lookup by companyNumber:

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.
Email	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.

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

Authorization

string

header

required

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

version

string

default:1.0

required

API version (e.g., 1.0)

Example:

"1.0"

Query Parameters

string

companyNumber

string

Response

string

required

Name

string

required

CompanyNumber

string

required

Type

string

required

Status

string

required

string[]

required

Phone

string[]

required

Notes

object[]

required

Show child attributes

PhysicalAddress

object | null

Show child attributes

Fax

string | null

DateCreated

string<date-time> | null

ExternalId

string | null

⌘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));

<?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))

}

{
  "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>"
    }
  ],
  "PhysicalAddress": {
    "Street": "<string>",
    "City": "<string>",
    "State": "<string>",
    "ZipCode": "<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>"
}

​Request Parameters

​Example cURL requests

​Response Parameters

​Example Response

​Rate Limits

Authorizations

Path Parameters

Query Parameters

Response

Request Parameters

Example cURL requests

Response Parameters

Example Response

Rate Limits