Skip to main content
This guide walks through a common approach to integrating Sohar into your patient intake flow. When a patient submits their information (first name, last name, date of birth, insurance information etc.), you send it to Sohar to process, check eligibility and return the result back to your system in real time. Patient intake diagram

​
Setup

1

Create Credentials

Create a client ID and client secret in the Sohar dashboard.
Create credentials for the sandbox environment to get started quickly without the need for actual patient data.
2

Configure Webhooks

Configure a webhook endpoint to listen for events. If you are using the sandbox environment, subscribe your endpoint to the sandbox.verification.updated event. If you are using the production environment, subscribe to the verification.updated event.

​
Workflow

The diagram below outlines the workflow we will build to take your patient through the intake flow and handle the response from Sohar. Patient intake diagram
1

Collect patient data

2

Call the Create Verification API

3

Handle webhook events and call the Get Verification API

4

Use the Sohar response to handle routing logic

​
Collect Patient Data

Create an interface to capture the following information at minimum:
  • First Name
  • Last Name
  • Date of Birth
  • State (2-letter code, e.g. CA)
  • Payer ID
  • Member ID
You can use the Get Payers API to retrieve a list of payer IDs. We recommend adding the Sohar payer IDs to your existing payer list, and presenting the list to your patients during intake.

​
Create a Verification

Pass the information collected in the previous step to the Create Verification API. You will also need to specify the placeOfServiceCode and specialtyCode. In this example we are interested in benefits information for a telehealth consultation (place of service code 10) with a psychotherapist (specialty code PSY). 
const response = await axios.post(
	'https://api.soharhealth.com/v2/verifications',
	{
		patient: {
			firstName: 'John',
			lastName: 'Doe',
			dateOfBirth: '09/20/2006',
			state: 'CA',
			memberId: '00000000'
		},
		payerId: '60054',
		placeOfServiceCode: '10',
		specialtyCode: 'PSY'
	},
	{
		headers: {
			'Authorization': `Bearer ${accessToken}`
		}
	}
);

​
Handle Webhook Events

Once the Verification request is complete, the response will be posted to all subscribed webhook endpoints. This is an example of the verification.updated and sandbox.verification.updated webhook payloads: 
{
  "verificationId": "990cdad8-1438-4bbd-8b55-120b56e87540",
  "id": "123456",
  "status": "complete.eligible"
}
Sohar responds asynchronously via webhooks, typically within 30 seconds. The example below demonstrates how to retrieve information once the response is ready. 
const express = require('express');
const axios = require('axios');

const app = require('express')();
app.use(express.json());

app.post('/webhooks', async (req, res) => {
	// Retrieve the verification ID from the request body
	const verificationId = req.body['verificationId'];

	// Generate an access token
	const createTokenResponse = await axios.post(
		'https://api.soharhealth.com/oauth/token',
		{
			client_id: process.env.SOHAR_CLIENT_ID,
			client_secret: process.env.SOHAR_CLIENT_SECRET
		}
	);

	const accessToken = createTokenResponse.data.access_token;

	// Retrieve details of the completed verification
	const getVerificationResponse = await axios.get(
		`https://api.soharhealth.com/v2/verifications/${verificationId}`,
		{
			headers: {
				'Authorization': `Bearer ${accessToken}`
			}
		}
	);

	// Handle routing logic based on the Sohar response
	const verificationData = getVerificationResponse.data;
	const status = verificationData.status;

	res.status(200).send({ success: true });
});

app.listen(3000, () => console.log('Running on port 3000'));
You can store the Sohar response in your system for data analytics purposes, or load it into external systems such as your EHR.

​
Patient Routing

Depending on the response you receive from Sohar, it might make sense to route the patient to different flows. The flows detailed below are most commonly used when integrating with Sohar. Patient routing

​
Schedule Consultation

This is the ideal outcome. The status is complete.eligible, indicating that the request is complete, the patient has active coverage and they are eligible for the requested service. The patient can proceed through the intake funnel - often the next step is to schedule their initial consultation.

​
Request Alternative Insurance

The status complete.ineligible indicates that the request is complete but the patient either doesn’t have active coverage or they are not eligible for the requested service. Perhaps their coverage has lapsed or they are using an outdated member ID. In this instance it might make sense to ask the patient if they have alternative insurance information. If the patient is able to provide alternative information, this information can be submitted to the Create Verification API.

​
Review Intake Data

A member error status indicates that there was something wrong with the information submitted by the patient. This could either be an error.member.id status, an error.member.name status or an error.member.dob status. Ask the patient to review the information they submitted, and if they are able to correct any mistakes then the updated information can be submitted to the Create Verification API.

​
Manual Workflow

There are two types of payer error status that can be returned. error.payer indicates that the payer has been unavailable for at least 24 hours - it is unlikely that you will see this status returned during patient intake. error.payer.npi indicates that the payer doesn’t recognise the NPI that Sohar included in the request. Here is some information about how to manage providers in your account in order to avoid this response. We typically see customers implement manual workflows to handle this status or any other unexpected response. This might involve contacting the patient to clarify the information they submitted.