Use the NikoHealth External API to add one or more insurances to an existing patient. You can see every endpoint below in Swagger.
Before You Start: Get the Payer ID and Plan ID
The payer, and the plan if you use one, must already exist in your NikoHealth environment. Payers and plans can only be added in the NikoHealth UI; the API can look them up but can’t create them.
Once they’re set up, get their IDs:
1. Look up the payer
GET /v1/payers/dictionary
Optional query parameters: name, claimCode, id, pageIndex (default 0) and pageSize (default 10).
⚠️ Results are paginated and return 10 at a time by default. Filter by name or claimCode, or page through the results, before you decide a payer is missing.
GET /v1/payers/dictionary?name=Cigna
{
"Count": 1,
"Items": [
{
"Id": "3c8e1f5a9b2d47e6a0c4f81b7d395e2a6f0b4c19",
"Name": "Cigna",
"ClaimCode": "62308"
}
]
}
2. Look up the plans for that payer (optional)
GET /v1/payers/{payerId}/plans/dictionaryGET /v1/payers/3c8e1f5a9b2d47e6a0c4f81b7d395e2a6f0b4c19/plans/dictionary
{
"Items": [
{
"Id": "8f2a6d0c4e91b73f5a8d2c6e0b4f97a13d5e8c20",
"Name": "Cigna PPO",
"Type": { "Id": "Other", "Name": "Other" }
}
]
}
Step 1: Create the Insurance
POST /v1/patients/{patientId}/insurances
Put the patient’s numeric ID in the path of the URL, for example 10000105.
Required fields
Field | Notes |
| The ID from |
| Up to 80 characters |
|
|
|
|
Conditionally required holder fields
Holder.Name,Holder.GenderandHolder.DateOfBirthdayare required unless the relationship isEmployer.Holder.OrganizationNameis required when the relationship isEmployer.Holder.Addressis required when the relationship is anything other thanSelf.
Common optional fields: PayerPlanId, GroupNumber, EffectiveDate, TerminationDate and InsuranceTypeCode (Medicare Secondary only).
Example: primary insurance where the patient is the holder
POST /v1/patients/10000105/insurances
{
"PayerId": "3c8e1f5a9b2d47e6a0c4f81b7d395e2a6f0b4c19",
"PayerPlanId": "8f2a6d0c4e91b73f5a8d2c6e0b4f97a13d5e8c20",
"PolicyNumber": "XYZ123456789",
"GroupNumber": "GRP-4455",
"Status": "Active",
"EffectiveDate": "2026-01-01",
"Holder": {
"Relationship": "Self",
"Name": { "FirstName": "Jane", "LastName": "Doe" },
"Gender": "Female",
"DateOfBirthday": "1980-05-14"
}
}
Response: 201 Created
{ "Id": "PI46bd2b00c5eaaaebaf04f17dee14f7e5" }
Example: secondary insurance where the spouse is the holder
POST /v1/patients/10000105/insurances
{
"PayerId": "b71d4e9f2a06c8357e1b9d4f6a2c08e5d3b7f914",
"PolicyNumber": "MED987654321",
"Status": "Active",
"Holder": {
"Relationship": "Spouse",
"Name": { "FirstName": "John", "LastName": "Doe" },
"Gender": "Male",
"DateOfBirthday": "1978-09-02",
"Address": {
"AddressLine": "123 Main St",
"City": "Birmingham",
"State": "AL",
"Zip": "35203"
}
}
}
Response: 201 Created
{ "Id": "PI9a3f7c01d4e8b26f5a0c9e3d71b4f8a2" }
Save each returned Id in case you need to change the order later.
Step 2: Adding Multiple Insurances (Primary, Secondary, etc.)
Insurances are ordered by the sequence you post them in. The first one posted becomes primary, the second secondary, and so on. Make a separate POST call for each insurance, in the order you want.
Changing the order
To change the order after the insurances are created, use:
POST /v1/patients/{patientId}/insurances/reorder
List the Patient Insurance IDs in the new priority order. The first ID becomes primary, the second secondary, and so on.
POST /v1/patients/10000105/insurances/reorder
{
"PatientInsuranceIds": [
"PI9a3f7c01d4e8b26f5a0c9e3d71b4f8a2",
"PI46bd2b00c5eaaaebaf04f17dee14f7e5"
]
}
Response: 200 OK
Common Errors
Code | Meaning |
400 | Invalid request, such as a missing required field or a bad enum value. The response body explains the problem. |
401 | The token is missing, expired or invalid. |
403 | You don’t have permission to access this resource. |
404 | The patient or payer wasn’t found. |
429 | Too many requests. |
