---
title: "Replace a payer's full record by ID"
method: PUT
path: "/payers/{id}"
tags: ["Payers"]
---

# Replace a payer's full record by ID

`PUT /payers/{id}`

Replaces the stored record for the payer identified by `{id}` with the supplied payload. This is a **full replacement, not a partial update** — confirmed against `PayerService.mergeModelsForUpdate` in the payer service, which overwrites `externalPayerId`, `sourceId`, and `data` wholesale from the request body. Any of these fields omitted from the request are cleared rather than preserved from the existing record, so always send the complete payer payload.

Requires the `UPDATE_PAYER` permission. The `tenant-id` header is required, but the payer catalog is not tenant-partitioned: any existing payer ID can be replaced regardless of which `tenant-id` value is supplied — the header is used only for audit-trail attribution. A missing or nonexistent `id` returns `404`.

The request `data` field is validated against the same external JSON Schema used at creation (`https://schemas.certifyos.com/entities/Payer.schema.json`). Payloads that fail validation are rejected with `400`.

On success, returns `200` with the updated `PayerResponse`.

## Path parameters

- `id` string, required

## Headers

- `tenant-id` string, required

## Request body

- PayerRequestSchema — Payer data used to replace an existing payer.
  - `externalPayerId` string
  - `sourceId` string
  - `data` PayerSchema — Represents an entity responsible for financing or reimbursing the cost of healthcare services.
    - `name` string, required — Name of the payer
    - `category` string — Type of payer
    - `sourceSystem` 'API' | 'File Upload' — Specifies the origin system of a record.
    - `changeReason` string — Optional description of why a change was made

## Response `200`

The updated payer.

- PayerResponseSchema — A payer record.
  - `id` string
  - `externalPayerId` string
  - `sourceId` string
  - `data` PayerSchema — Represents an entity responsible for financing or reimbursing the cost of healthcare services.
    - `name` string, required — Name of the payer
    - `category` string — Type of payer
    - `sourceSystem` 'API' | 'File Upload' — Specifies the origin system of a record.
    - `changeReason` string — Optional description of why a change was made

## Other responses

- `400` — Returned if `data` fails validation against the payer JSON Schema. Note: in the current implementation this specific error path returns an empty body rather than the structured error shape below (existing gap, not fixed in this change — see PR description).
- `401` — Unauthorized - Authentication required
- `403` — Forbidden - Insufficient permissions
- `404` — Returned if no payer exists with the given `id`.
- `500` — Internal server error

---

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