Search
K

Best Practices

Onboarding and Adding New NPNs to Your Subscribed Population

Due to the nature of data availability, we recommend that NPNs remain subscribed for the duration of time that any NIPR data about the NPN is needed.

Benefits of subscribing:

  • Performance: Subscribed NPNs return data quickly (P90 <1s), while non-subscribed NPNs can take over 10s.
  • Simplicity: Simplifies calling patterns and available options.

Initial Onboarding

Use a PUT call to /subscriptions to onboard your subscribed NPN population.

Example:

PUT /subscriptions

If your NPN population exceeds 50,000, we recommend reaching out to your AgentSync Customer Success Manager before "go-live." They can help streamline the onboarding process so that on Day 1, all relevant license, appointment, and other NIPR data is immediately available.

Ongoing Subscriptions

Subscriptions can be maintained using the /accounts/subscriptions endpoint.

Best practice:

  • Use a PUT call to /subscriptions whenever you need to subscribe a new NPN.
  • This allows AgentSync to request and process data from NIPR ahead of subsequent calls, reducing latency.

Example:

PUT /subscriptions

Subscribing an NPN in advance ensures that subsequent requests (e.g., GET /v2/entities/{NPN}/licenses) return faster.

Maintaining Producer Updates for Your Subscribed Population

Because of the volume of data requested, do not pull the full dataset daily. This may cause:

  • Performance degradation
  • AgentSync rate limiting
  • Large latencies
  1. Make an initial request for the NPN to pull the full dataset.
  2. Persist this data in your system.
  3. On a daily basis, use the producersync.updates_available webhook event to trigger API calls.
  4. Use the updatedSince query parameter with today's date (this date will increment automatically).
  5. This significantly reduces redundant information.
  6. If not using the webhook event, set updatedSince = (today's date - 1) to account for potential NIPR update delays.
  7. Process changes and update your persisted data store.

Example 1: Daily License Updates

Assumption: The customer has already made the initial call to pull license data for each NPN and persisted it.

Steps:

  1. Call: 
    GET /v2/licenses?updatedSince=yyyy-mm-dd
    • With webhooks → use today's date
    • Without webhooks → use today's date - 1
  2. Process paginated data and update the relevant NPNs.
  3. Repeat this process daily.

Example 2: Daily Appointment Updates

Assumption: The customer has already made the initial call to pull appointment data for each NPN and persisted it.

Steps:

  1. Call: 
    GET /v2/appointments?updatedSince=yyyy-mm-dd
    • With webhooks → use today's date
    • Without webhooks → use today's date - 1
  2. Process paginated data and update the relevant NPNs.
  3. Repeat this process daily.

Note: Always increment the date provided (today or today-1). This ensures no missed updates.