Getting Started with OAuth 2.0

OAuth 2.0 is an industry-standard protocol for authorization that allows users to grant limited access to their resources on one website to another website without sharing their credentials. It provides a secure and standardized way for applications to authenticate and authorize users.

Registering application

Before you can start using OAuth 2.0, you need to register your application with VerifyTreatment. Please send your registration request to [email protected] to obtain your client credentials, including a client ID and client secret.

Obtain an Authorization Grant

OAuth 2.0 supports multiple authorization flows, each designed for different use cases. VerifyTreatment limits 3rd party access to following flows:

  1. Authorization Code Flow: This flow is suitable for server-side applications that can securely store client secrets. It involves exchanging an authorization code for an access token.
  2. Client Credentials Flow: This flow is used by applications that need to access resources on behalf of themselves rather than a specific user. It involves directly exchanging client credentials for an access token.

Authorization Code Flow

The authorization code flow is a "three-legged OAuth" configuration. It involves three parties: the user (resource owner), the client (application), and the server (VerifyTreatment). Initially, the user obtains an authorization grant, which is then exchanged for an access token by the client.

Step 1: Authorization Request

The client initiates the flow by directing the user to the authorization endpoint. The client includes its client identifier, requested scope, local state, and a redirection URI to which the authorization server will send the user-agent back once access is granted (or denied).

Property Description
response_type code, client_credentials
client_id client identifier provided by VerifyTreatment
redirect_uri Where the user is redirected after successful log in
scope (optional) permissions you wish to request from the user, if none are defined default scopes will be used
state (optional) This parameter is optional but highly recommended. You should store the value of the CSRF token in the user’s session to be validated when they return.

Example Request:

GET

Step 2: User Authorizes Access

When the user clicks the link, they must first log in to VerifyTreatment, then will be prompted to authorize or deny the client's request to access data. If the user clicks authorize, VerifyTreatment redirects the user-agent to the client's redirection endpoint provided earlier. The redirection URI includes an authorization code and the client's local state.

Approved request:

Property Description
code authorization code
state the state parameter sent in the original request. You should compare this value with the value stored in the user’s session to ensure the authorization code obtained is in response to requests made by this client rather than another client application.

Denied request:

Property Description
error access_denied
error_description User+denied+the+request

Step 3: Exchange the Authorization Grant for an Access Token

Once you have obtained the authorization grant, you need to exchange it for an access token. The exact process depends on the chosen flow.

Authorization Code Flow:

Example Request:

POST
Content-Type: application/json
Property Description
grant_type Set to "authorization_code"
code The authorization code obtained in the previous step
client_id client identifier provided by VerifyTreatment
client_secret client secret provided by VerifyTreatment
redirect_uri Must match the redirect_uri used in the authorization request

Example Response:

Property Description
token_type bearer
id User id
access_token Access token
refresh_token Refresh token
expires_at Access token expiration time
scopes Requested scopes

Client Credentials Flow:

Example Request:

POST
Content-Type: application/json
Property Description
grant_type Set to "client_credentials"
client_id client identifier provided by VerifyTreatment
client_secret client secret provided by VerifyTreatment

Example Response:

Property Description
token_type bearer
id User id
access_token Access token
refresh_token Refresh token
expires_at Access token expiration time
scopes Requested scopes

Accessing Protected Resources

Once you have obtained an access token, you can use it to make requests to the API on a user’s behalf.

The access token must be sent as a Bearer token in the Authorization header of each request. The API will return a 401 Unauthorized response if the access token is missing or invalid.

Refresh Access Token

Access tokens have a limited lifetime specified by the expires_at field. If you attempt to use an expired token, you will receive a 401 Unauthorized response from the API. You can refresh an access token by using the refresh_token which is returned when the access token is generated.

Example Request:

POST
Content-Type: application/json
Property Description
grant_type refresh_token
refresh_token refresh_token received from the authorization request
client_id client identifier issued by VerifyTreatment
client_secret client secret issued by VerifyTreatment
scope (optional) This is optional; if not sent the original scopes will be used, otherwise you can request a reduced set of scopes.

VOBs

Create / Search benefits

You can create a new VOB by sending a POST request to the /vobs endpoint. The facility and payer_id fields are required to complete the configuration request.

Example Request:

POST
Content-Type: application/json
Property Description
first_name first name
last_name last name
member_id client member id
payer_id vtx_payer_id GET /payers
date_of_birth date of birth MM/DD/YYYY , YYYY-MM-DD
client_type (optional) client_type [ prospect , termed , client , referred , discharged ]
subscriber_relation (optional) client relation to the subscriber
insurance_phone (optional) insurance company phone
client_phone (optional) client company phone
ssn (optional) client ssn
gender (optional) M/F/Other,
facility (optional) Facility _id/ACCOUNT_DEFAULT from GET /facility request. If facility is included it will overwrite the accounts default facility when submitting the insurance request

List All VOBs

Example Request:

GET
Optional Query Parameters
Property Description
sort available fields to sort are:
  • first_name
  • payer_name
  • coverage
  • insurance_filter
  • facility_filter
  • client_type
  • updated_at
You can append a "-" to the field name to sort descending
coverage
  • Active Coverage
  • Unavailable
  • Inactive
payer_name Payer name from GET /payers
facility Facility ID from GET /facilities
client_type
  • web_lead
  • prospect
  • client
  • referred
  • discharged
  • referred
  • termed
range
  • today
  • yesterday
  • last_7
  • last_30
  • last_60
  • last_90
created_by User ID from GET /users
q Free text search
skip Number of vobs to skip (defaults to 0)
limit Number of vobs to return (defaults to 20)

View Vob

Example Request:

GET
Fields
Property Description
rev History ID from GET /vob/:id/history

Update VOB

Example Request:

PUT
Fields
Property Description
action save / verify
client_type
  • web_lead
  • prospect
  • client
  • referred
  • discharged
  • referred
  • termed
date_of_birth xxx
email xxx
facility xxx
first_name xxx
gender xxx
group_number xxx
insurance_phone xxx
last_name xxx
member_id xxx
payer_id xxx
payer_name xxx
phone xxx
place_of_service xxx
ssn xxx
subscriber_relation xxx
tag xxx

Delete VOB

Example Request:

DELETE

Re-Verify VOB

Example Request:

POST
Content-Type: application/json
Property Description
_id VOB ID to re-verify

History

Example Request:

GET

Subscriber Relations

Property Description
SR01 Self
SR02 Spouse
SR03 Child
SR04 Other Relationship
SR05 Other Adult

Exporting Data

Export single vob as PDF

Example Request:

POST
Property Description
format pdf
vob_id Vob ID to export
type custom
out_of_network['AI', '30'] Out of network service types to export
in_network['AI', '30'] In network service types to export

Export all vobs

Requires access to VerifyTreatment export subscription

Example Request:

POST
Property Description
format csv
type vobs
start Start date YYYY-MM-DD
end End date YYYY-MM-DD
coverage Coverage status ['active', 'inactive', 'unavilable']
sort -created_at | created_at (asc/desc)

Importing Data

Import batch data

You can import / update batch data by sumbitting a CSV file

Importing data:

Import batch data

POST
Property Description
file CSV file
type
  • vob
  • claim
action
  • create
  • update
facility Facility ID (optional)

CSV file structure

Property Description
_id VOB ID to update (required when action is update)
first_name First name
last_name Last name
date_of_birth Date of birth
client_type
  • web_lead
  • prospect
  • client
  • referred
  • discharged
  • referred
  • termed
payer_id Payer ID
facility Facility ID
tag Tag
external_id External ID
place_of_service
  • PC01 Telehealth
  • PC02 Office
  • PC03 Home
  • PC04 Inpatient Hospital
  • PC05 On Campus-Outpatient Hospital
  • PC06 Emergency Room - Hospital
  • PC07 Other Place of Service

Batch Eligibility

Automatically re-verify vobs

VerifyTreatment provides two options for batch eligibility verification: Auto VOB Monitoring and Run Now.

Auto VOB Monitoring method re-verifies each VOB record when the "Client Type" field is set to "client," according to the specified schedule and settings.

Run Now method enables the user to generate a one-time batch eligibility report.

Please note that the VerifyTreatment Automate Subscription is require to access this feature.

Scheduled run / Auto VOB Monitoring:

Configure batch eligibility scheduled run

PUT
Property Description
enabled boolean
frequency
  • daily
  • bi-weekly
  • monthly
days Array of days to run the scheduled batch eligibility, only applies if frequency is set to daily
start_date Date to run the scheduled batch eligibility. This is used to calculate the next run dates.
Only applies if frequency is set to bi-weekly or monthly

Manual run:

Configure batch eligibility for manual run

PUT
Property Description
manual true
options
JSON Payload:
{
  "vob_status": "VOB_STATUS", // optional defaults to client
  "vob_coverage": "COVERAGE_STATUS", // optional
  "tag": "OPTIONAL_VOB_TAG", // optional
  "vob_last_update": "LAST_UPDATED_DATE (YYYY-MM-DD)", // optional
}
vob_status: [ prospect , termed , client , referred , discharged ]
vob_coverage: [ Active Coverage , Inactive , Unknown ]

Payers

Example Request:

GET
Query Parameters
Property Description
q Search Payer
limit Number of payers to return
skip Number of payers to skip

Configuration API

Each insurance company requires a unique combination of patient/provider details. For example, some insurance companies may require less information than others.

The configuration API allows you to look up all the required fields for a specific payer.

Tip: Sometimes the insurance company may allow you to submit requests using only the patient's first name, last name, and date of birth. However, you may still receive a "Patient Not Found" error message, even if you have verified the information. In these cases, you will still need to submit the request using the Member ID

Example Request:

GET
Query Parameters
Property Description
facility Facility ID

Facilities

Example Request:

GET
Query Parameters
Property Description
q Search Facility
limit Number of payers to return
skip Number of payers to skip

Join VerifyTreatment

Get started with VerifyTreatment today!