Cost Center

Overview

Cost centers are organizational units used to tag and route spend: for example by department, project, or expense category. Create cost centers before associating them with spend permissions (costCenterIds) or budget mappings (costCenterId).

Typical flow:

1. Create a cost center: POST /md/api/CostCenters
2. Update a cost center: PATCH /md/api/CostCenters/{costCenterId}
3. Retrieve by ID: GET /md/api/CostCenters/{costCenterId}
4. Assign a user to a cost center: POST /md/api/TeamUserMappings with teamType: "CostCenter"
5. Update a mapping: PATCH /md/api/TeamUserMappings/{teamUserMappingId}
6. Remove a user from a cost center: DELETE /md/api/TeamUserMappings/{teamUserMappingId}
7. Reference the cost center: use the returned id in spend permissions, budget mappings, or expense updates

Create Cost Center

Creates a new cost center for the company associated with your access token. The platform sets companyId, id, active, and status automatically.

Request Body: mandatory fields

Optional fields

Example Request

Using cURL:

curl -X POST https://sandbox.custodia-tech.com/md/api/CostCenters \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Marketing department travel expenses",
    "code": "MKT-001",
    "name": "Marketing Travel Expenditure"
  }'

Using JavaScript (fetch):

const response = await fetch('https://sandbox.custodia-tech.com/md/api/CostCenters', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    description: 'Marketing department travel expenses',
    code: 'MKT-001',
    name: 'Marketing Travel Expenditure'
  })
});

const costCenter = await response.json();

Response

{
  "description": "Marketing department travel expenses",
  "code": "MKT-001",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Marketing Travel Expenditure",
  "active": true,
  "companyId": "your-company-id",
  "status": "active"
}

Update Cost Center

Partially updates an existing cost center. 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 description:

Using cURL:

curl -X PATCH https://sandbox.custodia-tech.com/md/api/CostCenters/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Travel and Events",
    "description": "Travel and event expenses for the marketing department"
  }'

Using JavaScript (fetch):

const costCenterId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/CostCenters/${costCenterId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Marketing Travel and Events',
    description: 'Travel and event expenses for the marketing department'
  })
});

const costCenter = await response.json();

Response

{
  "description": "Travel and event expenses for the marketing department",
  "code": "MKT-001",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Marketing Travel and Events",
  "active": true,
  "companyId": "your-company-id",
  "status": "active"
}

Get Cost Center by ID

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

Path Parameters

Example Request

Using cURL:

curl -X GET https://sandbox.custodia-tech.com/md/api/CostCenters/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID"

Using JavaScript (fetch):

const costCenterId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

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

const costCenter = await response.json();

Response

{
  "description": "Marketing department travel expenses",
  "code": "MKT-001",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Marketing Travel Expenditure",
  "active": true,
  "companyId": "your-company-id",
  "leaderId": null,
  "subsidiaryId": null,
  "externalId": null,
  "status": "active",
  "deletedOn": null,
  "deletedBy": null,
  "uiLabel": "MKT-001 Marketing Travel Expenditure"
}

The uiLabel field is a calculated display label combining code and name. It is returned on read but is not accepted on create.

Create Cost Center User Mapping

Assigns a user to a cost center by creating a cost center user mapping: the join record that links a user (memberId) to a cost center. Users are not added to cost centers by updating the cost center or user record directly.

Prerequisites: the cost center and user must already exist. Create users via Create User and cost centers via create cost center before calling this endpoint.

Request Body: mandatory fields

Optional fields

Example Request

Using cURL:

curl -X POST https://sandbox.custodia-tech.com/md/api/TeamUserMappings \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "teamType": "CostCenter",
    "memberId": "c8d4e2f1-6a3b-4c7d-9e01-2847361950ab"
  }'

Using JavaScript (fetch):

const response = await fetch('https://sandbox.custodia-tech.com/md/api/TeamUserMappings', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    teamId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    teamType: 'CostCenter',
    memberId: 'c8d4e2f1-6a3b-4c7d-9e01-2847361950ab'
  })
});

const mapping = await response.json();

Response

{
  "id": "d9e5f3a2-7b4c-4d8e-a012-3958472610bc",
  "teamId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "teamType": "CostCenter",
  "memberId": "c8d4e2f1-6a3b-4c7d-9e01-2847361950ab",
  "order": 0,
  "companyId": "your-company-id"
}

Save the returned mapping id to update or remove the assignment later.

Update Cost Center User Mapping

Partially updates an existing cost center user mapping. 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:

To move a user to a different cost center, you can update teamId or delete the existing mapping and create a new one.

Example Request

Change the sort order for a user with multiple cost center memberships:

Using cURL:

curl -X PATCH https://sandbox.custodia-tech.com/md/api/TeamUserMappings/d9e5f3a2-7b4c-4d8e-a012-3958472610bc \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "order": 1
  }'

Using JavaScript (fetch):

const teamUserMappingId = 'd9e5f3a2-7b4c-4d8e-a012-3958472610bc';

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

const mapping = await response.json();

Response

{
  "id": "d9e5f3a2-7b4c-4d8e-a012-3958472610bc",
  "teamId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "teamType": "CostCenter",
  "memberId": "c8d4e2f1-6a3b-4c7d-9e01-2847361950ab",
  "order": 1,
  "companyId": "your-company-id"
}

Delete Cost Center User Mapping

Removes a user from a cost center by deleting the cost center user mapping. Use the mapping id returned from create cost center user mapping. This soft-deletes the mapping record: the user and cost center are not deleted.

Path Parameters

Example Request

Using cURL:

curl -X DELETE https://sandbox.custodia-tech.com/md/api/TeamUserMappings/d9e5f3a2-7b4c-4d8e-a012-3958472610bc \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID"

Using JavaScript (fetch):

const teamUserMappingId = 'd9e5f3a2-7b4c-4d8e-a012-3958472610bc';

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

const result = await response.json();

Response

{
  "count": 1
}

A count of 1 confirms one mapping was removed. A count of 0 means no matching mapping was found (already deleted or invalid ID).

Cost Center Fields

Summary of all fields returned by the API:

Error Responses

All endpoints may return the following error responses:

Related documentation

• Spend permission: associate cost centers via costCenterIds
• Budget mapping: route spend by costCenterId
• Org team user mapping: same TeamUserMappings API with teamType: "OrgTeam"
• Create user: users to assign via memberId
• Authentication: obtain access tokens
• Glossary: platform terminology