Skip to main content

​
Plan Immutability Design

Patient plans are intentionally designed to be immutable after creation—with the exception of the source_id field, plan attributes cannot be modified through direct API updates. This design ensures data integrity and prevents inconsistencies between patient plans and their associated verification records.

​
Update Strategies

When you need to modify patient plan information, you must replace the existing plan with a new one. Two approaches are available:

​
Approach 1: Managed Replacement (PUT API)

Use the PUT Patient Plan API with the conflict_behavior=REPLACE parameter to leverage automated lifecycle management. How It Works:
  1. Call PUT Patient Plan with the updated plan data and conflict_behavior=REPLACE
  2. Spike Care automatically archives the existing plan
  3. A new plan is created with the updated information
  4. The system applies platform-defined lifecycle rules
Advantages:
  • Simplified implementation—single API call handles the entire process
  • Automated application of platform lifecycle policies
  • Consistent behavior across integrations
Considerations:
  • Less granular control over the transition timing
  • Requires understanding of platform lifecycle policies

​
Approach 2: Manual Replacement (GET/DELETE/POST)

Orchestrate the replacement process explicitly using individual API operations. How It Works:
  1. Call GET Patient Plans to retrieve existing plan details
  2. Call DELETE Patient Plan to archive the target plan
  3. Call POST Patient Plan to create the new plan with updated information
Advantages:
  • Complete control over transition timing and sequence
  • Ability to implement custom logic between deletion and creation
  • Explicit handling of dependent verifications
  • Clearer audit trail of changes
Considerations:
  • Requires more integration code
  • Responsibility for handling edge cases rests with your implementation
  • Must manage dependent resources (verifications) explicitly

​
Recommendation

For most integrations, Approach 2 (Manual Replacement) provides better operational visibility and control. The PUT API approach is suitable when your requirements align precisely with Spike Care’s managed lifecycle policies. Review the PUT Patient Plan API documentation thoroughly before implementing managed replacement to ensure the automated behaviors match your needs.

​
Verification Status Tracking

Patient plans maintain references to the most recently completed verification activities, providing quick access to current plan status without querying verification endpoints.
​
latest_benefits_check
object
Contains details from the most recently completed benefit verification for this plan. This field remains null until at least one benefit verification has reached COMPLETE status. Updates automatically when newer verifications complete.
​
latest_eligibility_check
object
Contains details from the most recently completed eligibility verification for this plan. Similar to latest_benefits_check, this field is null until the first eligibility verification completes and updates automatically thereafter.
​
plan_eligibility_status
string
A derived status field representing the current plan eligibility based on the most recent verification (either benefit or eligibility check). When both verification types have completed, this field reflects whichever completed most recently. This provides a single field to determine current plan status without comparing timestamps.
These fields update automatically as verification processes complete—your integration does not need to manually maintain them.

​
Frequently Asked Questions

​
Can I modify member identification numbers after plan creation?

No. Member IDs (such as insurance policy numbers, member numbers, and subscriber IDs) cannot be changed after a patient plan is created. This immutability prevents potential misalignment between the plan record and existing verifications that reference those identifiers. If a patient’s insurance information changes (including member numbers), you must create a new patient plan with the updated information and archive the previous plan using one of the update strategies described above.

​
What happens to existing verifications when I replace a plan?

The behavior depends on your replacement approach: Manual Replacement (DELETE/POST): Existing in-progress verifications become orphaned when you delete the plan. Your integration should handle these records appropriately—either by withdrawing them explicitly or ensuring they complete before deleting the plan. Managed Replacement (PUT with REPLACE): The platform automatically withdraws all in-progress verifications for the old plan before creating the new one.

​
Should I archive old plans or delete them permanently?

All DELETE operations in the Spike Care API perform soft deletion (archival) rather than permanent deletion. Archived plans remain in the system for historical reference and reporting but are excluded from standard list queries. This ensures audit trail preservation while keeping active plan lists uncluttered.

​
How do I query for a patient’s active plans only?

The GET Patient Plans API returns active (non-archived) plans by default. To include archived plans in results, use the appropriate query parameter documented in the API reference.

​
Can I reuse a source_id after deleting a plan?

Yes. After archiving a plan, you can reuse its source_id for a new plan. This is particularly useful when using the PUT API pattern, as it enables true upsert semantics—the same source_id can refer to the current active plan regardless of how many times it has been replaced.

​
What fields ARE modifiable after plan creation?

Only the source_id field can be modified on an existing patient plan. This allows for correcting external identifier mappings without requiring plan replacement. All other plan attributes require the create-new/archive-old workflow described in this guide.