---
title: "Create a new contract for the authenticated tenant"
method: POST
path: "/contracts"
tags: ["Contracts"]
---

# Create a new contract for the authenticated tenant

`POST /contracts`

Creates a new Contract record and returns the persisted object with server-assigned identifiers.

**What it does:** Registers a new contract for the tenant identified by the `tenant-id` header. The server assigns `id` (a UUID); any `id` supplied in the request body is ignored and discarded before the request reaches storage. `createdBy` and `updatedBy` are always set from the authenticated caller's user ID - any values supplied in the body are ignored.

**When to use:** Use this endpoint to introduce a net-new contract. To modify an existing contract, use `PUT /contracts/{id}` instead.

**Preconditions:** Requires the `CREATE_CONTRACT` permission. `documentId`, `networkId`, and `planId` are required top-level identifiers (caller-supplied, not server-generated). Within `generalInfo`, `contractId`, `contractName`, `contractType`, and `contractStatus` are required; all other fields and sections are optional.

**Response:** Returns `201 Created` with the full Contract object, including the server-assigned `id`. No async jobs, webhooks, or downstream events are triggered by this operation as of this writing.

## Headers

- `tenant-id` string, required

## Request body

- Contract — A contract between a healthcare provider and a payer.
  - `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.

## Response `201`

The newly created Contract, including its server-assigned `id`.

- Contract — A contract between a healthcare provider and a payer.
  - `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.

## Other responses

- `400` — The request body failed validation - for example, a required field such as `documentId`/`networkId`/`planId`, or `generalInfo.contractId`/`contractName`/`contractType`/`contractStatus`, was missing, or an enum field was set to a value outside its allowed set.
- `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)