Skip to main content

API Versions and Deprecations

How NikoHealth API versions work, and which endpoints and fields are deprecated.

API versions

The version is part of every endpoint path:

https://{yourDomain}.nikohealth.com/api/external/v1/patients
https://{yourDomain}.nikohealth.com/api/external/v2/payments
https://{yourDomain}.nikohealth.com/api/external/v3/orders/{id}/cost-sharing

Version

What's in it

V1

The core API: patients, insurances, orders, documents, notes, eligibility, invoices, inventory, tasks, webhooks, and reference data (165 endpoints)

V2

Newer versions of specific areas: payments and payment invoices, invoice search, patient rentals, order cost sharing, and inventory product categories, groups, and manufacturers

V3

Order cost sharing (get and save)

Key points

  • Versions are not separate APIs. Use all three together with the same token. Most integrations use V1 for nearly everything, plus V2 or V3 for the specific areas above.

  • A newer version of an endpoint doesn't automatically remove the older one. When an older endpoint is being replaced, it's marked deprecated.

  • In Swagger, switch versions with the Select a definition dropdown at the top right (V1 Api, V2 Api, V3 Api).


What "Deprecated" Means

A deprecated endpoint or field still works today but will be removed in the future.

  • New integrations should not use deprecated endpoints or fields.

  • Existing integrations should plan to move to the replacement.

  • In Swagger, deprecated endpoints appear greyed out with a strikethrough, and deprecated fields are marked in the schema.


Deprecated Endpoints

Deprecated

Use instead

GET /v1/documents/{id}

GET /v1/patients/documents/{id}

PUT /v1/documents/{id}

PUT /v1/patients/documents/{id}

GET /v1/documents/{id}/download

GET /v1/patients/documents/{id}/download

GET /v1/document-types/dictionary

GET /v1/document-types

GET /v1/patient-note-subjects/dictionary

GET /v1/note-subjects/dictionary

GET /v1/order-note-subjects/dictionary

GET /v1/note-subjects/dictionary

GET /v1/orders/{orderId}/tracking

GET /v1/orders/{orderId}/items

GET /v1/orders/{orderId}/tracking/{trackingId}

GET /v1/orders/{orderId}/items/{itemId}

PUT /v1/orders/{orderId}/tracking/{trackingId}

PUT /v1/orders/{orderId}/items/{itemId}

PUT /v1/orders/{orderId}/tracking/{trackingId}/status

PUT /v1/orders/{orderId}/items/{itemId}/status

DELETE /v1/orders/{orderId}/tracking/{trackingId}

DELETE /v1/orders/{orderId}/items/{itemId}

POST /v1/patients/{patientId}/custom-fields

Send custom fields with PUT /v1/patients/{id}

PUT /v1/patients/{patientId}/custom-fields/{fieldId}

Send custom fields with PUT /v1/patients/{id}

DELETE /v1/patients/{patientId}/custom-fields/{fieldId}

Send custom fields with PUT /v1/patients/{id}

PUT /v1/orders/{orderId}/custom-fields/{fieldId}

Send custom fields with POST /v1/patients/{patientId}/orders or PUT /v1/patients/{patientId}/orders/{id}

DELETE /v1/orders/{orderId}/custom-fields/{fieldId}

Send custom fields with PUT /v1/patients/{patientId}/orders/{id}

PUT /v1/invoices/{invoiceId}/custom-fields/{fieldId}

PUT /v1/invoices/{invoiceId}/custom-fields

DELETE /v1/invoices/{invoiceId}/custom-fields/{fieldId}

PUT /v1/invoices/{invoiceId}/custom-fields

POST /v1/patients/{patientId}/payments

POST /v2/payments

GET /v1/patients/{patientId}/rentals

GET /v2/patients/{patientId}/rentals

GET /v2/orders/{id}/cost-sharing

GET /v3/orders/{id}/cost-sharing

GET /v1/users/list

GET /v1/users

GET /v1/purchase-orders/{purchaseOrderId}/audit/{auditId}

No direct replacement


Deprecated Request Fields

These fields still appear in request models but should no longer be used.

Endpoint

Deprecated field

Use instead

POST /v1/patients/{patientId}/orders

General.Products

General.Items

POST /v1/patients/{patientId}/orders

General.Items[].Count

General.Items[].QuantityInBaseUnits

POST /v1/patients/{patientId}/orders

General.HospitalDischarge

General.Delivery.HospitalDischarge

PUT /v1/patients/documents/{id}

TypeId

DocumentTypeId

POST / PUT patient notes

Description

Text

POST /v1/patients/{patientId}/documents (response)

Id

PatientDocumentId

⚠️ Two deprecated fields are still required.Description on patient notes and TypeId on document updates are marked deprecated but are still required by the request model. Until that changes, send them with the same value as their replacement (Text and DocumentTypeId).

Also Deprecated (see Swagger for current guidance)

  • Invoices:PriorAuthNumber on invoice options and service lines; CreatedOn / ModifiedOn on the invoice list filter; drug Code / Ndc on service lines

  • Products:BundleOptions, SerializedOptions, NonSerializedOptions, DropShipInfo, PreferedDeliveryMethod, PurchaseVendorId

  • Referring providers:ContactPerson, SalesAgentId

  • Vendors:DropShipIntegrationType


Staying Current

  • Check Swagger before you build. If an endpoint or field is struck through, use its replacement.

  • Review your integration periodically. New deprecations are added as the API evolves.

  • Handle new response fields gracefully. We add fields to responses over time; your code shouldn't break when that happens.


Related articles

Did this answer your question?