References
List reference definitions
Returns tenant custom reference definitions visible to the Public API, keyed by entity (Load, Stop, …). Pass one or more entities query values. Each requested entity requires its matching read scope (load:read for Load, stop:read for Stop); requesting both requires both scopes.
GET
/
api
/
p
/
v
{version}
/
references
List custom reference definitions
curl --request GET \
--url https://integrations.alvys.com/api/p/v{version}/references \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://integrations.alvys.com/api/p/v{version}/references', 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}/references"
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}/references",
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}/references"
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}/references")
.header("Authorization", "Bearer <token>")
.asString();{}{
"Errors": {},
"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>"
}Returns the catalog of custom reference definitions your tenant exposes to the Public API. Use this before creating a catalog-backed reference so you have the definition
Id, Type, and allowed Values.
Only definitions marked visible to the Public API are returned. The response is an object keyed by entity name (Load, Stop, Trip, …).
Each requested entities value requires its matching read scope: load:read for Load, stop:read for Stop, and trip:read for Trip. Requesting more than one requires each corresponding scope.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
| entities | string[] | No | One or more entity kinds to include. Common values: Load, Stop, Trip. |
| version | string | Yes | API version in the path (for example 2.0). |
Example
curl --location 'https://integrations.alvys.com/api/p/v2.0/references?entities=Load&entities=Stop&entities=Trip' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Response shape
{
"Load": [
{
"Id": "tenant-reference-id",
"Name": "Customer PO",
"CanBeAppliedTo": ["Load"],
"Type": "Text",
"Values": null,
"Description": "Customer-provided purchase order"
}
],
"Stop": [],
"Trip": []
}
Status codes
| Code | Description |
|---|---|
| 200 | Catalog returned for the requested entities. |
| 400 | Request validation failed. |
| 401 | Authentication failed or the token is missing. |
| 403 | The token lacks the required read scope(s). |
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., 2.0)
Example:
"2.0"
Query Parameters
Available options:
Stop, Load, Trip, Driver, Truck, Trailer, Customer, Location Response
OK
Show child attributes
Show child attributes
⌘I
List custom reference definitions
curl --request GET \
--url https://integrations.alvys.com/api/p/v{version}/references \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://integrations.alvys.com/api/p/v{version}/references', 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}/references"
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}/references",
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}/references"
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}/references")
.header("Authorization", "Bearer <token>")
.asString();{}{
"Errors": {},
"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>"
}