Chart of Accounts

Overview

The chart of accounts defines the general ledger (GL) codes your program uses to classify spend. Each line has an accounting code and a display account name. Budgets reference these codes via the category field: see Create budget.

Typical flow:

1. Import or create GL accounts: POST /md/api/LedgerAccountTypes
2. Update a GL account: PATCH /md/api/LedgerAccountTypes/{id}
3. Find GL accounts: GET /md/api/LedgerAccountTypes with a filter.where clause
4. Reference the code on budgets: set category to the GL code when creating a budget
5. Map expenses: transactions and expenses resolve to the appropriate GL line based on budget and mapping rules

Create Chart of Account

Creates a new GL account line for the company associated with your access token. The platform sets id, companyId, locale, and currency (when omitted) automatically.

Request Body: mandatory fields

Optional fields

Example Request

Using cURL:

curl -X POST https://sandbox.custodia-tech.com/md/api/LedgerAccountTypes \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "6204",
    "default": false,
    "account": "Field Equipment",
    "status": "active",
    "description": "Tools and gear issued to employees in the field",
    "externalId": "SAP-472891"
  }'

Using JavaScript (fetch):

const response = await fetch('https://sandbox.custodia-tech.com/md/api/LedgerAccountTypes', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: '6204',
    default: false,
    account: 'Field Equipment',
    status: 'active',
    description: 'Tools and gear issued to employees in the field',
    externalId: 'SAP-472891'
  })
});

const glAccount = await response.json();

Response

{
  "id": "b7c2e891-4d03-4f12-8a6f-3e5d91c04b28",
  "code": "6204",
  "default": false,
  "account": "Field Equipment",
  "locale": "en-US",
  "status": "active",
  "companyId": "2a8f6c14-9e7b-4d32-a816-5b3f0d8e72c1",
  "currency": "USD",
  "description": "Tools and gear issued to employees in the field",
  "externalId": "SAP-472891"
}

Update Chart of Account

Partially updates an existing GL account line. Only include fields you want to change. Do not send companyId, locale, 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 description:

Using cURL:

curl -X PATCH https://sandbox.custodia-tech.com/md/api/LedgerAccountTypes/b7c2e891-4d03-4f12-8a6f-3e5d91c04b28 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "Field Equipment and Supplies",
    "description": "Hand tools, PPE, and consumable supplies for field staff"
  }'

Using JavaScript (fetch):

const glAccountId = 'b7c2e891-4d03-4f12-8a6f-3e5d91c04b28';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/LedgerAccountTypes/${glAccountId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    account: 'Field Equipment and Supplies',
    description: 'Hand tools, PPE, and consumable supplies for field staff'
  })
});

const glAccount = await response.json();

Response

{
  "id": "b7c2e891-4d03-4f12-8a6f-3e5d91c04b28",
  "code": "6204",
  "default": false,
  "account": "Field Equipment and Supplies",
  "locale": "en-US",
  "status": "active",
  "companyId": "2a8f6c14-9e7b-4d32-a816-5b3f0d8e72c1",
  "currency": "USD",
  "description": "Hand tools, PPE, and consumable supplies for field staff",
  "externalId": "SAP-472891"
}

Find GL Accounts

Retrieves GL account lines 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 GL account by code:

Using cURL:

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

Using JavaScript (fetch):

const filter = {
  where: {
    code: '6204',
    status: 'active'
  },
  order: 'account ASC'
};

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

const glAccounts = await response.json();

Search active GL accounts by display name:

Using JavaScript (fetch):

const filter = {
  where: {
    status: 'active',
    account: { like: '%Equipment%', options: 'i' }
  },
  limit: 25
};

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

const glAccounts = await response.json();

Response

[
  {
    "id": "b7c2e891-4d03-4f12-8a6f-3e5d91c04b28",
    "code": "6204",
    "default": false,
    "account": "Field Equipment and Supplies",
    "locale": "en-US",
    "status": "active",
    "companyId": "2a8f6c14-9e7b-4d32-a816-5b3f0d8e72c1",
    "currency": "USD",
    "description": "Hand tools, PPE, and consumable supplies for field staff",
    "externalId": "SAP-472891"
  }
]

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

Chart of Account Fields

Field reference for create, update, and find responses:

Error Responses

These endpoints may return the following error responses:

Related documentation

• Create budget: reference a GL code via category
• Glossary: category (budget GL code)
• Authentication: obtain access tokens