Create a payer record

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