Skip to main content

Moving from Sandbox to Production

A checklist for taking your NikoHealth API integration live.

Your sandbox and production environments are completely separate. They have different URLs, credentials, reference data, and webhook subscriptions. Nothing carries over automatically.


1. Update Your URLs

Sandbox

Production

Token URL

https://{sandbox-domain}.nikohealth.com/api/identity/connect/token

https://{production-domain}.nikohealth.com/api/identity/connect/token

API base URL

https://{sandbox-domain}.nikohealth.com/api/external

https://{production-domain}.nikohealth.com/api/external

💡 Store the domain in configuration, not in code, so you can switch environments without a code change.


2. Use Your Production Credentials

  • Request your production Client ID and Client Secret from your NikoHealth contact. Sandbox credentials don't work in production.

  • Store production secrets in a secure secrets manager or environment variables. Never commit them to source control or expose them in client-side code.

  • Limit who has access to production credentials.


3. Re-Map Every Reference ID

⚠️ This is the most common go-live issue. Reference IDs in your sandbox are different from the ones in production, even when the names match.

Look up each of these in production and update your mappings:

Reference Data

Lookup Endpoint

Used In

Service locations

GET /v1/organization/locations

Patients, orders, eligibility

Payers

GET /v1/payers/dictionary

Insurances, eligibility

Payer plans

GET /v1/payers/{payerId}/plans/dictionary

Insurances, eligibility

Products

GET /v1/products

Orders, prescriptions

Referring providers

GET /v1/referring-providers

Orders, prescriptions

Document types

GET /v1/document-types

Patient documents

Note subjects

GET /v1/note-subjects/dictionary

Patient notes

Order tags / patient tags

GET /v1/order-tags, GET /v1/patient-tags

Orders, patients

Custom fields

GET /v1/custom-fields

Patients, orders, invoices

Drop-ship accounts

GET /v1/orders/dropship/accounts

Drop ship

Best practice: Don't hard-code IDs. Look them up by name, NPI, or code at startup or on a schedule, or keep a separate mapping table for each environment.

Fixed enum values, such as Active, HomeDelivery, or DurableMedicalEquipment, are the same in every environment. Record IDs are what change.


4. Make Sure Reference Data Exists in Production

Records that can only be created in the NikoHealth UI must be set up in production before go-live:

  • Service locations

  • Payers and payer plans

  • Any products, document types, tags, or custom fields your integration depends on

Work with your NikoHealth implementation team to confirm production setup matches what you tested in the sandbox.


5. Re-Subscribe Your Webhooks

Webhook subscriptions don't carry over from the sandbox.

  • Create production webhooks with POST /v1/webhooks, pointing to your production endpoint.

  • Save each new Secret. Production secrets are different, and each one is only shown once.

  • Update your endpoint to validate signatures with the production secret.

  • Remove or deactivate sandbox webhooks that point at production systems.

  • Never point production webhooks at public testing tools such as webhook.site.


6. Insurance Eligibility: Enrollment and Real Data

  • Confirm payer enrollment for each payer you'll check eligibility with. Some payers require enrollment before you can submit checks.

  • Never send fake or test data in production. Some payers, especially CMS (HETS), prohibit test transactions with fictitious data and can block or revoke access.

  • Remember that eligibility checks have per-transaction fees in production.


7. Harden Your Integration

  • Token handling: Cache tokens and refresh them before they expire (20 minutes), rather than requesting one per call.

  • Error handling: Handle 400, 401, 403, 404, and 429 explicitly. Retry 429 and 5xx with an increasing delay. See HTTP Status Codes.

  • Duplicates: Search for existing patients before creating new ones.

  • Logging: Log request IDs, status codes, and error messages, but never log PHI, tokens, or secrets.

  • Monitoring: Alert on spikes in 4xx/5xx responses and failed webhook deliveries.


8. Plan the Cutover

  • Agree on a go-live date and time with your NikoHealth contact.

  • Decide whether you need an initial data load (for example, existing patients) and how you'll avoid duplicates.

  • Run a small pilot first: a few real records, end to end, verified in the NikoHealth UI.

  • Have a rollback plan, such as a feature flag that pauses your integration.

  • Turn off sandbox jobs that might accidentally write to production.


Go-Live Checklist

☐ Production URLs configured

☐ Production credentials stored securely

☐ All reference IDs re-mapped to production

☐ Required reference data set up in production

☐ Production webhooks created and secrets saved

☐ Payer enrollment confirmed (if using eligibility)

☐ No test data in production

☐ Error handling, retries, and pagination verified

☐ Deprecated endpoints replaced

☐ Pilot completed and verified


Related articles

Did this answer your question?