Overview

​

Authentication

All API endpoints are authenticated using Bearer tokens. In order to generate a token, you should go to the Silna Portal and create a token associated with your provider or MSO. If you are not a Silna customer, please visit our website to learn more about our services and set up a demo!

​

Rate Limiting

We support rate limiting on all our APIs. By default, all APIs are limited to 120 requests per minute, except for the file upload API which is limited to 60 requests per minute. If you want to request a rate limit increase, please email us at engineering@silnahealth.com.

If our API is rate-limiting your request, then we will return a 429 status code with the following response body:

{
  "message": "Rate limit exceeded. Please wait {X} seconds before trying again."
}

We also return response headers for all requests with the following information:

• X-RateLimit-Limit:The maximum number of requests you’re permitted to make per minute for the requested API.
• X-RateLimit-Remaining: The number of requests remaining in the current rate limit window.
• X-RateLimit-Reset: The time at which the current rate limit window resets in UTC epoch seconds.
• Retry-After: The number of seconds to wait until you can send another request. This will be 0 in all cases except when you get a 429 status code.

​

Source Ids (External Ids/Client Ids)

We support source ids for some of our resources. This is useful if you want to associate a Silna resource with an id in your system and not have to save the Silna Id. It is also useful if you want to send idempotent put requests or search for resources by your id.

We support search by source_id for any api with a source_id query parameter, such as:

• Providers
• Provider Service Locations
• Patients

We support creation of resources with a source_id for any api with a source_id field in the request body, such as:

• Create Patient
• Create or Update Patient

When searching by source ids, you can search for resources without a source_id by passing in null for the source_id query parameter.

​

Idempotent Requests

We support idempotent requests through two mechanisms: PUT APIs and the Idempotency-Key header.

​

PUT APIs

For PUT APIs, you are required to send a source_id in the request body. If you create another resource with the same source_id, we will update the existing resource with the new data. If the resource does not exist, we will create a new resource. These APIs are useful if you don’t want to worry about storing Silna resource ids in your system.

If you want to use these APIs and you already have patient data in Silna (say you onboarded to the web app first), then we will need to backfill all source_ids/ehr ids for your providers, provider service locations, patients, and patient plans (basically every resource that you want to use the PUT APIs for).

1. For providers and provider service locations, you will provide us a csv with these columns: source_id, provider_name/service_location_name
2. For patients, you will provide us a csv with these columns: source_id, first_name, last_name, dob
3. For patient plans, 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.

Once you provide these to us, we will perform the backfill. We do not recommend that you use the PUT APIs until the backfill is complete. Doing so could result in duplicate or archived patients, patient plans, and benefits checks.

​

Idempotency Keys

For APIs which accept an Idempotency-Key header, you can pass a unique key for each request (up to 255 characters). If you make the same request with the same Idempotency-Key, we will return the same response as the first request. This is useful for scenarios where you want to ensure that a request is only processed once. It’s important to note the following caveats with idempotency keys:

1. We will only support idempotency keys for 2XX responses. If you get a 4XX or 5XX response, then you can try again with the same key.
2. We support idempotency keys for 30 days. After 30 days, the key will be removed from our system.
3. If you make a request with an idempotency key that has already been used but with a different request body or parameters, we will consider this improper usage and return an error (400 status code).

​

Errors

All our errors will return a JSON response with the following format:

{
  "message": "{MESSAGE}"
}

Some of our errors, like the authentication error (401) will also return a type field. This helps distinguish between different types of unauthorized errors.

{
  "message": "{MESSAGE}",
  "type": "{TYPE}"
}

Below are the errors returned by our API

• 400: Bad Request
• 401: Unauthorized
• 404: Not Found
• 413: Request Entity Too Large
• 429: Rate Limit Exceeded

​

Pagination

Some of our APIs support pagination. We use keyset pagination, so you can pass in query parameters like ending_before, starting_after and limit to iterate through the data. The valid values for limit are between 1 and 100.

​

Ending_Before

A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a request to a paginated api and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar.id in order to fetch the previous page of the list.

​

Starting_After

A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a request to a paginated api and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo.id in order to fetch the next page of the list.

​

Response

The response will include a has_more field which will be true if there are more objects to fetch. There are also last_id and first_id fields which will be the object ID of the last and first object in the list respectively. All the objects will be in the records field.

{
  "records": [],
  "has_more": true,
  "first_id": "0194a4ed-130d-775b-81fd-ca2b4eb618ce",
  "last_id": "0194a4ed-501d-7790-802e-404c23617954"
}

​

Test Accounts

If you would like a test account for use in your development environments, please reach out to us at engineering@silnahealth.com or over slack and we will create one for you.

​

Common Use Cases

​

Creating Benefit Check for a New Patient

To create a benefit check, you will need to do the following steps:

1. Follow the guide for Patient Creation to create a new patient.
   • You can also use the Create or Update Patient API
2. Use the patient_id from the response above to create a patient plan by following the guide for Patient Plan Creation.
   • You can also use the Put Patient Plan API.
3. Use the patient_plan_id from the response above to create a benefit check by following the guide for Benefit Check Creation.
4. It can take some time for Silna to complete a benefit check. We recommend polling the benefit check status by calling the Get Benefits Check API (with the benefits_check_id returned by the above API call). Terminal states for a Benefits Check are COMPLETE and WITHDRAWN.
5. Once the benefits check is complete, you can get the benefits check pdf report by calling the Get Benefits Check Report API and then calling the Get File API with the file_id from the response.

​

Creating a Benefit Check for an Existing Patient

To create a benefit check for an existing patient, you will take the same steps as above with the below modifications.

• Instead of using the Create Patient API, you will use the Update Patient or Create or Update Patient API if you need to update any patient information. If you are storing the Silna patient_id in your system, then you can use the Update Patient API. If you are using your own id (source_id), then you should use the Create or Update Patient API. If this state of the patient in our system is unknown to you, then use the Create or Update Patient API.
• If you want to create a benefits check for a new plan, you will need to follow the guide for Patient Plan Creation. If it’s for an existing plan, you will use the Get Patient Plans API or PUT Patient Plan API . Again, if the state of the patient plan in our system is unknown to you, then use the Create or Update Patient Plan API.