> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alvys.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
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](/en/api/guides/authentication-1).
### 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
```bash theme={null}
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](#country-values). |
### Example Response
**200 OK**
```json theme={null}
[
{
"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](/en/api/guides/rate-limits).
## OpenAPI
````yaml GET /api/p/v{version}/subsidiaries
openapi: 3.0.1
info:
title: Alvys
description: >-
Alvys provides a robust set of REST APIs to allow you to integrate Alvys
into virtually any platform. These APIs cover most of Alvys' major product
areas with additional endpoints being added regularly based on customer
requests.
contact:
name: Alvys Support
url: https://www.alvys.com/resources/contact/
version: v1
servers:
- url: https://integrations.alvys.com
description: Public API Server
- url: https://api.alvys.com/
description: Public API Server
security:
- Public: []
tags:
- name: Authentication
description: Obtain an OAuth 2.0 access token for the Alvys Public API.
- name: Carrier Settlement Statements
description: >-
Search carrier settlement statements and retrieve a single statement by
number.
- name: Carriers
description: Read carrier records, search carriers, and manage carrier documents.
- name: Customers
description: Create, read, update, delete, and search customer records.
- name: Deductions
description: >-
Create one-time deductions and search or delete existing deduction
records.
- name: DispatchPreferences
description: Dispatch preferences endpoints for reading dispatch rules and preferences.
- name: Driver Settlement Statements
description: >-
Search driver settlement statements and retrieve a single statement by
number.
- name: Drivers
description: >-
Read driver records, search drivers and driver events, and manage driver
documents.
- name: Fuel
description: Read and search fuel transactions.
- name: Invoices
description: >-
Read invoices, create carrier invoices, and record carrier and customer
payments.
- name: Loads
description: Read, update, search loads, and manage load documents and notes.
- name: Locations
description: Read and search company location details.
- name: Maintenance
description: Read and search maintenance records.
- name: Subsidiaries
description: >-
List your company's subsidiaries and read a single subsidiary, so an
integration can resolve a subsidiary id to a recognizable name.
- name: Tenders
description: Create, accept, reject, cancel, update, and search inbound EDI tenders.
- name: Tolls
description: Read and search toll transactions.
- name: Tracking
description: >-
Record an asset's current location or telemetry from a third-party source,
such as an external ELD or a self-reporting vehicle.
- name: Trailers
description: Read trailers, search trailer events, and manage trailer documents.
- name: Trips
description: >-
Read, search trips, manage trip documents, and record stop appointments,
arrivals, and departures.
- name: Trucks
description: Read trucks, search truck events, and manage truck documents.
- name: Users
description: List and search users.
- name: Visibility
description: >-
Read inbound and outbound visibility history and search outbound
visibility errors.
- name: Webhooks
description: >-
Create, read, update, delete, enable, disable, verify, test, and rotate
secrets for webhook subscriptions; read event types, delivery logs, and
health metrics.
paths:
/api/p/v{version}/subsidiaries:
get:
tags:
- Subsidiaries
summary: List subsidiaries
description: >-
Returns the subsidiaries of your own company. Deleted subsidiaries are
omitted unless `includeDeleted` is true, and a credential scoped to
specific subsidiaries only ever receives those.
parameters:
- name: includeDeleted
in: query
schema:
type: boolean
default: false
- name: version
in: path
description: API version (e.g., 1.0)
required: true
schema:
type: string
default: '1.0'
example: '1.0'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: >-
#/components/schemas/Alvys.Models.Subsidiaries.SubsidiaryResponse
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
application/problem+json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
application/problem+json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
'429':
description: Too Many Requests
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
security:
- Public: []
components:
schemas:
Alvys.Models.Subsidiaries.SubsidiaryResponse:
required:
- Id
- Name
- Type
type: object
properties:
Id:
type: string
Name:
type: string
Type:
type: string
McNumber:
type: string
nullable: true
DotNumber:
type: string
nullable: true
DefaultEquipmentType:
type: string
nullable: true
RemitAddress:
allOf:
- $ref: '#/components/schemas/Alvys.Features.Locations.ShortAddress'
nullable: true
additionalProperties: false
Microsoft.AspNetCore.Mvc.ProblemDetails:
type: object
properties:
Type:
type: string
nullable: true
Title:
type: string
nullable: true
Status:
type: integer
format: int32
nullable: true
Detail:
type: string
nullable: true
Instance:
type: string
nullable: true
additionalProperties: {}
Alvys.Features.Locations.ShortAddress:
required:
- City
- State
- Street
- ZipCode
type: object
properties:
Street:
type: string
City:
type: string
State:
type: string
ZipCode:
type: string
Country:
type: string
description: >-
ISO 3166-1 alpha-2 country code where the recorded value is a
recognized spelling of United States, Canada or Mexico; otherwise
the country exactly as recorded, which for addresses created before
this field existed may be any string. Omitted when no country is
recorded; an absent Country must NOT be interpreted as US.
nullable: true
additionalProperties: false
securitySchemes:
Public:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
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 `.
````