Silna OpenAPI Specification

View the OpenAPI specification

​
Key Silna Concepts

Patient Plan: A Patient Plan in Silna represents a patients insurance plan. In Silna Patient Plans are immutable for customers. If you ever want to update a patient plan, you have to archive the existing one and create a new plan.

Eligibility Checks: Silna automatically creates eligibility checks for active patients periodically (usually at the first of every month). An eligibility check is created per patient plan belonging to an active patient. An eligibility check will say whether a patient plan is still active.

Benefits Check: Silna supports on demand benefits checks for patient plans. Additionally, Silna automatically create benefits check at the first of every year for active patients’ patient plans. A benefits check will say whether a patient plan is active as well as other important details such as the copay, deductible, etc.

Prior Authorization: Silna supports on demand prior authorizations for patient plans. An approved prior authorization contains which treatment codes the payor approved, the reference number, the approval letter, etc.

Escalations: When Silna requires additional information or action from a provider when completing an eligibility check, benefits check, or prior authorization we will raise an escalation in the Silna web app. Providers must go through the Silna web app to resolve escalations.

​
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:

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

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).

​
Delete APIs

All our delete APIs archive the resource. We do not completely delete the record from our system.

​
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.

​
Testing

We recommend testing your implementation in a test account before turning on your integration in production. You can create an API key in your test account to get started! You can test scenarios like creation patients, patient plans, benefits checks, prior authorization, etc. When it comes to testing polling for completion, you will need to reach out to Silna over slack to move benefits checks, prior authorizations, eligibility checks, etc to a Completed state.

​
Implementation Planning

We recommend a two phase approach to building to the Silna API. In Phase One, you should build to our patient, patient plan, and benefits check APIs. In Phase Two, you should build to our prior authorization API. When you turn on an integration, you should turn it on all at once or not at all. For example, if you are working on Phase One and you have only built out creating patients in Silna, you should not turn on the integration as it does not make sense to support creating patients in Silna without patient plans or a benefits check

​
Phase One Checklist

  1. Determine Payor Strategy
  2. Build Creating/Updating/Getting Patients in Silna
  3. Build Creating/Updating/Getting Patient Plans in Silna
  4. Build Creating a Benefits Check in Silna (and polling for completion)
  5. Backfill source_ids (if using PUT APIs)

Please reference these guides when integrating with these apis

​
Phase Two Checklist

  1. Build a system to translate your document tags to Silna document tags or adopt Silna’s document standard
  2. Build Creating Prior Authorizations in Silna (and polling for completion). You should re-use your patient and patient plan implementations for this.

You can read more about integrating with the prior authorization API here: Prior Authorization Creation.