Skip to main content

Prior Authorizations via API

Record payer prior authorizations so they're applied to invoices automatically.

How Authorizations Work

A prior authorization ties a payer's approval (an auth number) to a patient, for either a product or one or more HCPCS codes, with an approved period, units, and amount.

When invoices are created for that patient, payer, and product or HCPCS, NikoHealth can apply the authorization automatically and release invoices that are on hold waiting for an authorization.


Before You Start: Lookups

What you need

Endpoint

Patient ID

GET /v1/patients

Payer

GET /v1/payers/dictionary

Product (product authorizations)

GET /v1/products


Create an Authorization

POST /v1/authorizations

Fields

Field

Required

Notes

PatientId

✅

Numeric patient ID, sent as a number, e.g. 10000105

PayerId

✅

From GET /v1/payers/dictionary

AuthNumber

The payer's authorization number

AuthorizationType

Product or Hcpcs

ProductId

When AuthorizationType is Product

Hcpcs

When AuthorizationType is Hcpcs, e.g. ["E0601", "A7030"]

TypeId

Price option type: Purchase, Rental, or Retail

Period.From / .To

Approved date range, YYYY-MM-DD

Units

Approved units

Amount

Approved amount

Modifiers

Level1 to Level4

Notes

Free text

Invoice Automation Options

Field

What it does when true

DoNotAutoApplyOnInvoices

Stops this authorization from being applied to invoices automatically

UpdateInvoicesOnHoldForAuthorizationRequired

Updates invoices on hold for Authorization Required with this authorization

UpdateInvoicesOnHoldForAuthorizationExpired

Updates invoices on hold for Authorization Expired with this authorization

Example: product authorization

POST /v1/authorizations
{
"PatientId": 10000105,
"PayerId": "d0bd30210e89f1745e45c3b14d0440512c5a8234",
"AuthNumber": "CPM123456789",
"AuthorizationType": "Product",
"ProductId": "X98HS36WD42EJ57YT25L",
"TypeId": "Purchase",
"Period": { "From": "2026-11-01", "To": "2027-01-31" },
"Units": 24,
"UpdateInvoicesOnHoldForAuthorizationRequired": true
}

Example: HCPCS authorization

{
"PatientId": 10000105,
"PayerId": "d0bd30210e89f1745e45c3b14d0440512c5a8234",
"AuthNumber": "AUTH-55512",
"AuthorizationType": "Hcpcs",
"Hcpcs": ["E0601"],
"TypeId": "Rental",
"Period": { "From": "2026-11-01", "To": "2027-10-31" },
"Modifiers": { "Level1": "RR" }
}

Response: 201 Created

{ "Id": "02564fe731dbaa0b6e2132435a15c0e5adfa6ad9" }

Search Authorizations

GET /v1/authorizations

Filter

Notes

patientId / payerId / productId

authNumber

hcpcs

status

e.g. active or expired

expiryPeriod.from / .to

Expiry date range

createdOnRange.from / .to, modifiedOnRange.from / .to

includeArchived

pageIndex / pageSize / selectCount

Paging

{
"Count": 1,
"Items": [
{
"Id": "02564fe731dbaa0b6e2132435a15c0e5adfa6ad9",
"AuthNumber": "CPM123456789",
"AuthorizationType": { "Id": "Product", "Name": "Product" },
"Status": { "Id": "2", "Name": "Expired" },
"ExpiryDate": "2026-11-21T00:00:00",
"Patient": { "Id": 10000105, "Name": { "FirstName": "Jane", "LastName": "Doe" } },
"Payer": { "Id": "d0bd30210e89f1745e45c3b14d0440512c5a8234", "Name": "Example Payer" },
"Product": { "Id": "X98HS36WD42EJ57YT25L", "Name": "Foam Dressing 6x6" },
"DoNotAutoApplyOnInvoices": false,
"Archived": false
}
]
}

Get one authorization: GET /v1/authorizations/{id}. Also returns Units, Amount, Period, Modifiers, and Notes.

The API can create and view authorizations, but it has no update or delete endpoint. Make those changes in the NikoHealth UI.


Authorizations on Invoices

You can also send prior auth numbers directly on an invoice, at the claim level (Options.PriorAuthorizations) or the service-line level (ServiceLines[].PriorAuthorizations).


Common Errors

Code

Meaning

400

Invalid request, e.g. a missing PatientId or PayerId, or PatientId sent as a string

401

Token missing, expired, or invalid

403

You don't have permission to access this resource

404

Authorization, patient, payer, or product not found

429

Too many requests


Related articles

Did this answer your question?