Migration to Certified v2 APIs

Overview

Netsmart has released new Certified v2 APIs to support the latest regulatory requirements including US Core IG 6.1.0, SMART App Launch 2.0.0, and Bulk Data Export 2.0.0. This guide helps developers migrate applications from Certified v1 APIs to the new v2 APIs.

Backwards Compatibility

The v2 APIs are designed to be backwards compatible with US Core 3.1.1, allowing for a smoother migration path while supporting the latest standards.

What's New in v2

Enhanced Standards Support

• US Core IG 6.1.0 - Updated from 3.1.1 with expanded data requirements
• SMART App Launch 2.0.0 - Enhanced security and authorization capabilities
• Bulk Data Export 2.0.0 - Improved bulk data access patterns

New Authorization Infrastructure

• Tenant-Specific URLs - Each CareConnect FHIR tenant now has dedicated authorization and FHIR base URLs
• New Developer Portal - Streamlined application registration and tenant authorization workflow
• Enhanced Security - Improved OAuth 2.0 implementation with SMART App Launch 2.0.0 features

Expanded System Access

The v2 System Access API consolidates all system-level (backend) access patterns, not just bulk data export. This means system access use cases previously using the v1 Patient Access API should migrate to the v2 System Access API.

Migration Paths

Patient Access API

v1 Patient Access API → v2 Provider Patient Access API

Aspect	v1	v2
Base URL	https://fhir.netsmartcloud.com/uscore/v1	https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}
Auth URL	https://oauth.netsmartcloud.com/	https://fhir.netsmartcloud.com/auth/{tenant-id}/oauth2/v1/
US Core	3.1.1	6.1.0 (backwards compatible with 3.1.1)
SMART Launch	1.0.0	2.0.0
Registration	Legacy Portal	New Developer Portal

Bulk Data Export API

v1 Bulk Data Export API → v2 Provider System Access API

Aspect	v1	v2
Base URL	https://fhir.netsmartcloud.com/uscore/v1/bulk-data	https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}
Auth URL	https://oauth.netsmartcloud.com/	https://fhir.netsmartcloud.com/auth/{tenant-id}/oauth2/v1/
Bulk Data IG	1.0.0	2.0.0
Use Cases	Bulk export only	All system access patterns including bulk export
Registration	Legacy Portal	New Developer Portal

System Access Use Cases

v1 Patient Access API (system scopes) → v2 Provider System Access API

If you were using the v1 Patient Access API with system/* scopes for backend integrations (not bulk export), you should migrate to the v2 System Access API which is designed for all system-level access patterns.

Migration Steps

Step 1: Register in New Developer Portal

The v2 APIs require registration through the new developer portal.

Production

1. Navigate to Developer Portal for Production
2. Create an account or sign in
3. Select Applications → Create Application
4. Complete the guided setup:
   • Type: Patient-facing application or System integration
   • Platform: Web server application or Mobile/Desktop application
   • Access: Provider APIs or Payer APIs
   • Authentication: Client Secret or Private Key JWT
   • Details: Application name, redirect URIs, etc.
5. Repeat for each tenant you need to access (one application per tenant)

Preview

1. Navigate to Developer Portal for Preview
2. Create an account or sign in
3. Select Applications → Create Application
4. Complete the guided setup:
   • Type: Patient-facing application or System integration
   • Platform: Web server application or Mobile/Desktop application
   • Access: Provider APIs or Payer APIs
   • Authentication: Client Secret or Private Key JWT
   • Details: Application name, redirect URIs, etc.
5. Repeat for each tenant you need to access (one application per tenant)

warning

Your v1 application credentials will NOT work with v2 APIs. You must register a new application in the new developer portal. Currently, each application can only be authorized for a single tenant, so you must register separate applications for each tenant you need to access.

Step 2: Request Tenant Authorization

After registering your application, request authorization for the tenant you need to access.

1. In the Developer Portal, select your application
2. Navigate to the Tenant Authorization tab
3. Search for and select the Organization (tenant)
4. Select Request Authorization
5. Wait for tenant owner approval
6. Once approved, the tenant name and ID will be displayed

Single Tenant Per Application

Currently, each registered application can only be authorized for a single tenant. If you need to access multiple tenants, you must register a separate application for each tenant.

info

As a third-party application developer, you will typically request access to healthcare organizations' tenants. Once authorized, you can retrieve the tenant ID from the developer portal to use in your API calls.

Step 3: Update Base URLs

Update all API calls to use tenant-specific URLs.

v1 Pattern:

https://fhir.netsmartcloud.com/uscore/v1

v2 Pattern:

https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}
https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}

Example Migration:

Patient Access

- GET https://fhir.netsmartcloud.com/uscore/v1/Patient/123
+ GET https://fhir.netsmartcloud.com/provider/patient-access/v2/43477c76-ceb6-47ed-81c8-1b7c0ae10ca6/Patient/123

System Access

- GET https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Group/456/$export
+ GET https://fhir.netsmartcloud.com/provider/system-access/v2/43477c76-ceb6-47ed-81c8-1b7c0ae10ca6/Group/456/$export

Step 4: Update Authorization Endpoints

Update OAuth 2.0 authorization and token endpoints to use tenant-specific URLs.

v1 Authorization Endpoints:

https://oauth.netsmartcloud.com/authorize
https://oauth.netsmartcloud.com/token

v2 Authorization Endpoints:

https://fhir.netsmartcloud.com/auth/{tenant-id}/oauth2/v1/authorize
https://fhir.netsmartcloud.com/auth/{tenant-id}/oauth2/v1/token

Example Authorization Request:

Patient Access

curl -X GET "https://fhir.netsmartcloud.com/auth/43477c76-ceb6-47ed-81c8-1b7c0ae10ca6/oauth2/v1/authorize?\
response_type=code&\
client_id=YOUR_CLIENT_ID&\
redirect_uri=https%3A%2F%2Fapp.example.com%2Fsmart%2Fredirect&\
scope=launch%2Fpatient%20openid%20fhirUser%20offline_access%20patient%2FPatient.rs&\
state=RANDOM_STATE&\
aud=https%3A%2F%2Ffhir.netsmartcloud.com%2Fprovider%2Fpatient-access%2Fv2%2F43477c76-ceb6-47ed-81c8-1b7c0ae10ca6&\
code_challenge=YOUR_CODE_CHALLENGE&\
code_challenge_method=S256"

System Access

curl -X POST "https://fhir.netsmartcloud.com/auth/43477c76-ceb6-47ed-81c8-1b7c0ae10ca6/oauth2/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=YOUR_SIGNED_JWT" \
  -d "scope=system/Patient.rs%20system/AllergyIntolerance.rs"

Step 5: Discover Tenant-Specific Endpoints

Use the SMART configuration or CapabilityStatement to discover OAuth endpoints for each tenant.

SMART Configuration:

GET https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/.well-known/smart-configuration

CapabilityStatement:

GET https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/metadata

Both responses include the authorization and token endpoint URLs for that specific tenant.

Step 6: Update Scope Syntax (Optional)

While v2 maintains backwards compatibility with v1 scope syntax, consider adopting SMART App Launch 2.0.0 scope patterns:

v1 Scope Examples:

patient/Patient.read
patient/Observation.read
system/Patient.read

v2 Enhanced Scope Examples (SMART 2.0.0):

patient/Patient.rs      # read + search
patient/Observation.cruds  # create + read + update + delete + search
system/Patient.rs

info

The v2 APIs support both v1 and v2 scope syntax for backwards compatibility.

Step 7: Test Against CapabilityStatement

Always retrieve and validate against the CapabilityStatement before making API calls.

curl -X GET "https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/metadata" \
  -H "Accept: application/fhir+json"

Verify:

• Supported resources match your requirements
• Search parameters are available
• Operations are supported
• Profiles align with your use case

Step 8: Update Error Handling

Review error responses as the v2 APIs may return different error structures aligned with SMART App Launch 2.0.0 and FHIR R4 specifications.

Key Differences

Tenant-Specific Architecture

v1: Single base URL for all tenants

https://fhir.netsmartcloud.com/uscore/v1

v2: Tenant-specific base URLs

https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}
https://fhir.netsmartcloud.com/auth/{tenant-id}/oauth2/v1/

Authorization Workflow

v1:

• Register once in legacy portal
• Request authorization via external form
• Use global OAuth endpoints

v2:

• Register in new developer portal
• Request tenant authorization directly in portal
• Use tenant-specific OAuth endpoints

System Access Consolidation

v1:

• Bulk Data Export API for bulk export only
• Patient Access API with system scopes for other backend use cases

v2:

• System Access API for ALL system-level access patterns
• Includes bulk export and other backend integrations

Backwards Compatibility

The v2 APIs maintain backwards compatibility with US Core 3.1.1 and SMART App Launch 1.0.0 patterns where possible:

✅ Compatible:

• US Core 3.1.1 profiles and resources
• SMART 1.0.0 scope syntax
• Standard FHIR R4 search parameters
• OAuth 2.0 authorization code flow
• Client credentials grant type

⚠️ Requires Updates:

• Base URLs (must use tenant-specific URLs)
• Authorization endpoints (must use tenant-specific auth server)
• Application registration (must use new developer portal)
• Tenant authorization (must request per-tenant access)

Testing Your Migration

1. Preview Environment

Test your migration in the preview environment first:

• Developer Portal: https://fhirtest.netsmartcloud.com/developers
• Base URL Pattern: https://fhirtest.netsmartcloud.com/provider/patient-access/v2/{tenant-id}
• Auth URL Pattern: https://fhirtest.netsmartcloud.com/auth/{tenant-id}/oauth2/v1/

2. Validation Checklist

Before migrating to production, verify:

• Application registered in new developer portal
• Tenant authorization approved for all required tenants
• Base URLs updated to tenant-specific format
• Authorization endpoints updated to tenant-specific format
• OAuth flow tested with new credentials
• CapabilityStatement retrieved and validated
• All API calls tested against preview environment
• Error handling updated for v2 responses
• Scope syntax validated (v1 or v2 format)

3. Parallel Operation

Consider running v1 and v2 integrations in parallel during migration:

1. Register v2 application and obtain authorization
2. Implement v2 integration alongside existing v1 integration
3. Test v2 integration thoroughly in preview and production
4. Gradually shift traffic from v1 to v2
5. Monitor for issues and rollback if needed
6. Deprecate v1 integration once v2 is stable

Getting Help

Documentation Resources

• Provider Patient Access API
• Provider System Access API
• Authorization Guide
• Registration Guide

Support

For migration assistance, contact Netsmart support:

• Developer Portal: Use the support contact in your developer portal account
• Documentation: Review the comprehensive API documentation for detailed guidance

Timeline and Deprecation

v1 API Lifecycle

While v1 APIs remain available, developers should plan to migrate to v2 APIs to take advantage of the latest features and regulatory compliance. Deprecation timelines will be communicated with advance notice.

Recommended Migration Timeline:

• Immediate: Begin planning and testing v2 migration
• Short-term (1-3 months): Complete registration and tenant authorization
• Medium-term (3-6 months): Implement and test v2 integration
• Long-term (6-12 months): Complete migration and deprecate v1 integration

Frequently Asked Questions

Do I need to re-register my application?

Yes. The v2 APIs use a new authorization infrastructure and developer portal. Your v1 credentials will not work with v2 APIs.

Can I use the same client_id for v1 and v2?

No. You must register a new application in the new developer portal and receive new credentials.

Will my v1 application stop working?

No immediate changes. v1 APIs remain operational, but migrating to v2 is recommended for latest features and compliance.

How do I find my tenant ID?

Once your application is authorized for a tenant, the tenant ID is displayed in the developer portal under your application's Tenant Authorization tab. The tenant ID is a UUID that identifies the specific CareConnect FHIR tenant you have been authorized to access.

Can I test v2 APIs without production access?

Yes. Use the preview environment at https://fhirtest.netsmartcloud.com/developers to test your integration before requesting production access.

What if I need access to multiple tenants?

Currently, each application registration can only be authorized for a single tenant. To access multiple tenants, you must register a separate application for each tenant in the developer portal. Each tenant owner must approve their respective application.

Are there any breaking changes in the FHIR resources?

The v2 APIs are designed to be backwards compatible with US Core 3.1.1. However, US Core 6.1.0 adds new required fields and search parameters. Review the CapabilityStatement for each tenant to understand specific capabilities.

How do I migrate bulk data export workflows?

Bulk data export moves from the v1 Bulk Data Export API to the v2 System Access API. The core workflow remains similar, but URLs and authorization must be updated to use tenant-specific endpoints.

Can I use SMART App Launch 1.0.0 patterns with v2?

Yes. The v2 APIs maintain backwards compatibility with SMART App Launch 1.0.0 while also supporting 2.0.0 features.

What happens if tenant authorization is revoked?

If a tenant revokes your application's authorization, API calls to that tenant will fail with authorization errors. You must request re-authorization through the developer portal.