Nirvana Coverage API Integration Best Practices

Last Updated: June 2025

📝 Request Parameters

payer_id

• Must correspond to a payer that Nirvana recognizes.
• Maintain a mapping table from your EHR’s payer IDs to Nirvana’s accepted payer_id values.
• Recommendation: Collaborate with your Customer Success Manager to build and validate this mapping table before development.

provider_npi

• Preferred: Use the group NPI for best results.
• May be hardcoded, though not all payers support this.
• Best practice: Allow flexibility to switch between group and individual NPI based on payer_id.
• Some payers are more performant with individual (rendering) NPI.

member_first_name, member_last_name, member_id, member_dob

• Provide demographic details for the patient, not the policyholder (important for dependents under 18).
• member_first_name and member_last_name are optional but improve result quality.

provider_session_cost

• Required for accurate calculation of member_obligation.
• Pass in the allowable rate in cents.
• If allowables are unavailable:
  • Alternative: Hardcode a typical session cost (commonly between 10000 and 50000 cents).
  • Note: This may reduce accuracy, but Nirvana will still return:
    • copayment
    • coinsurance
    • remaining_deductible
    • remaining_oop_max
    • benefit_structure

📦 Batching Requests

When to Run

• Schedule batch checks overnight, ideally between 11 PM – 4 AM ET to minimize disruption.

Rate Limiting

• Max rate: 50 checks per minute
• Exceeding this limit will return a 429 error for all subsequent checks within a 60-second window.

🔁 Retry Logic

NPI Retry (400 status code)

• 400 errors related to credentialing can often be resolved by switching NPIs:
  • If the initial request used group NPI, retry with individual NPI.
  • If the initial request used individual NPI, retry with group NPI.
• Most effective when the initial attempt uses rendering provider NPI.

Payer Retry (502 status code)

• A 502 indicates payer downtime, which is usually temporary.
• Retry the request after 60 minutes.
• Limit retries to 1 per patient (2 attempts total).

📤 Response Parameters

telehealth

• Use this object for virtual appointments.
• Includes:
  • copay
  • coinsurance
  • benefit_structure
  • member_obligation specific to telehealth
• Note: Deductible and out-of-pocket max (oop_max) are typically consistent between in-person and virtual visits.

third_party_payer

• Indicates that benefits are administered by a third party (e.g., carve-outs).
• Claims are often filed with this third-party payer.