Certifyos Plan API

openapi: 3.2.0
info:
  description: API for Certify application
  title: Certify API Layer Plan API
  version: 1.0.0
servers:
- url: http://localhost:9000
  description: Local Development Server
- url: https://api-service.staging.certifyos.com
  description: Staging Server
- url: https://api-service.internal.certifyos.com
  description: Internal Server
- url: https://api-service.test.certifyos.com
  description: Test Server
- url: https://api-service.demo.certifyos.com
  description: Demo Server
- url: https://api-service.certifyos.com
  description: Production Server
tags:
- name: Plan
  description: APIs for managing plan entities
paths:
  /plans:
    get:
      summary: List tenant plans sorted by creation date
      description: Returns the first page of plans belonging to the specified tenant, sorted by creation date descending (most recent first). Call this to retrieve the current plan catalogue for a tenant. The caller must hold the READ_PLAN permission. **Note:** the current implementation always queries page 0 with a fixed page size of 10; pagination parameters are not exposed on this endpoint, so if the tenant has more than 10 plans, only the 10 most recent are returned. If the tenant has no plans, `data` is empty and `totalCount` is 0 (a downstream 404 is silently mapped to an empty result).
      operationId: getPlans
      tags:
      - Plan
      parameters:
      - description: The tenant identifier. Scopes the returned plans to this tenant; no default — the request fails with 400 if omitted.
        in: header
        name: tenant-id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Envelope containing the tenant's plans for the current (fixed) page.
          content:
            application/json:
              examples:
                plans:
                  value:
                    totalCount: 1
                    data:
                    - id: plan_5f3e8a1b2c9d
                      tenantId: tenant_001
                      payerId: payer_4b6a9c2d
                      data:
                        name: Bronze PPO 2026
                        payer: payer_4b6a9c2d
              schema:
                $ref: '#/components/schemas/GetAllPlansResponse'
        '400':
          description: Returned when the required `tenant-id` header is missing.
          content:
            application/json:
              examples:
                missingTenantId:
                  value:
                    errors:
                    - httpStatus: 400
                      reason: VALIDATION_ERROR
                      title: 'Validation failed for field: getPlans.tenantId'
                      detail: must not be null
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Returned if the request is unauthorized. Authentication required.
        '403':
          description: Returned if the caller lacks the READ_PLAN permission.
        '502':
          description: Returned when the downstream data service (DAL) responds with an error status.
          content:
            application/json:
              examples:
                downstreamError:
                  value:
                    error: Downstream service error
        '503':
          description: Returned when the downstream data service (DAL) cannot be reached.
          content:
            application/json:
              examples:
                serviceUnavailable:
                  value:
                    error: Service temporarily unavailable
        '500':
          description: Returned for an unexpected internal error.
          content:
            application/json:
              examples:
                internalError:
                  value:
                    error: An unexpected error occurred
      security:
      - jwt: []
    post:
      summary: Create a new plan for a tenant
      description: 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`.
      operationId: createPlan
      tags:
      - Plan
      parameters:
      - description: The tenant identifier to associate the new plan with.
        required: true
        name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            examples:
              createPlan:
                value:
                  data:
                    payer: payer_4b6a9c2d
            schema:
              $ref: '#/components/schemas/CreatePlanRequest'
        required: true
      responses:
        '201':
          description: The created plan, including the server-assigned `id`. Store this `id` to reference the plan in subsequent calls (e.g. PUT /plans/{id}).
          content:
            application/json:
              examples:
                createdPlan:
                  value:
                    id: plan_5f3e8a1b2c9d
                    tenantId: tenant_001
                    payerId: payer_4b6a9c2d
                    data:
                      payer: payer_4b6a9c2d
              schema:
                $ref: '#/components/schemas/GetPlanResponse'
        '400':
          description: 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.
          content:
            application/json:
              examples:
                schemaValidationFailed:
                  value:
                    errors:
                    - '$.data.payer: is missing but it is required'
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - Caller lacks the CREATE_PLAN permission
        '502':
          description: Returned when the downstream data service (DAL) responds with a server error.
          content:
            application/json:
              examples:
                downstreamUnavailable:
                  value:
                    error: Downstream service unavailable
        '503':
          description: Returned when the downstream data service (DAL) cannot be reached.
          content:
            application/json:
              examples:
                serviceUnavailable:
                  value:
                    error: Service temporarily unavailable
        '500':
          description: Returned for an unexpected internal error.
          content:
            application/json:
              examples:
                internalError:
                  value:
                    error: An unexpected error occurred
      security:
      - jwt: []
  /plans/{id}:
    put:
      summary: Fully replace an existing plan by ID
      description: Replaces the entire plan record identified by `{id}` with the supplied payload. This is a **full replacement** — fields omitted from `data` are not preserved from the prior version, so submit the complete desired plan `data` on every call, not a partial diff. Submitting the same payload twice for the same `{id}` is idempotent. The caller must hold the UPDATE_PLAN permission. As with plan creation, `data.payer` is extracted and stored as `payerId`, and the referenced payer is not validated for existence. `data`'s full shape is defined by the external Plan JSON schema and may include required fields beyond `payer`.
      operationId: updatePlan
      tags:
      - Plan
      parameters:
      - description: The plan's server-assigned identifier, as returned by POST /plans.
        required: true
        name: id
        in: path
        schema:
          type: string
      - description: The tenant identifier that must own the plan being replaced.
        required: true
        name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            examples:
              updatePlan:
                value:
                  data:
                    payer: payer_4b6a9c2d
            schema:
              $ref: '#/components/schemas/CreatePlanRequest'
        required: true
      responses:
        '200':
          description: The plan as it exists after the replacement.
          content:
            application/json:
              examples:
                updatedPlan:
                  value:
                    id: plan_5f3e8a1b2c9d
                    tenantId: tenant_001
                    payerId: payer_4b6a9c2d
                    data:
                      payer: payer_4b6a9c2d
              schema:
                $ref: '#/components/schemas/GetPlanResponse'
        '400':
          description: 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.
          content:
            application/json:
              examples:
                schemaValidationFailed:
                  value:
                    errors:
                    - '$.data.payer: is missing but it is required'
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - Caller lacks the UPDATE_PLAN permission
        '404':
          description: Returned when no plan exists with the given `{id}` for the tenant. Passed through unchanged from the downstream data service (DAL).
          content:
            application/json:
              examples:
                planNotFound:
                  value:
                    errors:
                    - httpStatus: 404
                      reason: Not Found
                      title: Entity Not Found
                      detail: 'Plan not found with ID: plan_5f3e8a1b2c9d'
              schema:
                $ref: '#/components/schemas/ApiError'
        '502':
          description: Returned when the downstream data service (DAL) responds with a server error.
          content:
            application/json:
              examples:
                downstreamUnavailable:
                  value:
                    error: Downstream service unavailable
        '503':
          description: Returned when the downstream data service (DAL) cannot be reached.
          content:
            application/json:
              examples:
                serviceUnavailable:
                  value:
                    error: Service temporarily unavailable
        '500':
          description: Returned for an unexpected internal error.
          content:
            application/json:
              examples:
                internalError:
                  value:
                    error: An unexpected error occurred
      security:
      - jwt: []
components:
  schemas:
    ApiError:
      type: object
      description: Standard API error response containing a list of error objects
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
          description: List of error objects describing validation or processing failures
    GetAllPlansResponse:
      type: object
      properties:
        totalCount:
          type: integer
          format: int64
          description: Total number of plans matching the request, across all pages.
        data:
          type: array
          items:
            type: object
            description: A single plan record as it appears in a paginated plans listing.
            properties:
              id:
                type: string
                description: Server-assigned unique identifier for the plan.
              tenantId:
                type: string
                description: Identifier of the tenant that owns this plan.
              payerId:
                type: string
                description: Identifier of the payer this plan is associated with. Extracted server-side from `data.payer` at creation time.
              data:
                type: object
                description: The plan's domain data, validated against the Plan JSON schema at creation/update time.
          description: The current page of plan records (at most 10).
    BadRequestErrorResponse:
      type: object
      description: Standard error response structure for 400 Bad Request validation and client errors
      properties:
        errors:
          type: array
          examples:
          - - Validation failed
            - Required field missing
          items:
            type: string
          description: List of error messages
        errorDetails:
          type: object
          description: Detailed error information with specific validation failures
    ErrorObject:
      type: object
      description: Individual error object containing details about a specific validation or processing error
      properties:
        httpStatus:
          type: integer
          format: int32
          examples:
          - 400
          description: HTTP status code for this error
        reason:
          type: string
          examples:
          - VALIDATION_ERROR
          description: Error reason/code
        title:
          type: string
          examples:
          - 'Validation failed for field: eventTypes'
          description: Error title/summary
        detail:
          type: string
          examples:
          - eventTypes is required and cannot be empty or null
          description: Detailed error message
        rejectedValue:
          type: string
          description: The value that was rejected, omitted for sensitive fields such as SSN
    CreatePlanRequest:
      type: object
      properties:
        data:
          $ref: https://schemas.certifyos.com/entities/Plan.schema.json
          type: object
          description: The plan's domain data. Must satisfy the Plan JSON schema; `payer` is required and is extracted server-side to populate the stored `payerId`.
    GetPlanResponse:
      type: object
      description: A single plan record as it appears in a paginated plans listing.
      properties:
        id:
          type: string
          description: Server-assigned unique identifier for the plan.
        tenantId:
          type: string
          description: Identifier of the tenant that owns this plan.
        payerId:
          type: string
          description: Identifier of the payer this plan is associated with. Extracted server-side from `data.payer` at creation time.
        data:
          type: object
          description: The plan's domain data, validated against the Plan JSON schema at creation/update time.
  securitySchemes:
    jwt:
      type: http
      description: JWT Authentication - Provide only the raw token without Bearer prefix
      scheme: bearer
      bearerFormat: JWT
x-provenance:
  method: harvested
  publisher: Certifyos
  source: https://api-service.internal.certifyos.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)