List subsidiaries

GET

api

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

}

[
  {
    "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

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

includeDeleted

boolean

default:false

Response

string

required

Name

string

required

Type

string

required

McNumber

string | null

DotNumber

string | null

DefaultEquipmentType

string | null

RemitAddress

object | null

Show child attributes

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

}

[
  {
    "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>"
}

​Endpoint

​Request Parameters

​Example CURL request

​Response Fields

​Example Response

​Country values

​Status Codes

​Rate Limits

Authorizations

Path Parameters

Query Parameters

Response

Endpoint

Request Parameters

Example CURL request

Response Fields

Example Response

Country values

Status Codes

Rate Limits