Skip to main content

Adding Insurance to a Patient Record via API

Add one or more insurances to an existing patient, and change their order, using the NikoHealth External API.

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/dictionary
GET /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

PayerId

The ID from /v1/payers/dictionary

PolicyNumber

Up to 80 characters

Status

Active, Inactive, Review or Failed

Holder.Relationship

Self, Spouse, Parent, Employer or Other

Conditionally required holder fields

  • Holder.Name, Holder.Gender and Holder.DateOfBirthday are required unless the relationship is Employer.

  • Holder.OrganizationName is required when the relationship is Employer.

  • Holder.Address is required when the relationship is anything other than Self.

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.

Did this answer your question?