---
title: "Create a new plan for a tenant"
method: POST
path: "/plans"
tags: ["Plan"]
---

# Create a new plan for a tenant

`POST /plans`

Creates a new plan and associates it with the specified tenant. This operation is **not idempotent** — submitting the same payload twice creates two separate plan records. The caller must hold the CREATE_PLAN permission. The request body's `data.payer` field is extracted and stored as the plan's `payerId`; the referenced payer is not validated for existence before the plan is created. `data`'s full shape is defined by the external Plan JSON schema and may include required fields beyond `payer`.

## Headers

- `tenant-id` string, required

## Request body

- CreatePlanRequest
  - `data` PlanSchema — Represents a healthcare plan with business line, network type, and benefits information.
    - `lineOfBusiness` 'Medicare' | 'Medicaid' | 'Commercial' — Specifies the line of business associated with a healthcare plan.
    - `networkType` 'Commercial - HMO' | 'Commercial - PPO' | 'Medicare - HMO' | 'Medicaid - HMO' — Specifies the line of business and network type combination for a healthcare plan.
    - `benefits` string — The benefits offered under the plan.
    - `name` string — The name of the plan.

## Response `201`

The created plan, including the server-assigned `id`. Store this `id` to reference the plan in subsequent calls (e.g. PUT /plans/{id}).

- GetPlanResponse — A single plan record as it appears in a paginated plans listing.
  - `id` string — Server-assigned unique identifier for the plan.
  - `tenantId` string — Identifier of the tenant that owns this plan.
  - `payerId` string — Identifier of the payer this plan is associated with. Extracted server-side from `data.payer` at creation time.
  - `data` object — The plan's domain data, validated against the Plan JSON schema at creation/update time.

## Other responses

- `400` — Returned when `tenant-id` is missing or `data` fails validation against the Plan JSON schema. DAL-side validation errors are passed through with their original body.
- `401` — Unauthorized - Authentication required
- `403` — Forbidden - Caller lacks the CREATE_PLAN permission
- `500` — Returned for an unexpected internal error.
- `502` — Returned when the downstream data service (DAL) responds with a server error.
- `503` — Returned when the downstream data service (DAL) cannot be reached.

---

[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)