Spend Templates

Overview

A spend template defines a category of spend: for example travel, meals, or field equipment. In the API it is the AllocatableType model. Each template has a stable code (activity type key), behavior flags (such as supportsMerchants or supportsSingleCreation), and defaults used when users or integrations create spend permissions.

Typical flow:

1. Get an available activity type code (recommended): POST /md/api/AllocatableTypes/availableCode
2. Create a spend template: POST /md/api/AllocatableTypes
3. Set the display name: PUT /md/api/TenantDictionaries (see Set display name)
4. Link expense categories: POST /md/api/ActivityExpenseTypeMappings (see Link expense categories)
5. Configure optional behavior: update flags via PATCH /md/api/AllocatableTypes/{id} (see Optional fields)
6. Create spend permissions from the template: POST /md/api/AllocatableTypes/{id}/createActivity (see Create spend permission)

Get Available Activity Type Code

Returns the next unused ActivityType dictionary code your company can use when creating a custom spend template (for example Other/Activity03). Call this before create spend template if you need the platform to assign a code slot rather than supplying your own.

Request Body: mandatory fields

Send the body as application/x-www-form-urlencoded (form fields), not JSON.

Example Request

Using cURL:

curl --location 'https://sandbox.custodia-tech.com/md/api/AllocatableTypes/availableCode' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'x-appid: YOUR_CLIENT_ID' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'companyId=2a8f6c14-9e7b-4d32-a816-5b3f0d8e72c1'

Using JavaScript (fetch):

const body = new URLSearchParams({
  companyId: '2a8f6c14-9e7b-4d32-a816-5b3f0d8e72c1'
});

const response = await fetch('https://sandbox.custodia-tech.com/md/api/AllocatableTypes/availableCode', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: body.toString()
});

const code = await response.json();

Response

"Other/Activity03"

Returns a JSON string: the activity type code to use in your create request when calling POST /md/api/AllocatableTypes.

Create Spend Template

Creates a new spend template. The platform sets id and createdOn automatically. After create, set the display name and expense categories in separate calls.

Request Body: mandatory fields

Optional fields (create or PATCH)

Send only the flags you need at create time; configure the rest via PATCH after the template exists. See Support config reference for nested object shapes.

Support config reference

Most supports* fields use a shared config shape. Send them as nested JSON objects on create or PATCH.

ActivityPropertySupportConfig (base)

Extended config types

JSON examples

Send config objects as nested JSON on POST or PATCH /md/api/AllocatableTypes. Omit fields you do not need.

ActivityPropertySupportConfig: used by supportsReceiptRequired, supportsEditable, supportsATM, supportsOutOfPocket, supportsLockedByDefault, supportsAutoLockOnBufferUsage, supportsRecurringPaymentAllowed, supportsAllocationSplit, supportsAllocationMerge, supportsHideLimits, supportsHideDailyLimit, and supportsHideTransactionLimit:

"supportsReceiptRequired": {
  "supported": true,
  "editable": true,
  "enabledByDefault": true,
  "visibleAtCreation": true
}

MerchantSupportConfig: supportsMerchants:

"supportsMerchants": {
  "supported": true,
  "editable": true,
  "defaultMerchants": [
    {
      "type": "Merchant",
      "value": "5812",
      "name": "Restaurants"
    }
  ]
}

RecurringSupportConfig: supportsRecurring:

"supportsRecurring": {
  "supported": true,
  "editable": true,
  "defaultRecurringType": "monthly"
}

BoundToCardSupportConfig: supportsBoundToCard:

"supportsBoundToCard": {
  "supported": true,
  "required": false
}

GroupPaySupportConfig: supportsGroupPay:

"supportsGroupPay": {
  "canReceive": true,
  "canSend": true
}

TransactionsRestrictionsSupportConfig: supportsTransactionsRestrictions:

"supportsTransactionsRestrictions": {
  "supported": true,
  "supportsTxCountLimit": true,
  "defaultTxCountLimit": 10,
  "canEditTxCountLimit": true,
  "txCountLimitVisible": true
}

AutoExtendSupportConfig: supportsAutoExtend:

"supportsAutoExtend": {
  "supported": true,
  "editable": true,
  "enabledByDefault": false,
  "visibleAtCreation": true,
  "autoExtendUntilAmountPercentage": 80,
  "extendByDays": 7
}

ActivityForceValuesConfig: supportsActiveForCurrencies:

"supportsActiveForCurrencies": {
  "supported": true,
  "editable": false,
  "enabledByDefault": true,
  "visibleAtCreation": false,
  "value": ["USD", "EUR"]
}

ActivityForceValuesConfig: supportsActiveForCountryCodes:

"supportsActiveForCountryCodes": {
  "supported": true,
  "editable": false,
  "value": ["US", "CA"]
}

ActivityLimitConfig: supportsDailyLimit, supportsTransactionLimit, or supportsDailyCountLimit:

"supportsDailyLimit": {
  "supported": true,
  "editable": true,
  "visibleAtCreation": true,
  "defaultValue": 500
}

BasicActivityPropertySupportConfig: defaultAmount and defaultCurrency:

"defaultAmount": {
  "editable": true,
  "defaultValue": 1000
},
"defaultCurrency": {
  "editable": false,
  "defaultValue": "USD"
}

Combined PATCH example: update several configs on an existing template:

curl -X PATCH https://sandbox.custodia-tech.com/md/api/AllocatableTypes/668aa37d-6243-46d0-9373-1c859435f89f \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "supportsMerchants": {
      "supported": true,
      "editable": true,
      "defaultMerchants": []
    },
    "supportsReceiptRequired": {
      "supported": true,
      "editable": true,
      "enabledByDefault": true,
      "visibleAtCreation": true
    },
    "defaultCurrency": {
      "editable": false,
      "defaultValue": "USD"
    },
    "supportsDailyLimit": {
      "supported": true,
      "editable": true,
      "visibleAtCreation": true,
      "defaultValue": 500
    }
  }'

Example Request

Using cURL:

curl -X POST https://sandbox.custodia-tech.com/md/api/AllocatableTypes \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "Other/Activity025",
    "companyId": "7332ad13-d460-457d-b73f-0e1681f060fc",
    "type": "spend",
    "creatableByUser": true,
    "supportsSingleCreation": true
  }'

Using JavaScript (fetch):

const response = await fetch('https://sandbox.custodia-tech.com/md/api/AllocatableTypes', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: 'Other/Activity025',
    companyId: '7332ad13-d460-457d-b73f-0e1681f060fc',
    type: 'spend',
    creatableByUser: true,
    supportsSingleCreation: true
  })
});

const activityTemplate = await response.json();

Response

{
  "id": "668aa37d-6243-46d0-9373-1c859435f89f",
  "companyId": "7332ad13-d460-457d-b73f-0e1681f060fc",
  "partnerId": null,
  "code": "Other/Activity025",
  "createdOn": "2026-07-08T01:40:32.204Z",
  "enabled": true,
  "type": "spend",
  "creatableByUser": true,
  "supportsBulkCreation": false,
  "bulkOnly": false,
  "supportsSingleCreation": true,
  "canSelfCreate": true,
  "hasPartialAuth": false,
  "private": false,
  "skipAdvancedSettings": "false",
  "status": "active",
  "version": 0
}

Save the returned id: it is the AllocatableType UUID used in POST /md/api/AllocatableTypes/{id}/createActivity. The code is the activity type key referenced elsewhere (for example budget mappings, expense category links, or associatedType).

Set Display Name

The user-facing template name (for example Travel Meals) is stored in TenantDictionary, not on AllocatableType itself. Upsert a dictionary entry after creating the template.

Request Body: mandatory fields

Example Request

curl -X PUT https://sandbox.custodia-tech.com/md/api/TenantDictionaries \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "Other/Activity025",
    "category": "ActivityType",
    "label": "Travel Meals",
    "companyId": "7332ad13-d460-457d-b73f-0e1681f060fc",
    "locale": "en-US",
    "scope": "default",
    "status": "active"
  }'

Link Expense Categories

Expense categories allowed for a template are linked via ActivityExpenseTypeMapping records: one per expense type. Call this after create to allow transactions in specific expense categories (for example Meals) or all categories (*).

Request Body: mandatory fields

Optional fields

Use expenseType: "*" to allow any expense category in a single mapping. To restrict to specific categories, create one mapping per expense type (for example Meals or Travel).

Example Request

curl -X POST https://sandbox.custodia-tech.com/md/api/ActivityExpenseTypeMappings \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "activityType": "Other/Activity025",
    "expenseType": "*",
    "companyId": "7332ad13-d460-457d-b73f-0e1681f060fc",
    "status": "active"
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "activityType": "Other/Activity025",
  "expenseType": "*",
  "companyId": "7332ad13-d460-457d-b73f-0e1681f060fc",
  "status": "active",
  "createdOn": "2026-07-08T01:41:00.000Z"
}

Complete initial setup example

Typical sequence after availableCode returns Other/Activity025:

1. POST /md/api/AllocatableTypes: create template with code and companyId
2. PUT /md/api/TenantDictionaries: set label to Travel Meals
3. POST /md/api/ActivityExpenseTypeMappings: link expenseType: "*" to allow any expense category

Spend Template Fields (summary)

Full optional field and support config definitions are in Optional fields and Support config reference.

Error Responses

Related documentation

• Spend permission: create permissions from this template’s id
• Glossary: Spend template
• Budget mapping: route spend by activity type
• Authentication