---
title: "List contracts with pagination"
method: GET
path: "/contracts"
tags: ["Contracts"]
---

# List contracts with pagination

`GET /contracts`

Returns a paginated list of contracts for the tenant identified by the `tenant-id` header.

**When to use:** Use this endpoint to browse or page through the contract catalogue. For a single known contract, prefer `GET /contracts/{id}` to avoid scanning a page of results.

**Preconditions:** Requires the `READ_CONTRACT` permission.

**Pagination:** Two modes are supported and should not be combined:
- *Offset-based*: provide `page` (0-based; treated as `0` if omitted or negative) and `size` (records per page; defaults to `50` if omitted or non-positive, silently clamped to a maximum of `100` if a larger value is supplied).
- *Cursor-based*: provide `startAfterId` to page forward or `endAtId` to page backward, using the contract's server-assigned `id` field (not `documentId`) from a previous response. If either cursor parameter is supplied, it takes precedence over `page` even if both are sent.
If none of `page`, `startAfterId`, or `endAtId` are supplied, the first page is returned in cursor mode, ordered ascending by `id`.

**Filtering:** This operation does not currently accept a filter query parameter - every call returns the full unfiltered set of contracts for the tenant, paginated. (The underlying data layer supports filtering by `planId`/`networkId`/`documentId`, but this endpoint does not yet forward a filter to it.)

**Response:** A paginated envelope containing a `data` array of Contract objects, a `links` object with `self`/`next`/`prev` navigation URLs (`next`/`prev` are `null` when there is no further page in that direction), and a `totalCount` of matching records. No state is changed; this operation is safe and idempotent.

## Query parameters

- `endAtId` string
- `page` integer
- `size` integer
- `startAfterId` string

## Headers

- `tenant-id` string, required

## Response `200`

Paginated list of contracts for the tenant, in the order determined by the pagination mode used (see description).

- PagedContractResponse — A single page of Contracts, matching either offset-based or cursor-based pagination.
  - `data` Contract[] — Contracts on this page, in the order determined by the pagination mode used.
    - `id` string — Server-assigned unique identifier (UUID). Ignored if supplied in a create request; on replace (PUT), the existing contract's id is always preserved regardless of what is sent.
    - `planId` string — Identifier of the plan this contract belongs to. Required on create. On replace (PUT), any value supplied here is ignored - the existing contract's planId is always preserved.
    - `networkId` string — Identifier of the network this contract belongs to. Required on create. On replace (PUT), any value supplied here is ignored - the existing contract's networkId is always preserved.
    - `documentId` string — Caller-supplied business document identifier for this contract. Required on create. On replace (PUT), any value supplied here is ignored - the existing contract's documentId is always preserved.
    - `createdBy` string — User ID of the caller who originally created the contract. Always set by the server from the authenticated caller on create; any value supplied in the request body is ignored. Preserved unchanged on every subsequent replace (PUT), regardless of the request body.
    - `updatedBy` string — User ID of the caller who most recently created or replaced the contract. Always set by the server from the authenticated caller; any value supplied in the request body is ignored.
    - `generalInfo` ContractGeneralInfo — Core contract identity and classification fields.
      - `contractId` string — Business contract identifier assigned by the caller. Distinct from the top-level server-assigned `Contract.id`. Required.
      - `contractName` string — Human-readable name of the contract. Required.
      - `contractTemplate` string — Name of the contract template this agreement was drafted from.
      - `contractRate` string — Free-text description of the contracted rate.
      - `reimbursementCode` string — Reimbursement code associated with this contract.
      - `contractType` 'FFS' | 'Capitation' | 'VBC' — Type of contract arrangement. Required. `FFS` = fee-for-service (paid per rendered service); `Capitation` = fixed per-member payment regardless of services rendered; `VBC` = value-based care (payment tied to outcomes/quality rather than volume).
      - `vbcAttribution` string — Description of value-based-care attribution methodology, if applicable.
      - `contractStatus` 'Active' | 'Terminated' | 'Contracting' | 'Not Known' — Current lifecycle status of the contract. Required. `Active` = currently in effect; `Terminated` = ended; `Contracting` = under negotiation, not yet effective; `Not Known` = status could not be determined at the time of entry.
      - `contractAgreementType` 'Single' | 'Multiple Provider' | 'IPA' | 'System' — Structure of the contracting arrangement. Optional. `Single` = one provider entity; `Multiple Provider` = a named group of provider entities; `IPA` = Independent Practice Association (a legal entity of independent providers contracting collectively); `System` = a health system encompassing multiple facilities/providers.
      - `groupId` string — Identifier of the group this contract applies to, if any.
      - `practitionerId` string — Identifier of the individual practitioner this contract applies to, if any.
      - `networkId` string — Identifier of the network this contract belongs to, mirroring the top-level `Contract.networkId`.
      - `planId` string — Identifier of the plan this contract belongs to, mirroring the top-level `Contract.planId`.
    - `lifecycle` ContractLifeCycleInfo — Contract lifecycle dates. All fields are optional and use the ISO-8601 `date` format (YYYY-MM-DD, no time or offset).
      - `contractEffectiveDate` string, date — Date the contract terms take effect.
      - `initialTermDate` string, date — Date the contract's initial term ends (subject to renewal).
      - `terminationInformedDate` string, date — Date on which notice of termination was given.
      - `terminationDate` string, date — Date the contract terminates.
      - `billingEffectiveDate` string, date — Date from which billing under this contract is effective.
      - `billingTerminationDate` string, date — Date after which billing under this contract stops.
    - `financial` ContractFinancialInfo — Contract financial and payment terms. All fields are optional.
      - `feeSchedule` string — Name of the fee schedule used for standard reimbursement.
      - `additionalFeeSchedule` string — Name of a supplemental fee schedule applied alongside the primary one, if any.
      - `contractPaymentType` 'Per Claim' | 'Capitation' | 'Shared Savings' — How the provider is paid under this contract.
      - `nonTypicalContractTerms` string — Free-text description of any non-standard financial terms in this contract.
      - `providerRateCalculation` string — Description of how the provider's reimbursement rate is calculated.
      - `rateLesserOfClaimAllowed` boolean — Whether the contract allows paying the lesser of the billed charge or the contracted rate.
      - `sequestrationAllowed` boolean — Whether Medicare sequestration reductions apply to payments under this contract.
      - `sharedSavings` boolean — Whether this contract includes a shared-savings arrangement.
      - `bonus` boolean — Whether this contract includes a performance bonus arrangement.
      - `claimSubmissionCycle` 'Weekly' | 'Biweekly' | 'Monthly' — How often claims must be submitted under this contract.
      - `snfCorporateChampionRate` number — SNF corporate champion capitation rate, in dollars.
      - `snfCapitationPartARate` number — SNF Medicare Part A capitation rate, in dollars.
      - `snfCapitationPartBRate` number — SNF Medicare Part B capitation rate, in dollars.
      - `snfCapitationBillAboveRate` number — Per-diem rate billed above the SNF capitation threshold, in dollars.
      - `hasGssRate` boolean — Whether this contract includes a gain-share/shared-savings (GSS) rate.
      - `gssRateDetails` string — Free-text details of the gain-share/shared-savings (GSS) rate arrangement.
      - `gssMinimumMM` integer — Minimum member-months (MM) required for the GSS rate to apply.
      - `gssTerm` string — Free-text description of the GSS rate's contract term.
      - `gssFrequency` 'Monthly' | 'Quarterly' | 'Annual' — How often the GSS rate is calculated and settled.
      - `appPenalty` string — Description of any penalty applied for missed appointment (no-show) policies.
      - `telehealthNoShow` string — Description of the telehealth no-show policy for this contract.
    - `administrativeAndLegal` ContractAdministrativeAndLegalInfo — Contract administrative and legal terms. All fields are optional.
      - `amendmentOnFile` boolean — Whether a signed amendment to this contract is on file.
      - `amendmentNumber` string — Identifier/number of the amendment on file, if any.
      - `practitionersTerminationNoticePeriod` '30' | '60' | '90' | '120' — Notice period, in days, a practitioner must give before terminating this contract.
      - `providersManualUpdatesNoticePeriod` '30' | '60' | '90' | '120' — Notice period, in days, the payer must give providers before manual updates take effect.
      - `policyUpdateNotificationRequired` boolean — Whether providers must be notified before a policy update takes effect.
      - `claimFilingLimit` string — Deadline for submitting claims after the date of service.
      - `reimbursementScheduleUpdateFrequency` 'Monthly' | 'Quarterly' — How often the reimbursement schedule is updated.
      - `timelyPaymentCommitment` integer — Number of days within which the payer commits to paying a clean claim.
    - `clinicalAndQuality` ContractClinicalAndQualityInfo — Contract clinical and quality program terms. All fields are optional.
      - `hasQualityProgram` boolean — Whether this contract includes a quality incentive program.
      - `qualityProgramInitiatives` string — Free-text description of the quality program's initiatives.
      - `averageStarsAndPmpmBonus` string — Free-text summary of the star rating and per-member-per-month (PMPM) bonus tied to it.
      - `hasMlrTarget` boolean — Whether this contract includes a medical loss ratio (MLR) target.
      - `mlrTargetDescription` string — Free-text description of the medical loss ratio (MLR) target, if any.
      - `performanceReportingRequirements` string — Description of the performance reporting the provider must submit under this contract.
      - `credentialingDelegation` boolean — Whether credentialing responsibilities are delegated to the provider organization.
      - `recredentialingInterval` '1 yr' | '2 yr' | '3 yr' — How often practitioners under this contract must be recredentialed.
      - `referralRequirements` boolean — Whether this contract imposes referral requirements (e.g. requires PCP referral).
      - `priorAuthorizationRequired` boolean — Whether prior authorization is required for services under this contract.
      - `panelSizeLimits` string — Free-text description of any panel size limits imposed on providers.
      - `providerRosterUpdateFrequency` 'Monthly' | 'Quarterly' — How often the provider roster must be updated under this contract.
  - `links` PageLinks1
    - `self` string
    - `next` string
    - `prev` string
  - `totalCount` integer — Total number of contracts matching the request, across all pages.

## Other responses

- `400` — Reserved for invalid filter criteria. This endpoint does not currently expose a filter query parameter, so in practice this status is not triggered by any input to this operation today.
- `401` — Unauthorized - Authentication required
- `403` — Forbidden - Insufficient permissions

---

[API](https://skmtc.net/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.net/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/563848e0ecc0/schema)