Sources and occurrences

Every obligation the API returns is either a source or an occurrence, as shown by its obligationType field.

Source (SOURCE): the obligation as defined on a contract, such as "Deliver a quarterly usage report." Its cadence says how the work is scheduled.
Occurrence (OCCURRENCE): one instance of a recurring or triggered source, such as the Q3 usage report. An occurrence has a sourceObligationId that points to its source, and a sourceRelationshipType of RECURRING or TRIGGERED.

Source `cadence`	Occurrences	Where status lives
`ONE_TIME`	None	The source's `userFacingObligations_status` property
`PERPETUAL`	None	The source's `userFacingObligations_status` property
`RECURRING`	Ironclad generates them on the schedule set in the Ironclad app	Each occurrence's `status`, `dueDate`, and `assigneeUserId`
`TRIGGERED`	Recorded each time the triggering event happens, either in the Ironclad app or with Create an Obligation by passing the source's ID as `sourceObligationId`	Each occurrence's `status`, `dueDate`, and `assigneeUserId`

For recurring and triggered sources, Ironclad keeps the source's userFacingObligations_status and userFacingObligations_dueDate properties as a summary of its occurrences: the due date is the next open occurrence's due date. To track or change the work itself, read and update the occurrences. To update an occurrence with Update an Obligation, include its sourceObligationId in the request body.

Listing occurrences

List All Obligations returns sources only. There are two ways to get their occurrences:

Goal	Use
Get every occurrence of one source	List Obligation Instances (`GET /obligations/{id}/instances`). Pass the source's ID or Ironclad ID. Results are paginated with `page` and `pageSize`, and `count` is the total across all pages.
Preview occurrences while listing sources	List All Obligations with `include=occurrences`. Each source gets `occurrences`, holding at most its first 5 occurrences, and `occurrenceCount`, its total. If `occurrenceCount` is greater than the number of occurrences returned, call List Obligation Instances for that source to get the rest.

Both return occurrences ordered by due date, earliest first, with undated occurrences last. That order includes past and completed occurrences, so the first 5 are not necessarily the upcoming ones.

{
  "page": 0,
  "pageSize": 20,
  "count": 1,
  "list": [
    {
      "id": "8f1c2d3e-4b5a-4c6d-9e8f-0a1b2c3d4e5f",
      "ironcladId": "OB-12",
      "name": "Deliver quarterly usage report",
      "obligationType": "SOURCE",
      "cadence": "RECURRING",
      "occurrenceCount": 8,
      "occurrences": [
        {
          "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
          "name": "Deliver quarterly usage report",
          "obligationType": "OCCURRENCE",
          "sourceObligationId": "8f1c2d3e-4b5a-4c6d-9e8f-0a1b2c3d4e5f",
          "sourceRelationshipType": "RECURRING",
          "status": "COMPLETED",
          "dueDate": "2026-03-31"
        }
      ]
    }
  ]
}

Access

Both ways of listing occurrences require the public.obligations.readObligations OAuth scope.
Triggered obligations must be enabled for your account. If they aren't, List Obligation Instances returns 403, and List All Obligations returns 400 when you pass include=occurrences. To enable them, contact your Ironclad account representative.