This resource represents a payer in the healthcare system. A payer refers to an entity that finances or reimburses the cost of health services. Use it to get, create, and update payers.
openapi: 3.2.0
info:
title: Certifyos Payers API
version: 1.0.0
description: 'Operations tagged Payers across 2 of this provider''s published API definitions: certifyos-api-service-openapi.yml, certifyos-roster-service-openapi.yml. Each path carries the servers of the definition it was published in.'
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
- url: http://localhost:9001
description: Local Development Server
tags:
- name: Payers
description: This resource represents a payer in the healthcare system. A payer refers to an entity that finances or reimburses the cost of health services. Use it to get, create, and update payers.
paths:
/payers:
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
get:
summary: Get all payers
description: Returns a list of payers for the provided tenant. The payers are returned sorted by creation date, with the most recent payers appearing first.
operationId: getPayers
tags:
- Payers
parameters:
- description: Optional name to filter the list of payers. The search is case-insensitive and partial.
in: query
name: name
schema:
type: string
- description: The tenant identifier.
in: header
name: tenant-id
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/GetAllPayersResponse'
'400':
description: Returned if the request is invalid. `tenant-id` and `user-id` headers are required.
'401':
description: Returned if the request is unauthorized. Authentication required.
'403':
description: Returned if the request is forbidden. Insufficient permissions.
'500':
description: Returned if the request is an internal server error.
'502':
description: Returned if the request is a bad gateway. Downstream service error.
'503':
description: Returned if the request is a service unavailable. Network connectivity issues.
security:
- jwt: []
post:
summary: Create a new payer
description: Creates a new payer with the provided details
operationId: createPayer
tags:
- Payers
parameters:
- description: Tenant ID
required: true
name: tenant-id
in: header
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePayerRequest'
required: true
responses:
'201':
description: Payer created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PayerResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
'401':
description: Unauthorized - Authentication required
'403':
description: Forbidden - Insufficient permissions
'500':
description: Internal server error
security:
- jwt: []
/payers/{id}:
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
put:
summary: Update an existing payer
description: Updates a payer with the provided details
operationId: updatePayer
tags:
- Payers
parameters:
- description: Payer identifier
required: true
name: id
in: path
schema:
type: string
- description: Tenant ID
required: true
name: tenant-id
in: header
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayerRequest'
required: true
responses:
'200':
description: Payer updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PayerResponse'
'400':
description: Invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
'401':
description: Unauthorized - Authentication required
'403':
description: Forbidden - Insufficient permissions
'404':
description: Payer not found
'500':
description: Internal server error
security:
- jwt: []
get:
summary: Get a payer by ID
description: Retrieves a specific payer by its unique identifier
operationId: getPayerById
tags:
- Payers
parameters:
- description: ID of the payer to retrieve
required: true
name: id
in: path
schema:
type: string
- description: Tenant ID
required: true
name: tenant-id
in: header
schema:
type: string
responses:
'200':
description: Payer retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PayerResponse'
'401':
description: Unauthorized - Authentication required
'403':
description: Forbidden - Insufficient permissions
'404':
description: Payer not found
'500':
description: Internal server error
security:
- jwt: []
components:
schemas:
JsonNodeType:
type: string
enum:
- ARRAY
- BINARY
- BOOLEAN
- MISSING
- 'NULL'
- NUMBER
- OBJECT
- POJO
- STRING
GetAllPayersResponse:
type: object
properties:
totalCount:
type: integer
format: int64
data:
type: array
items:
$ref: '#/components/schemas/Payer.schema'
SourceSystem.schema:
$schema: https://json-schema.org/draft/2020-12/schema
$id: https://schemas.certifyos.com/enums/SourceSystem.schema.json
title: Source System Enum
description: Specifies the origin system of a record.
type: string
enum:
- API
- File Upload
PayerRequest:
type: object
properties:
id:
type: string
externalPayerId:
type: string
sourceId:
type: string
data:
$ref: '#/components/schemas/JsonNode'
dataToValidate:
$ref: '#/components/schemas/JsonNode'
Payer.schema:
$schema: https://json-schema.org/draft/2020-12/schema
$id: https://schemas.certifyos.com/entities/Payer.schema.json
title: Payer
description: Represents an entity responsible for financing or reimbursing the cost of healthcare services.
type: object
properties:
name:
description: Name of the payer
type: string
category:
description: Type of payer
type: string
sourceSystem:
description: Origin of the record (e.g., API, File Upload)
$ref: '#/components/schemas/SourceSystem.schema'
changeReason:
description: Optional description of why a change was made
type: string
required:
- name
CreatePayerRequest:
type: object
properties:
data:
$ref: '#/components/schemas/Payer.schema'
type: object
JsonNode:
type: object
properties:
empty:
type: boolean
valueNode:
type: boolean
containerNode:
type: boolean
missingNode:
type: boolean
array:
type: boolean
object:
type: boolean
nodeType:
$ref: '#/components/schemas/JsonNodeType'
pojo:
type: boolean
number:
type: boolean
integralNumber:
type: boolean
floatingPointNumber:
type: boolean
short:
type: boolean
int:
type: boolean
long:
type: boolean
float:
type: boolean
double:
type: boolean
bigDecimal:
type: boolean
bigInteger:
type: boolean
textual:
type: boolean
boolean:
type: boolean
'null':
type: boolean
binary:
type: boolean
BadRequestErrorResponse:
description: Standard error response structure for 400 Bad Request validation and client errors
type: object
properties:
errors:
type: array
items:
type: string
description: List of error messages
examples:
- - Validation failed
- Required field missing
errorDetails:
description: Detailed error information with specific validation failures
type: array
$ref: '#/components/schemas/JsonNode'
PayerResponse:
type: object
properties:
id:
type: string
externalPayerId:
type: string
sourceId:
type: string
data:
$ref: '#/components/schemas/JsonNode'
securitySchemes:
jwt:
type: http
description: JWT Authentication - Provide only the raw token without Bearer prefix
scheme: bearer
bearerFormat: JWT
x-refined-from:
- certifyos-api-service-openapi.yml
- certifyos-roster-service-openapi.yml