​
Immutability

Patient Plans are immutable through the API. Once you create a Patient Plan, you will no longer be able to update it programmatically (except for updating source_id as this is a customer owned field). If you need to update a Patient Plan, you will need to first delete it and then create it again. You can use either of the below strategies to do this:
  1. If you have a source_id for the Patient Plan, you can use the PUT Patient Plan API to first replace the existing plan and then create a new one in the existing plan slot (primary, secondary, etc). You should pass in the conflict_behavior=REPLACE in the payload. You should be aware that replacing plans leads to the withdrawal of all in-progress benefits checks and prior authorizations on the replaced plan.
  2. If you want to use a safer approach or you don’t track source ids, you will want to do the following:
    1. Use the GET Patient Plans API to get the existing plans for a patient.
    2. Use the DELETE Patient Plan API to delete the plan you want to update. This will delete/archive the plan and withdraw all associated benefits checks and prior authorizations.
    3. Use the POST Patient Plan API to create a new plan for the patient.

​
Our Recommendation

Using the PUT Patient Plan API allows clients to use our manged lifecycle rules for patient plans. It can be quicker to implement but it can lead to accidentally archiving/deleting patient plans. We recommend you consult the documentation here closely to have success with this API. If you do not want to use our managed lifecycle plan rules or you want more control over when patient plans are deleted, we recommend you instead integrate with our POST, PATCH, DELETE, and GET APIs instead.

​
Tracking Latest Benefits and Eligibility

  1. lastest_benefits_check is populated with the latest completed benefits check. So, if the if you have not yet created any benefit checks against a patient plan, this field will be null until the benefit check that you create is complete. If there was a benefit check (Benefit Check A) completed against this plan (say two months ago) and you want to create a fresh benefit check (Benefit Check B), the latest_benefits_check will return Benefit Check A until Benefit Check B is complete.
  2. latest_eligibility_check behaves in a similar manner to the above. It will be null until the first eligibility check is complete and will return the latest completed eligibility check until a new one is complete.
  3. plan_eligibility_status is determined through a combination of the latest_benefits_check and latest_eligibility_check, whichever one was most recent

​
FAQ

​
What if I want to update the member number after I originally create the plan?

We do not support this because patient plans may have existing benefits checks, eligiblity checks, and prior authorizations. If you update the patient plan to a different member number, it may seem that that plan may be active when in fact it is not.