Clinic Insurances API

Endpoints for managing insurance information within the clinic system.

Person Information

List Person Information

Get a list of person information records for insurance purposes.

Endpoint: GET /v1/clinic/insurances/person_informations
Authentication: Required

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number for pagination
`page_size`	integer	No	Number of items per page
`patient_id`	integer	No	Filter by patient ID

Get Person Information Details

Endpoint: GET /v1/clinic/insurances/person_informations/{id}
Authentication: Required

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	Person information ID

Create Person Information

Endpoint: POST /v1/clinic/insurances/person_informations
Authentication: Required

Request Body Parameters

Parameter	Type	Required	Description
`person_information`	object	Yes	Person information data object
`person_information.ownable_id`	integer	Yes	ID of the ownable entity (usually patient)
`person_information.ownable_type`	string	Yes	Type of ownable entity (e.g., “Patient”)
`person_information.first_name`	string	Yes	First name
`person_information.last_name`	string	Yes	Last name
`person_information.date_of_birth`	string	Yes	Date of birth (YYYY-MM-DD)
`person_information.ssn`	string	No	Social Security Number
`person_information.phone`	string	No	Phone number
`person_information.email`	string	No	Email address

Example Request


POST /v1/clinic/insurances/person_informations HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here
 
{
  "person_information": {
    "ownable_id": 1049,
    "ownable_type": "Patient",
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-05-15",
    "ssn": "123-45-6789",
    "phone": "+1-555-123-4567",
    "email": "[email protected]"
  }
}

Dependents

List Dependents

Get a list of dependents for insurance coverage.

Endpoint: GET /v1/clinic/insurances/dependents
Authentication: Required

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number for pagination
`page_size`	integer	No	Number of items per page
`primary_holder_id`	integer	No	Filter by primary insurance holder ID

Create Dependent

Endpoint: POST /v1/clinic/insurances/dependents
Authentication: Required

Request Body Parameters

Parameter	Type	Required	Description
`dependent`	object	Yes	Dependent data object
`dependent.primary_holder_id`	integer	Yes	ID of the primary insurance holder
`dependent.first_name`	string	Yes	Dependent’s first name
`dependent.last_name`	string	Yes	Dependent’s last name
`dependent.date_of_birth`	string	Yes	Dependent’s date of birth (YYYY-MM-DD)
`dependent.relationship`	string	Yes	Relationship to primary holder
`dependent.ssn`	string	No	Dependent’s Social Security Number

Example Request


POST /v1/clinic/insurances/dependents HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here
 
{
  "dependent": {
    "primary_holder_id": 1049,
    "first_name": "Jane",
    "last_name": "Doe",
    "date_of_birth": "2010-03-20",
    "relationship": "child",
    "ssn": "987-65-4321"
  }
}

Insurance Plans

List Insurance Plans

Get a list of available insurance plans.

Endpoint: GET /v1/clinic/insurances/plans
Authentication: Required

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number for pagination
`page_size`	integer	No	Number of items per page
`plan_type`	string	No	Filter by plan type
`carrier`	string	No	Filter by insurance carrier
`active`	boolean	No	Filter by active status

Response Format

Person Information Response


{
  "id": 123,
  "ownable_id": 1049,
  "ownable_type": "Patient",
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1990-05-15",
  "ssn": "***-**-6789",
  "phone": "+1-555-123-4567",
  "email": "[email protected]",
  "created_at": "2023-10-20T10:00:00.000Z",
  "updated_at": "2023-10-20T10:00:00.000Z"
}

Dependent Response


{
  "id": 456,
  "primary_holder_id": 1049,
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "2010-03-20",
  "relationship": "child",
  "ssn": "***-**-4321",
  "created_at": "2023-10-20T10:00:00.000Z",
  "updated_at": "2023-10-20T10:00:00.000Z"
}

Insurance Plan Response


{
  "id": 789,
  "plan_name": "Premium Health Plan",
  "carrier": "Health Insurance Co.",
  "plan_type": "PPO",
  "coverage_details": {
    "deductible": 1000,
    "copay": 25,
    "out_of_pocket_max": 5000
  },
  "active": true,
  "created_at": "2023-10-20T10:00:00.000Z",
  "updated_at": "2023-10-20T10:00:00.000Z"
}

Error Responses

422 Unprocessable Entity


{
  "errors": {
    "first_name": ["can't be blank"],
    "date_of_birth": ["is invalid"],
    "ownable_id": ["must exist"]
  }
}

404 Not Found


{
  "errors": "Person information not found"
}

Notes

SSN fields are masked in responses for security purposes
Date fields should be provided in YYYY-MM-DD format
The ownable_type is typically “Patient” but may support other entity types
Relationship values for dependents include: “spouse”, “child”, “parent”, “other”
Insurance plan details may vary based on carrier and plan type