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.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 500
The updated payer.
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).
Unauthorized - Authentication required
Forbidden - Insufficient permissions
Returned if no payer exists with the given id.
Internal server error