Subsidiaries
List subsidiaries
List the subsidiaries of your own company so an integration can resolve a subsidiary id to a recognizable name, MC or DOT number, and remit address.
GET
/
api
/
p
/
v
{version}
/
subsidiaries
List subsidiaries
curl --request GET \
--url https://integrations.alvys.com/api/p/v{version}/subsidiaries \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://integrations.alvys.com/api/p/v{version}/subsidiaries', 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}/subsidiaries"
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}/subsidiaries",
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}/subsidiaries"
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}/subsidiaries")
.header("Authorization", "Bearer <token>")
.asString();[
{
"Id": "<string>",
"Name": "<string>",
"Type": "<string>",
"McNumber": "<string>",
"DotNumber": "<string>",
"DefaultEquipmentType": "<string>",
"RemitAddress": {
"Street": "<string>",
"City": "<string>",
"State": "<string>",
"ZipCode": "<string>",
"Country": "<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 subsidiaries of your own company. Nothing in the Alvys interface shows a subsidiary id, so this is how an integration resolves one — for example the
SubsidiaryId a webhook subscription is scoped to, or the subsidiary a trip was tendered as.
Deleted subsidiaries are omitted unless you pass includeDeleted=true. A credential scoped to specific subsidiaries only ever receives those, and includeDeleted cannot widen that scope.
A company with no subsidiaries returns 200 and an empty array, not 404. The list addresses no single resource, so there is nothing to be missing.
This endpoint requires the
subsidiary:read scope. It is not part of any other scope, and credentials issued before it existed do not carry it — grant it to the client before your first call. See Authentication.Endpoint
GET /api/p/v{version}/subsidiaries
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | string | Yes | API version to use (1.0). |
| includeDeleted | boolean | No | Include soft-deleted subsidiaries. Defaults to false. |
Example CURL request
curl --location 'https://integrations.alvys.com/api/p/v1/subsidiaries' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Response Fields
The response is an array of subsidiary objects.| Field | Type | Description |
|---|---|---|
| Id | string | Unique identifier of the subsidiary. This is the value other endpoints expect as a subsidiary id. |
| Name | string | Name of the subsidiary. |
| Type | string | Either Carrier or Brokerage. |
| McNumber | string | MC number of the subsidiary. Omitted when none is recorded. |
| DotNumber | string | DOT number of the subsidiary. Omitted when none is recorded. |
| DefaultEquipmentType | string | Default equipment type for the subsidiary. |
| RemitAddress | Object | Postal remit-to address. Postal fields only — no contact details. |
| RemitAddress.Street | string | Street line of the remit address. |
| RemitAddress.City | string | City of the remit address. |
| RemitAddress.State | string | State or province of the remit address. |
| RemitAddress.ZipCode | string | Postal code of the remit address. |
| RemitAddress.Country | string | Country of the remit address. See Country values. |
Example Response
200 OK[
{
"Id": "9d4b1327-2774-d32c-fb33-87a288c2722c",
"Name": "Alvy's Motor",
"Type": "Carrier",
"McNumber": "1234567",
"DotNumber": "2515539",
"DefaultEquipmentType": "Van",
"RemitAddress": {
"Street": "201 Lomas Santa Fe Dr",
"City": "Solana Beach",
"State": "CA",
"ZipCode": "92075",
"Country": "US"
}
}
]
Country values
Country publishes the ISO 3166-1 alpha-2 code when the recorded value is a recognized spelling of the United States, Canada or Mexico. Any other recorded value publishes exactly as stored, which for addresses created before the field existed may be any string.
Country is omitted when no country is recorded. An absent Country must not be read as the United States.Status Codes
| Status | Description |
|---|---|
| 200 | Subsidiaries returned. An empty array is a valid result. |
| 401 | Missing or invalid access token. |
| 403 | Token lacks the subsidiary:read scope. |
| 429 | Rate limit exceeded. |
Rate Limits
All endpoints are subject to rate limits to protect the API from traffic spikes. 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"
Query Parameters
⌘I
List subsidiaries
curl --request GET \
--url https://integrations.alvys.com/api/p/v{version}/subsidiaries \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://integrations.alvys.com/api/p/v{version}/subsidiaries', 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}/subsidiaries"
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}/subsidiaries",
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}/subsidiaries"
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}/subsidiaries")
.header("Authorization", "Bearer <token>")
.asString();[
{
"Id": "<string>",
"Name": "<string>",
"Type": "<string>",
"McNumber": "<string>",
"DotNumber": "<string>",
"DefaultEquipmentType": "<string>",
"RemitAddress": {
"Street": "<string>",
"City": "<string>",
"State": "<string>",
"ZipCode": "<string>",
"Country": "<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>"
}