Glossary

Definitions for terms used across the partner API documentation

Overview

This page defines technical terms, API model names, and field names used in the partner guides. Wording can differ by integration track (for example payment intent in agentic payments versus spend permission in white label), but many terms refer to the same Custodia objects underneath. Entries below are in alphabetical order.

Activity (allocatable)

An activity is the business context for a spend event (for example a restaurant meal or trip). In the API this is modeled as an allocatable record (types such as Restaurant, Trip, or Other depending on program configuration). Creating an activity via createActivity also drives creation of the linked allocation; for standard activities the activity and allocation share the same id.

Activity expense type mapping

An activity expense type mapping (ActivityExpenseTypeMapping) links a spend template to the expense categories allowed for that template. Create one record per expense type via POST /md/api/ActivityExpenseTypeMappings with activityType (the template code), expenseType (an ExpenseType dictionary code such as Meals), and companyId. Use expenseType: "*" to allow any expense category.

Related: Link expense categories.

Activity request

An activity request (API model Request) is the approval workflow record returned immediately from createActivity. It is not the full allocation document. It includes status (for example new), workflowId, associatedId, associatedType, and budget references while approvers process the activity.

Related: Create spend permission (response section).

Spend template

Partner documentation term for an AllocatableType: a company-level template that defines a category of spend (for example travel meals or field equipment). Configure spend templates before creating spend permissions via createActivity. Setup typically includes reserving a type code, creating the AllocatableType, setting a display name in TenantDictionary, and linking expense categories.

ActivityType (dictionary code)

ActivityType is the tenant dictionary category for activity type keys. A spend template code must be a valid ActivityType value (for example Other/Activity025), not a free-form name. Call POST /md/api/AllocatableTypes/availableCode to obtain an unused code slot. The user-facing name (for example Travel Meals) is stored separately in TenantDictionary with category: "ActivityType".

AllocatableType

An AllocatableType (also called a spend template) is a company-level template that defines a category of activity (for example travel, meals, or restaurant). Each type has a stable code (ActivityType dictionary key, such as Other/Activity025), configuration flags (such as supportsMerchants), and defaults for how activities of that category behave.

The {id} in POST /md/api/AllocatableTypes/{id}/createActivity is the AllocatableType UUID, not the same as code or associatedType.

Allocation

An allocation is the budgeted spending record exposed at /md/api/Allocations. It holds the amount and currency available to spend, the activity date range (activityStart / activityEnd), status (for example new, active, locked), the card owner (ownerId), optional merchant allowlists, and other limits used when authorizing card transactions. When linked to a company budget, a budget allocation ties the permission to that budget line.

associatedId

associatedId on an activity request identifies the allocatable/activity the workflow is for. For standard activities you can use this value as {allocationId} on Allocation endpoints (for example GET /md/api/Allocations/{allocationId}, POST .../lock, POST .../controlledSave) once the spend permission or payment intent exists.

associatedType

associatedType on an activity request is the activity type key (for example Other/Activity025). It matches the AllocatableType code for that category. It is not the AllocatableType UUID used in the createActivity URL path.

Available balance (budget)

Available balance is the amount still free to allocate on a budget. Retrieve it with GET /md/api/Budgets/{budgetId}/available; the response is a single number equal to budget.amount − taken. For a field-by-field breakdown of reserved, used, and taken, use POST /md/api/Budgets/calcMetrics.

availableCode

availableCode is POST /md/api/AllocatableTypes/availableCode. It returns the next unused ActivityType dictionary code your company can use when creating a custom spend template (for example Other/Activity025). Send companyId as form-urlencoded body. Use the returned string as the template code on create.

Budget

A budget (/md/api/Budgets) is the company spending pool for a time period. It has an amount, currency, granularity (annual, quarterly, monthly, or custom), fiscalYear, and a category GL code. Spend permissions draw from a budget through budget allocations; budget mappings route spend to the correct budget by scope.

Related: Budget, Spend permission.

Budget allocation

A budget allocation links a spend permission (allocation) to a specific budget line. It tracks how much of the budget is reserved and used for that permission. Budget utilization metrics (reserved, used, taken) aggregate data from budget allocations attached to the budget.

Budget mapping

A budget mapping (/md/api/BudgetMappings) is a routing rule that matches spend context (user, cost center, activity type, expense type, and other scope fields) to a budget for a given period. Scope fields use * as a wildcard. Create at least one mapping after creating a budget so spend can be routed to it.

Related: Create budget mapping.

calcMetrics

calcMetrics is POST /md/api/Budgets/calcMetrics. Pass a query array of budget ids to receive utilization metrics per budget: reserved, used, taken, expired allocation totals, sub-budget rollups, and last expense timestamp. Use it when you need detail beyond the single number from /available.

Related: Calculate budget metrics.

cardIssuerId

cardIssuerId identifies the card issuer/network context for your program. It is required in the filter.where object when calling GET /md/api/MasterMerchants/search or GET /md/api/Merchants. Ask your Custodia support rep for the correct value for sandbox and production; do not reuse another program’s issuer id.

Card product

A card product defines the card program template used when ordering a card (virtual or physical, vendor, limits, and related settings). Retrieved via /md/api/CardProduct and referenced as cardProductId when ordering a card for a user.

Related: Card products, Card issuance.

category (budget GL code)

On a budget, category is the GL account code (general ledger line) for that budget line. Import or create codes via the chart of accounts (LedgerAccountTypes); if none exist, the platform default 1001 may apply. Do not confuse this with merchant category (MCC) on merchant search results.

Chart of accounts

The chart of accounts is the set of general ledger (GL) account lines for a company, modeled as LedgerAccountType at /md/api/LedgerAccountTypes. Each line has a stable accounting code and display account name. Budgets reference GL codes through the budget category field.

Client credentials

Client credentials is the OAuth2 grant type used for partner server-to-server access. You exchange client_id and client_secret for a bearer access token via POST /md/api/Application/authenticate, then pass the token in the Authorization header on subsequent requests.

commonId

commonId is the stable master merchant identifier returned from merchant search. When building a merchant allowlist, it is typically stored in merchants[].value and merchants[].extra.commonId with type "MasterMerchant".

Company

A company is the top-level tenant in Custodia. Every user, card, budget, and activity belongs to a company. Create a company via POST /md/api/Companies; the returned id is the companyId used across partner APIs. New companies start in new status until activated by Custodia operations.

Related: Create company, companyId.

companyId

companyId is the tenant identifier (company UUID) in Custodia. Many records and filters are scoped by company. For most write APIs under an existing company context (budgets, cost centers, users, spend permissions), the company is resolved from your access token: do not send companyId in the body. Some provisioning APIs require companyId explicitly, including POST /md/api/Companies (target company), POST /md/api/AllocatableTypes, POST /md/api/AllocatableTypes/availableCode, PUT /md/api/TenantDictionaries, POST /md/api/ActivityExpenseTypeMappings, and POST /md/api/User.

Related: Companies.

controlledSave

controlledSave is POST /md/api/Allocations/controlledSave. It applies a partial update to an existing allocation (activity), such as merchant allowlists, dates, or purpose, subject to program rules and permissions. The body includes allocationId and an allocation object with only the fields you want to change.

Related: Merchant restriction.

Cost center

A cost center (/md/api/CostCenters) is an organizational unit used to tag and route spend (for example department, project, or location). Reference a cost center id on spend permissions (costCenterIds) or budget mappings (costCenterId). Assign users to cost centers via TeamUserMappings with teamType: "CostCenter".

createActivity

createActivity is the remote method POST /md/api/AllocatableTypes/{id}/createActivity. It creates a new activity (allocatable), estimates budget impact, and submits an activity request for approval. Required body fields typically include amount, start, end, and ownerId.

dns (company email domain)

On a company, dns holds corporate email domain(s) allowed for user signup and identity. Format is semicolon-delimited, for example ;acme.com;subsidiary.com;. Set on company create or update via POST /md/api/Companies or PATCH /md/api/Companies/{id}.

Related: Create company.

Expense type

An expense type is a transaction or spend classification from the ExpenseType tenant dictionary (for example Meals, Travel, or * for any). Spend templates link to allowed expense types through activity expense type mappings. Expense types also appear in budget mapping scope fields.

externalId

externalId is an optional partner or ERP reference identifier stored on records such as companies, users, or cost centers. Use it to correlate Custodia objects with your own systems. It is not the Custodia UUID (id).

filter.where

filter.where is the LoopBack query object used on GET list endpoints. Pass it as a URL-encoded JSON filter parameter, for example filter={"where":{"code":"1000"}}. Used on GET /md/api/LedgerAccountTypes, GET /md/api/Subsidiaries, GET /md/api/MerchantGroups, GET /md/api/Allocations, and other find APIs.

granularity (budget)

Granularity on a budget defines its time period: annual, quarterly, monthly, or custom. It works with fiscalYear (and quarter or month when applicable) to set the budget’s start and end dates. Budget mappings should align with the same granularity and period as the budget they route to.

Related: Create budget.

Master merchant

A master merchant is a normalized merchant identity in Custodia’s network-wide catalog (MasterMerchants). It groups issuer-specific merchant records under a shared commonId and display name so partners can restrict spend or match transactions consistently across the card network.

Related: Master merchant search.

Merchant

A merchant is an issuer-specific merchant record in /md/api/Merchants. It includes merchantId, MCC, vendor metadata, and optional links to a master merchant (masterId, commonId). Use merchant search when you need ids for transaction simulation or issuer-scoped lookups; use master merchant search for network-wide allowlists.

Related: Merchant search.

Merchant group

A merchant group (/md/api/MerchantGroups) is a tenant-defined collection of merchants your program creates and manages. It has a display name, stable code, and optional description. Merchants are linked through merchant group members. Reference the group id on spend permission allowlists with keyword type MerchantGroup.

MerchantGroup (keyword type)

MerchantGroup is a merchants[] entry type on a spend permission allowlist. Set value to the merchant group id from POST /md/api/MerchantGroups. At authorization, Custodia checks whether the transaction merchant belongs to that group.

MasterMerchant (keyword type)

MasterMerchant is a merchants[] entry type meaning the allowlist item refers to a catalog master merchant (identified by value / commonId and optional extra.id). Other types (such as Merchant or MerchantGroup) may be available depending on your program.

Merchant restriction

A merchant restriction (merchant allowlist) limits an activity so card spend is only eligible at listed merchants. You set it by posting allocation.merchants via controlledSave. The AllocatableType must have supportsMerchants enabled.

Related: Merchant restriction.

ownerId

ownerId is the user id of the cardholder who owns the activity or allocation. It appears on allocations, createActivity requests, and user/card APIs. Spend is evaluated in the context of that user’s cards and permissions.

Related: Users.

Org team

An org team (/md/api/OrgTeams) represents an organizational hierarchy unit: for example a department, region, or business unit. Users belong to org teams through team user mappings (teamType: "OrgTeam"). Org team id values can appear in budget mapping scope fields.

Related: Org team, Team user mapping.

Payment intent

Partner documentation term (agentic payments track) for an allocation. A payment intent defines how much an agent can spend, when, and under which rules. You create it via createActivity and manage it through the Allocations API once approved.

Real-time decisioning

Real-time decisioning is a live authorization flow where Custodia calls an external provider with a normalized transaction payload and expects an approve/decline response within decisionDeadlineMs. If the deadline is missed, an asynchronous outcome webhook may be used. See the beta integration guide for request shape, timeout handling, and webhook contract.

Related: Real-time decisioning.

Scope

A scope at authentication is a permission string in your token request (for example DEFAULT or feature scopes such as f:Card/OrderCards). The token only allows operations covered by the scopes granted to your application. Do not confuse this with budget mapping scope fields (such as costCenterId or activityType), which route spend to budgets.

Spend permission

Partner documentation term (white label track) for an allocation. A spend permission defines spending parameters and budgets for a cardholder or program. Same underlying API objects as a payment intent; only the guide naming differs.

Related: Spend permission.

Subsidiary

A subsidiary (/md/api/Subsidiaries) is a legal or operational entity under a company. Use subsidiaries to scope spend, budgets, cost centers, and teams when a parent company has multiple entities. Assign employees by setting subsidiaryId on the user record (PATCH /md/api/User/{id}), not via TeamUserMappings.

Team user mapping

A team user mapping (TeamUserMapping at /md/api/TeamUserMappings) links a user (memberId) to a team (teamId). Set teamType to OrgTeam for org team membership or CostCenter for cost center assignment. Users are not added to teams by updating the team or user record directly.

TenantDictionary

TenantDictionary stores localized labels for dictionary categories such as ActivityType and ExpenseType. The user-facing name of a spend template is set via PUT /md/api/TenantDictionaries with category: "ActivityType", code matching the template, and label as the display name. This is separate from the AllocatableType record itself.

Related: Set display name.

Transaction

In partner docs, a transaction is a payment event on a card (API model Expense under /md/api/Expenses). Transactions are read-only: they are created when payments are processed against an active allocation. They include amount, merchant, status, and a reference to the payment intent / allocation.

Related: Transactions.

Transaction simulation

Transaction simulation is a sandbox-only flow for testing card authorization and posting behavior through POST /md/api/TransactionSimulations/execute. It lets partners test a card, merchant, amount, and activity rules without live card spend.

Related: Transaction simulation.

x-appid

x-appid is a required HTTP header on partner API calls. Set it to your application client id (the same value used as client_id when authenticating). Custodia uses it with the bearer token to identify your integration.