Skip to main content
PUT
/
public
/
v1
/
patient-plans
Put Patient Plan
curl --request PUT \
  --url https://api.silnahealth.com/public/v1/patient-plans/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "member_number": "<string>",
  "payor_entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "source_id": "<string>",
  "patient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "plan_order_number": 123,
  "group_number": null,
  "start_date": null,
  "end_date": null,
  "insurance_type": null,
  "insurance_card_file_id": null,
  "insurance_card_back_file_id": null,
  "conflict_behavior": "REPLACE",
  "deduplication_strategy": "MEMBER_NUMBER"
}
'
{
  "patient_plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
The default behavior of this API has destructive properties! If you have an existing primary plan for a patient and you create a new primary plan for the same patient, the existing primary plan will be deleted/archived and all in progress benefits check and prior authorizations will be withdrawn! If you want to protect against this behavior, we recommend setting conflict_behavior=RAISE_ERROR.

​
Behavior Overview

This API has two flows: update and create. We trigger the update flow if we find a plan for the input patient with a matching source_id or we determine the requested plan to be a duplicate. Else we trigger the create flow. Since all fields are immutable on the patient plan record except for the source_id, we will only update the source_id field in the case when we determine the patient plan to be a duplicate. This means that in the case of source_id match, this API will make no updates and will just return the found patient plan.

​
Patient Plans Deduplication

If there is no source_id match, then we will run our deduplication logic. This is necessary to prevent accidental archival of existing patient plans in the case when source_ids might be configured incorrectly. By default, our deduplication logic will just check to see that there is no existing plan for the input patient with the same member number. If there is an existing patient plan with the same member number, we go to the update flow as described above. If not, we go to the create flow. Clients can modify this behavior by setting deduplication_strategy. When you set deduplication_strategy=MEMBER_NUMBER_AND_PAYOR, we use both the passed in payor_entity_id and member_number to determine if it is a duplicate. So, we only go to the update flow if both payor_entity_id and member_number match an existing patient plan for the input patient. Else we go to the create flow.

​
Handling Conflicts

Using the conflict_strategy field allows you to configure whether we want to automatically replace an existing plan if we determine that the source_ids are different and that the request is not for a duplicate plan.
  • The default is REPLACE and will result in the deletion/archival of the existing plan
  • RAISE_ERROR will return a Conflict Error (http status of 409)
  • RAISE_ERROR_ON_AUTH_WITHDRAWAL will return a Conflict Error (409) only if replacing the plan would lead to withdrawing an in progress Prior Authorization. This is a good flag to pass if your system allows edits to member numbers on existing plans and you have an implementation which always propagates your system’s changes into Silna. Ideally, you shold design a solution which does not require this.

​
Source Ids

Source Ids allow you to control when plans go through the update flow or the create flow. As a result, it is probably the most critical part of integrating with this API. In this section, we will go in depth on two approaches: Forcing Replacement on Member Number or Payor changes and Forcing Replacement on just Member Number changes. Please be aware that these are not the only options and you should reach out if you want to discuss another solution for your needs!

​
Forcing Replacement on Member Number or Payor Changes

If your system’s “Patient Plan” record is mutable and allows updates to the member_number or payor, we recommend using a source_id format which includes these two fields (ex. {YOUR_SYSTEMS_PATIENT_PLAN_ID}-{MEMBER_NUMBER}-{PAYOR_ID}). This will ensure that if either member_number or payor changes, we will create a new plan for the patient during a PUT Patient Plan call. If your system’s “Patient Plan” record only allows updates to the member_number (i.e. you would create an entirely new plan when changing the insurance), we recommend using a source_id format which includes the member_number field (ex. {YOUR_SYSTEMS_PATIENT_PLAN_ID}-{MEMBER_NUMBER}). This will ensure that if the member_number changes, we will create a new plan for the patient during a PUT Patient Plan call. If your system has the same immutability guarantees as Silna, then you can use a source_id that is just your systems id for the “Patient Plan” record (ex. {YOUR_SYSTEMS_PATIENT_PLAN_ID}). If you want to go down this route, you should set deduplication_strategy=MEMBER_NUMBER_AND_PAYOR. You should consider setting conflict_strategy=RAISE_ERROR_ON_AUTH_WITHDRAWAL if your system allows minor updates to patient plans and you still plan on calling Silna during that flow.

​
Forcing Replacement on Just Member Number Changes

  • Use a source_id that is just your systems id for the “Patient Plan” record (ex. {YOUR_SYSTEMS_PATIENT_PLAN_ID}) if you have the same immutability guarantees as Silna
  • If you don’t have the same immutability guarantees, then use a member number like {YOUR_SYSTEMS_PATIENT_PLAN_ID}-{MEMBER_NUMBER}.
If you want to go down this route, you should set deduplication_strategy=MEMBER_NUMBER. You should consider setting conflict_strategy=RAISE_ERROR_ON_AUTH_WITHDRAWAL if your system allows minor updates to patient plans and you still plan on calling Silna during that flow.

​
Why would I choose one over the other?

We recommend the first approach as it handles more complex cases where the different plans can have the same member number. This is common with Medicaid MCOs and plans which use SSNs. The downside of this approach is that it can lead to more patient plan deletions/archivals. The second approach could be a good choice if you care more about preventing accidental deletion/archival of plans and are fine with some workflows still being handled in the Silna application.

​
Integration Notes

Before Integrating with this API and if you already onboarded to the Silna web app with active patients, we want to backfill all source ids for your existing patient plans. For this, you will provide us a csv with these columns: source_id, patient_source_id, plan_order_number, member_id. Here, the plan_order_number will be 1 if the primary plan, 2 if the secondary plan, etc.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
Request schema for updating a patient plan

Request schema for updating a patient plan

​
member_number
string
required
Required string length: 2 - 80
​
payor_entity_id
string<uuid>
required
​
source_id
string
required

Unique identifier for the patient plan. This is generated and supplied by API clients

​
patient_id
string<uuid>
required
​
plan_order_number
integer
required

The order number of the plan (1 for primary, 2 for secondary, etc)

​
group_number
string | null
Required string length: 2 - 80
​
start_date
string<date-time> | null
​
end_date
string<date-time> | null
​
insurance_type
enum<string> | null

The type of insurance

Available options:
COMMERCIAL,
MEDICARE,
MEDICAID,
REGIONAL_CENTER,
WORKERS_COMPENSATION,
AUTO_INSURANCE
​
insurance_card_file_id
string<uuid> | null

The file ID corresponding to the front of the insurance card

​
insurance_card_back_file_id
string<uuid> | null

The file ID corresponding to the back of the insurance card

​
conflict_behavior
enum<string> | null
default:REPLACE

The behavior to take when there is a conflict with an existing patient plan.REPLACE (default) will replace the existing plan (this will halt all in progress benefits checks and prior authorizations for the plan). RAISE_ERROR will raise an error if there is a conflict. RAISE_ERROR_ON_AUTH_WITHDRAWAL will raise an error if there are active prior authorizations that would be withdrawn. The default behavior is REPLACE

Available options:
RAISE_ERROR,
REPLACE,
RAISE_ERROR_ON_AUTH_WITHDRAWAL
​
deduplication_strategy
enum<string> | null
default:MEMBER_NUMBER

The strategy to use for deduplicating patient plans. MEMBER_NUMBER (default) checks only the member number. MEMBER_NUMBER_AND_PAYOR checks both member number and payor entity for deduplication.

Available options:
MEMBER_NUMBER,
MEMBER_NUMBER_AND_PAYOR

Response

Response schema for creating a patient plan

Response schema for creating a patient plan

​
patient_plan_id
string<uuid>
required