The most common use case for the Sohar API is to determine the eligibility status and healthcare benefits for a patient. In this tutorial we will create a verification request in your sandbox environment.

The easiest way to get started is to make a request to the Create Verification API. The sandbox environment has a number of input values to generate pre-defined responses. We will make a sandbox request to Aetna using payer ID 60054.

1

Credentials

Locate your sandbox API key from the Sohar dashboard.

2

Request

Execute the request below, replacing <authorization> with your sandbox API key.

curl --request POST \
	--url https://api.soharhealth.com/v2/verifications \
	--header 'Authorization: <authorization>' \
	--header 'Content-Type: application/json' \
	--data '{
		"patient": {
			"firstName": "John",
			"lastName": "Doe",
			"dateOfBirth": "09/20/2006",
			"state": "CA",
			"memberId": "00000000"
		},
		"payerId": "60054",
		"placeOfServiceCode": "10",
		"specialtyCode": "PSY",
		"id":  "12345"
	}'
3

Response

The API response contains the IDs for the patient resource and verification resource that were created.

{
	"verificationId": "b213a377-744c-4c8b-b5db-be8955c187c0",
	"id":  "12345"
}
4

Webhooks

Our system processes requests asynchronously, and results are delivered via webhook. Once the verification request has completed, the sandbox.verification.updated webhook event will be sent with the following payload:

{
	"verificationId": "b213a377-744c-4c8b-b5db-be8955c187c0",
	"id": "12345",
	"status": "complete.eligible",
	...
}
5

Get Verification

Call the Get Verification API, replacing <authorization> with your sandbox API key and {verificationId} with the verificationId from the webhook event payload.

curl --request GET \
	--url https://api.soharhealth.com/v2/verifications/{verificationId} \
	--header 'Authorization: <authorization>'
6

Benefits

The Get Verification API will return a response similar to the response below:

{
  "verificationId": "b213a377-744c-4c8b-b5db-be8955c187c0",
  "created": "2024-01-01T12:00:00.000Z",
  "status": "complete.eligible",
  "id": "123456",
  "benefits": [
    [
      {
        "networkStatus": "inn",
        "tier": null,
        "copay": 30,
        "coinsurance": 0,
        "deductible": {
          "total": 1000,
          "remaining": 847.56,
          "coverageLevelCode": "IND"
        },
        "outOfPocket": {
          "total": 10000,
          "remaining": 5103.21
        }
      },
      {
        "networkStatus": "oon",
        "tier": null,
        "copay": 0,
        "coinsurance": 0.4,
        "deductible": {
          "total": 2000,
          "remaining": 2000,
          "coverageLevelCode": "IND"
        },
        "outOfPocket": {
          "total": 20000,
          "remaining": 20000
        }
      }
    ]
  ],
  "relatedEntities": [
    {
      "id": "01260",
      "name": "Magellan",
      "memberId": "00000000",
      "entityIdentifierCode": "VN"
    },
    {
      "id": "NDX99",
      "name": "Lucet",
      "memberId": null,
      "entityIdentifierCode": "X3"
    }
  ],
  "patient": {
    "firstName": "JOHN",
    "lastName": "DOE",
    "dateOfBirth": "09/20/2006",
    "memberId": "00000000",
    "subscriberRelationshipCode": "18",
    "address": {
      "address1": "1 BROADWAY",
      "address2": "P.O. BOX 123",
      "city": "LOS ANGELES",
      "state": "CA",
      "zipCode": "90210"
    }
  },
  "subscriber": {
    "firstName": "JANE",
    "lastName": "DOE"
  },
  "plan": {
    "name": "OPEN CHOICE",
    "insuranceTypeCode": "HM",
    "startDate": "09/20/2023",
    "endDate": "09/20/2023"
  },
  "payer": {
    "id": "60054",
    "name": "Aetna"
  },
  "group": {
    "number": "123456",
    "name": "ACME CORPORATION"
  }
}

You have successfully created your first verification!