Subsidiaries

Overview

A subsidiary is a legal or operational entity under a company. Programs use subsidiaries to scope spend, budgets, cost centers, teams, and employee assignment when the parent company has multiple entities (for example regional offices or brands).

Typical flow:

1. Create a subsidiary: POST /md/api/Subsidiaries
2. Retrieve by ID: GET /md/api/Subsidiaries/{id}
3. List with a filter: GET /md/api/Subsidiaries with filter.where
4. Update a subsidiary: PATCH /md/api/Subsidiaries/{id}
5. Assign employees: set subsidiaryId on the user via PATCH /md/api/User/{id} (see Assign employees)

Create Subsidiary

Creates a new subsidiary for the company associated with your access token. The platform sets companyId, id, and status (default active) automatically.

Request Body: mandatory fields

Optional fields

Example Request

Using cURL:

curl -X POST https://sandbox.custodia-tech.com/md/api/Subsidiaries \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme US East",
    "code": "US-EAST",
    "currency": "USD",
    "externalId": "ERP-SUB-1001"
  }'

Using JavaScript (fetch):

const response = await fetch('https://sandbox.custodia-tech.com/md/api/Subsidiaries', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme US East',
    code: 'US-EAST',
    currency: 'USD',
    externalId: 'ERP-SUB-1001'
  })
});

const subsidiary = await response.json();

Response

{
  "id": "c4d5e6f7-a8b9-0123-cdef-456789012345",
  "name": "Acme US East",
  "code": "US-EAST",
  "currency": "USD",
  "companyId": "your-company-id",
  "status": "active",
  "externalId": "ERP-SUB-1001",
  "officeLocationId": null
}

Save the returned id: it is the subsidiaryId used when assigning users and when scoping cost centers, teams, budgets, and related records.

Get Subsidiary by ID

Retrieves a single subsidiary by its ID. Use the id returned from create subsidiary.

Path Parameters

Example Request

Using cURL:

curl -X GET https://sandbox.custodia-tech.com/md/api/Subsidiaries/c4d5e6f7-a8b9-0123-cdef-456789012345 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID"

Using JavaScript (fetch):

const subsidiaryId = 'c4d5e6f7-a8b9-0123-cdef-456789012345';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Subsidiaries/${subsidiaryId}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const subsidiary = await response.json();

Response

{
  "id": "c4d5e6f7-a8b9-0123-cdef-456789012345",
  "name": "Acme US East",
  "code": "US-EAST",
  "currency": "USD",
  "companyId": "your-company-id",
  "status": "active",
  "externalId": "ERP-SUB-1001",
  "officeLocationId": null
}

List Subsidiaries

Retrieves subsidiaries for your company. Use the filter query parameter with a where clause to match by code, status, name, and other fields. Results are scoped to the company associated with your access token: do not include companyId in the filter.

Query Parameters

Pass the filter as a URL-encoded JSON object in the filter query parameter.

Filter Options

The filter object supports the following properties:

Where Clause Examples

Common filter conditions for the where clause:

Example Requests

Find an active subsidiary by code:

Using cURL:

curl -G https://sandbox.custodia-tech.com/md/api/Subsidiaries \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  --data-urlencode 'filter={"where":{"code":"US-EAST","status":"active"}}'

Using JavaScript (fetch):

const filter = {
  where: {
    code: 'US-EAST',
    status: 'active'
  },
  order: 'name ASC'
};

const filterParam = encodeURIComponent(JSON.stringify(filter));
const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Subsidiaries?filter=${filterParam}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const subsidiaries = await response.json();

List active subsidiaries (paginated):

Using JavaScript (fetch):

const filter = {
  where: { status: 'active' },
  order: 'code ASC',
  limit: 25,
  skip: 0
};

const filterParam = encodeURIComponent(JSON.stringify(filter));
const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Subsidiaries?filter=${filterParam}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const subsidiaries = await response.json();

Response

[
  {
    "id": "c4d5e6f7-a8b9-0123-cdef-456789012345",
    "name": "Acme US East",
    "code": "US-EAST",
    "currency": "USD",
    "companyId": "your-company-id",
    "status": "active",
    "externalId": "ERP-SUB-1001",
    "officeLocationId": null
  }
]

Returns an array of subsidiary objects. An empty array means no rows matched the filter.

Update Subsidiary

Partially updates an existing subsidiary. Only include fields you want to change. Do not send companyId or id: they cannot be changed via this endpoint.

Path Parameters

Request Body

All fields are optional on update. Send only the properties you want to change:

Example Request

Update the display name and currency:

Using cURL:

curl -X PATCH https://sandbox.custodia-tech.com/md/api/Subsidiaries/c4d5e6f7-a8b9-0123-cdef-456789012345 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme United States East",
    "currency": "USD"
  }'

Using JavaScript (fetch):

const subsidiaryId = 'c4d5e6f7-a8b9-0123-cdef-456789012345';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Subsidiaries/${subsidiaryId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme United States East',
    currency: 'USD'
  })
});

const subsidiary = await response.json();

Response

{
  "id": "c4d5e6f7-a8b9-0123-cdef-456789012345",
  "name": "Acme United States East",
  "code": "US-EAST",
  "currency": "USD",
  "companyId": "your-company-id",
  "status": "active",
  "externalId": "ERP-SUB-1001",
  "officeLocationId": null
}

Assign Employees

Employees are not added to a subsidiary through a dedicated membership endpoint. Assignment is done by updating the user (AppUser) record: set the user’s subsidiaryId field to the subsidiary UUID.

Path Parameters

Request Body

Example Request

Using cURL:

curl -X PATCH https://sandbox.custodia-tech.com/md/api/User/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "subsidiaryId": "c4d5e6f7-a8b9-0123-cdef-456789012345"
  }'

Using JavaScript (fetch):

const userId = '550e8400-e29b-41d4-a716-446655440000';
const subsidiaryId = 'c4d5e6f7-a8b9-0123-cdef-456789012345';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/User/${userId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subsidiaryId
  })
});

const user = await response.json();

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "firstname": "Jane",
  "lastname": "Doe",
  "email": "jane.doe@acme.com",
  "companyId": "your-company-id",
  "subsidiaryId": "c4d5e6f7-a8b9-0123-cdef-456789012345",
  "active": true
}

Subsidiary Fields

Field reference for create, update, and list responses:

Error Responses

All endpoints may return the following error responses:

Related documentation

• Companies: parent tenant for subsidiaries
• Update user: set subsidiaryId on the employee record
• Cost center: optional subsidiaryId scope on cost centers
• Org teams: optional subsidiaryId scope on teams
• Authentication: obtain access tokens
• Glossary: platform terminology