ITSM

Underpinning Contracts

Track external vendor and supplier contracts that back an internal SLA, including vendor response/resolution targets, scope, and renewal reminders.

What is an Underpinning Contract?

In ITIL terms, an underpinning contract (UC)is an agreement with an external vendor or supplier that supports ("underpins") an SLA offered to internal customers. Where an OLA(Operational Level Agreement) captures a commitment between internal teams, a UC captures the equivalent commitment from a third party — for example, a hardware vendor's 4-hour on-site response, or a SaaS provider's contracted resolution window. FlowOS stores UCs as their own record type and lets you link one or more OLAs to the contract that backs them.

Model Fields

Field	Type	Required	Default	Description
number	string	required	auto (UC-NNNN)	Human-readable identifier, generated on create.
name	string	required	—	Display name for the contract.
vendorName	string	required	—	Name of the external vendor or supplier.
vendorContact	string	optional	—	Named contact at the vendor.
vendorEmail	string (email)	optional	—	Vendor contact email address. Validated as an email on write.
contractNumber	string	optional	—	The vendor’s own contract/reference number.
startDate	date	required	—	Contract start date. Must be before endDate.
endDate	date	required	—	Contract end date. Must be after startDate.
responseTargetHours	number	optional	—	Vendor-committed response time, in hours.
resolutionTargetHours	number	optional	—	Vendor-committed resolution time, in hours.
linkedOlaIds	ObjectId[]	optional	[]	OLA policies this contract underpins. References OlaPolicy documents.
scopeDescription	string	optional	—	What the contract covers.
penaltyClause	string	optional	—	Penalty/credit terms if the vendor misses its targets.
renewalNotifyDays	number	optional	30	How many days before endDate to surface a renewal reminder.
status	enum	optional	active	active · expired · terminated · pending
attachments	string[]	optional	[]	Attachment references. Not settable on create/update via this API.
notes	string	optional	—	Free-form internal notes.
createdAt / updatedAt	timestamp	optional	auto	Managed by the record.

Status

•pending — Contract negotiated but not yet in force.
•active — Default status; the contract is currently in effect.
•expired — Past its endDate.
•terminated — Ended early.

Status is a plain field on the record — there is no dedicated transition endpoint; set it via PATCH.

Linking to OLAs

linkedOlaIds associates the contract with one or more OLA policies it underpins. The API validates that every ID in the array is a well-formed ObjectId — if the array is non-empty and any entry fails validation, the whole write is rejected with VALIDATION_ERROR.

Access

Routes require the feature_itsm_underpinning_contracts (or feature_itsm) feature flag to be enabled for the tenant, and are gated by the standard ITSM role guard. Records are additionally scoped by workspace, with backward-compatible matching for records written before workspace scoping was added.

bash

POST /api/itsm/underpinning-contracts
{
  "name": "Network Hardware Support — Acme Networks",
  "vendorName": "Acme Networks",
  "vendorContact": "Jane Doe",
  "vendorEmail": "support@acmenetworks.com",
  "contractNumber": "ACME-2026-0417",
  "startDate": "2026-01-01T00:00:00.000Z",
  "endDate": "2026-12-31T23:59:59.000Z",
  "responseTargetHours": 4,
  "resolutionTargetHours": 24,
  "linkedOlaIds": ["665f1a2b3c4d5e6f7a8b9c0d"],
  "scopeDescription": "On-site support for core switches and routers at all production data centers.",
  "penaltyClause": "5% service credit per hour beyond the contracted response target.",
  "renewalNotifyDays": 45
}

startDate must be strictly before endDate on both create and update — the API validates this and re-validates it on PATCH even when only one of the two dates is being changed.

API Quick Reference

GET

/api/itsm/underpinning-contracts

List contracts. Query: status, q (name search), limit

POST

/api/itsm/underpinning-contracts

Create a contract

GET

/api/itsm/underpinning-contracts/:id

Get a contract by id

PATCH

/api/itsm/underpinning-contracts/:id

Update a contract

DELETE

/api/itsm/underpinning-contracts/:id

Delete a contract