---
title: "Create a payer record"
method: POST
path: "/payers"
tags: ["Payers"]
---

# Create a payer record

`POST /payers`

Creates a new payer in the shared payer catalog. Use this before associating a payer with a plan or provider network; the `id` returned here is required by those downstream association endpoints.

Requires the `CREATE_PAYER` permission. The `tenant-id` header is required and forwarded downstream for audit-trail attribution only — because the payer catalog is not tenant-partitioned, the created payer is visible to any tenant with `READ_PAYER` permission; this is not a tenant-private resource.

The request `data` field is validated against the external JSON Schema at `https://schemas.certifyos.com/entities/Payer.schema.json`, which requires `name` and also accepts `category`, `sourceSystem` (`API` or `File Upload`), and `changeReason`. Payloads that fail validation are rejected with `400`.

This operation is **not idempotent** — each successful request creates a distinct payer record, even if the payload is identical to a previous call.

On success, returns `201` with the created `PayerResponse`. This endpoint does not accept `externalPayerId` or `sourceId` in the request, so both are always empty on payers created through it (omitted from the example below); a populated value on an existing payer means it was created through another path (e.g. bulk import).

## Headers

- `tenant-id` string, required

## Request body

- CreatePayerRequest
  - `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 `201`

The newly created 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 (e.g. missing the required `name` field).
- `401` — Unauthorized - Authentication required
- `403` — Forbidden - Insufficient permissions
- `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)