> ## 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.
# Get subsidiary
> Retrieve a single subsidiary of your own company by id, returning its name, type, MC and DOT numbers, default equipment type, and remit address.
Returns a single subsidiary of your own company by id. Use [List subsidiaries](/en/api/reference/subsidiaries/list-subsidiaries) when you do not already have the id.
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).
A subsidiary outside your credential's subsidiary scope answers `404`, identically to one that does not exist. This is deliberate: a scoped credential cannot use this endpoint to discover which subsidiaries exist that it may not read.
### Endpoint
```
GET /api/p/v{version}/subsidiaries/{id}
```
### Request Parameters
| Parameter | Type | Required | Description |
| -------------- | ------- | -------- | ---------------------------------------------------------------- |
| version | string | Yes | API version to use (`1.0`). |
| id | string | Yes | Unique identifier of the subsidiary. |
| includeDeleted | boolean | No | Return the subsidiary even if soft-deleted. Defaults to `false`. |
### Example CURL request
```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/subsidiaries/9d4b1327-2774-d32c-fb33-87a288c2722c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```
### Response Fields
| Field | Type | Description |
| -------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Id | string | Unique identifier of the subsidiary. |
| 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. Publishes `US`, `CA` or `MX` for recognized spellings of those countries, otherwise the value exactly as recorded. Omitted when no country is recorded, which must not be read as the United States. |
### 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"
}
}
```
### Status Codes
| Status | Description |
| ------ | -------------------------------------------------------------------- |
| 200 | Subsidiary returned. |
| 401 | Missing or invalid access token. |
| 403 | Token lacks the `subsidiary:read` scope. |
| 404 | Subsidiary not found, or outside your credential's subsidiary 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/{id}
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/{id}:
get:
tags:
- Subsidiaries
summary: Get subsidiary
description: >-
Returns a single subsidiary of your own company by id. A subsidiary
outside your credential's subsidiary scope responds 404, identically to
one that does not exist.
parameters:
- name: id
in: path
required: true
schema:
type: string
- 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:
$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'
'404':
description: Not Found
content:
application/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 `.
````