Run an eligibility check
curl --request POST \
--url https://api.healos.ai/ext-api/v1/benefits/eligibility-checks \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"payer_id": "60054",
"provider_name": "Riverside Family Medicine",
"provider_npi": "1234567893",
"payer_name": "Aetna",
"patient_id": "481926357104938271",
"member_id": "W123456789",
"first_name": "Jordan",
"last_name": "Rivera",
"date_of_birth": "1984-03-12",
"middle_name": "<string>",
"gender": "F",
"service_type": "30",
"linked_check_id": "<string>"
}
'import requests
url = "https://api.healos.ai/ext-api/v1/benefits/eligibility-checks"
payload = {
"payer_id": "60054",
"provider_name": "Riverside Family Medicine",
"provider_npi": "1234567893",
"payer_name": "Aetna",
"patient_id": "481926357104938271",
"member_id": "W123456789",
"first_name": "Jordan",
"last_name": "Rivera",
"date_of_birth": "1984-03-12",
"middle_name": "<string>",
"gender": "F",
"service_type": "30",
"linked_check_id": "<string>"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
payer_id: '60054',
provider_name: 'Riverside Family Medicine',
provider_npi: '1234567893',
payer_name: 'Aetna',
patient_id: '481926357104938271',
member_id: 'W123456789',
first_name: 'Jordan',
last_name: 'Rivera',
date_of_birth: '1984-03-12',
middle_name: '<string>',
gender: 'F',
service_type: '30',
linked_check_id: '<string>'
})
};
fetch('https://api.healos.ai/ext-api/v1/benefits/eligibility-checks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.healos.ai/ext-api/v1/benefits/eligibility-checks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'payer_id' => '60054',
'provider_name' => 'Riverside Family Medicine',
'provider_npi' => '1234567893',
'payer_name' => 'Aetna',
'patient_id' => '481926357104938271',
'member_id' => 'W123456789',
'first_name' => 'Jordan',
'last_name' => 'Rivera',
'date_of_birth' => '1984-03-12',
'middle_name' => '<string>',
'gender' => 'F',
'service_type' => '30',
'linked_check_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.healos.ai/ext-api/v1/benefits/eligibility-checks"
payload := strings.NewReader("{\n \"payer_id\": \"60054\",\n \"provider_name\": \"Riverside Family Medicine\",\n \"provider_npi\": \"1234567893\",\n \"payer_name\": \"Aetna\",\n \"patient_id\": \"481926357104938271\",\n \"member_id\": \"W123456789\",\n \"first_name\": \"Jordan\",\n \"last_name\": \"Rivera\",\n \"date_of_birth\": \"1984-03-12\",\n \"middle_name\": \"<string>\",\n \"gender\": \"F\",\n \"service_type\": \"30\",\n \"linked_check_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.healos.ai/ext-api/v1/benefits/eligibility-checks")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"payer_id\": \"60054\",\n \"provider_name\": \"Riverside Family Medicine\",\n \"provider_npi\": \"1234567893\",\n \"payer_name\": \"Aetna\",\n \"patient_id\": \"481926357104938271\",\n \"member_id\": \"W123456789\",\n \"first_name\": \"Jordan\",\n \"last_name\": \"Rivera\",\n \"date_of_birth\": \"1984-03-12\",\n \"middle_name\": \"<string>\",\n \"gender\": \"F\",\n \"service_type\": \"30\",\n \"linked_check_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.healos.ai/ext-api/v1/benefits/eligibility-checks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"payer_id\": \"60054\",\n \"provider_name\": \"Riverside Family Medicine\",\n \"provider_npi\": \"1234567893\",\n \"payer_name\": \"Aetna\",\n \"patient_id\": \"481926357104938271\",\n \"member_id\": \"W123456789\",\n \"first_name\": \"Jordan\",\n \"last_name\": \"Rivera\",\n \"date_of_birth\": \"1984-03-12\",\n \"middle_name\": \"<string>\",\n \"gender\": \"F\",\n \"service_type\": \"30\",\n \"linked_check_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "3f2b9c1e-6a7d-4e1f-9b0a-2c4d5e6f7a8b",
"status": "Active",
"patient_name": "Jordan Rivera",
"payer_name": "Aetna",
"member_id": "W123456789",
"patient_id": "<string>",
"insurance_type": "primary",
"linked_check_id": "<string>",
"checked_at": "<string>",
"last_checked_at": "<string>",
"result": {}
}
}{
"error": "<string>",
"code": "PAYER_VALIDATION_ERROR"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>",
"code": "PAYER_VALIDATION_ERROR"
}{
"error": "<string>",
"code": "PAYER_VALIDATION_ERROR"
}{
"error": "Rate limit exceeded. Please retry after the window resets."
}{
"error": "<string>",
"code": "PAYER_VALIDATION_ERROR"
}{
"error": "<string>",
"code": "PAYER_VALIDATION_ERROR"
}{
"error": "<string>",
"code": "PAYER_VALIDATION_ERROR"
}Benefits
Run an eligibility check
Runs a real-time insurance eligibility and benefits check (X12 270/271) with the payer and stores the result in your organization’s benefits history, where it also shows in the HealOS dashboard. Either pass patient_id for a patient already in HealOS, or pass member_id, first_name, last_name and date_of_birth. Requires the benefits:write scope. Each check is a billable payer request, so this endpoint is limited to 10 requests per minute per API key on top of the global limit. Responses usually take a few seconds; allow up to a minute when the payer is slow.
POST
/
benefits
/
eligibility-checks
Run an eligibility check
curl --request POST \
--url https://api.healos.ai/ext-api/v1/benefits/eligibility-checks \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"payer_id": "60054",
"provider_name": "Riverside Family Medicine",
"provider_npi": "1234567893",
"payer_name": "Aetna",
"patient_id": "481926357104938271",
"member_id": "W123456789",
"first_name": "Jordan",
"last_name": "Rivera",
"date_of_birth": "1984-03-12",
"middle_name": "<string>",
"gender": "F",
"service_type": "30",
"linked_check_id": "<string>"
}
'import requests
url = "https://api.healos.ai/ext-api/v1/benefits/eligibility-checks"
payload = {
"payer_id": "60054",
"provider_name": "Riverside Family Medicine",
"provider_npi": "1234567893",
"payer_name": "Aetna",
"patient_id": "481926357104938271",
"member_id": "W123456789",
"first_name": "Jordan",
"last_name": "Rivera",
"date_of_birth": "1984-03-12",
"middle_name": "<string>",
"gender": "F",
"service_type": "30",
"linked_check_id": "<string>"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
payer_id: '60054',
provider_name: 'Riverside Family Medicine',
provider_npi: '1234567893',
payer_name: 'Aetna',
patient_id: '481926357104938271',
member_id: 'W123456789',
first_name: 'Jordan',
last_name: 'Rivera',
date_of_birth: '1984-03-12',
middle_name: '<string>',
gender: 'F',
service_type: '30',
linked_check_id: '<string>'
})
};
fetch('https://api.healos.ai/ext-api/v1/benefits/eligibility-checks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.healos.ai/ext-api/v1/benefits/eligibility-checks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'payer_id' => '60054',
'provider_name' => 'Riverside Family Medicine',
'provider_npi' => '1234567893',
'payer_name' => 'Aetna',
'patient_id' => '481926357104938271',
'member_id' => 'W123456789',
'first_name' => 'Jordan',
'last_name' => 'Rivera',
'date_of_birth' => '1984-03-12',
'middle_name' => '<string>',
'gender' => 'F',
'service_type' => '30',
'linked_check_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.healos.ai/ext-api/v1/benefits/eligibility-checks"
payload := strings.NewReader("{\n \"payer_id\": \"60054\",\n \"provider_name\": \"Riverside Family Medicine\",\n \"provider_npi\": \"1234567893\",\n \"payer_name\": \"Aetna\",\n \"patient_id\": \"481926357104938271\",\n \"member_id\": \"W123456789\",\n \"first_name\": \"Jordan\",\n \"last_name\": \"Rivera\",\n \"date_of_birth\": \"1984-03-12\",\n \"middle_name\": \"<string>\",\n \"gender\": \"F\",\n \"service_type\": \"30\",\n \"linked_check_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.healos.ai/ext-api/v1/benefits/eligibility-checks")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"payer_id\": \"60054\",\n \"provider_name\": \"Riverside Family Medicine\",\n \"provider_npi\": \"1234567893\",\n \"payer_name\": \"Aetna\",\n \"patient_id\": \"481926357104938271\",\n \"member_id\": \"W123456789\",\n \"first_name\": \"Jordan\",\n \"last_name\": \"Rivera\",\n \"date_of_birth\": \"1984-03-12\",\n \"middle_name\": \"<string>\",\n \"gender\": \"F\",\n \"service_type\": \"30\",\n \"linked_check_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.healos.ai/ext-api/v1/benefits/eligibility-checks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"payer_id\": \"60054\",\n \"provider_name\": \"Riverside Family Medicine\",\n \"provider_npi\": \"1234567893\",\n \"payer_name\": \"Aetna\",\n \"patient_id\": \"481926357104938271\",\n \"member_id\": \"W123456789\",\n \"first_name\": \"Jordan\",\n \"last_name\": \"Rivera\",\n \"date_of_birth\": \"1984-03-12\",\n \"middle_name\": \"<string>\",\n \"gender\": \"F\",\n \"service_type\": \"30\",\n \"linked_check_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "3f2b9c1e-6a7d-4e1f-9b0a-2c4d5e6f7a8b",
"status": "Active",
"patient_name": "Jordan Rivera",
"payer_name": "Aetna",
"member_id": "W123456789",
"patient_id": "<string>",
"insurance_type": "primary",
"linked_check_id": "<string>",
"checked_at": "<string>",
"last_checked_at": "<string>",
"result": {}
}
}{
"error": "<string>",
"code": "PAYER_VALIDATION_ERROR"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>",
"code": "PAYER_VALIDATION_ERROR"
}{
"error": "<string>",
"code": "PAYER_VALIDATION_ERROR"
}{
"error": "Rate limit exceeded. Please retry after the window resets."
}{
"error": "<string>",
"code": "PAYER_VALIDATION_ERROR"
}{
"error": "<string>",
"code": "PAYER_VALIDATION_ERROR"
}{
"error": "<string>",
"code": "PAYER_VALIDATION_ERROR"
}Authorizations
API key obtained from /api/v1/ext-api-keys
Body
application/json
Payer id from GET /benefits/payers/search.
Minimum string length:
1Example:
"60054"
Name of the requesting provider or practice.
Minimum string length:
1Example:
"Riverside Family Medicine"
10-digit NPI of the requesting provider or practice.
Pattern:
^\d{10}$Example:
"1234567893"
Payer display name, stored on the check for your records.
Example:
"Aetna"
A HealOS patient in your organization. When set, the patient's name, date of birth, gender and the member id of their active insurance for this payer are used, and the member fields below are not required.
Pattern:
^\d+$Example:
"481926357104938271"
Insurance member id. Required without patient_id.
Minimum string length:
1Example:
"W123456789"
Required without patient_id.
Minimum string length:
1Example:
"Jordan"
Required without patient_id.
Minimum string length:
1Example:
"Rivera"
YYYY-MM-DD. Required without patient_id.
Pattern:
^\d{4}-\d{2}-\d{2}$Example:
"1984-03-12"
Example:
"F"
X12 service type code. Defaults to 30 (health benefit plan coverage).
Example:
"30"
Defaults to primary.
Available options:
primary, secondary For a secondary check: the id of the primary check it belongs to.
Response
Check completed (the payer may still report inactive coverage or issues)
Show child attributes
Show child attributes
Was this page helpful?