> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.joincandidhealth.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.joincandidhealth.com/_mcp/server. # Coordination Of Benefits POST https://pre-api.joincandidhealth.com/eligibility-checks/v1/coordination-of-benefits Content-Type: application/json Sends a coordination of benefits check through Stedi to determine whether a patient has coverage overlap across multiple payers and, if so, which payer is primary. Medicare and Medicare Advantage plans are not supported. Reference: https://docs.joincandidhealth.com/api-reference/pre-encounter/eligibility-checks/v-1/coordination-of-benefits ## Authentication - OAuth2 — send the obtained token as `Authorization: Bearer ` ## Servers - `https://pre-api.joincandidhealth.com` (Production, default) - `https://pre-api-staging.joincandidhealth.com` (Staging) - `https://sandbox-pre-api.joincandidhealth.com` (CandidSandbox) - `https://staging-pre-api.joincandidhealth.com` (CandidStaging) - `http://localhost:4000` (Local) ## Request ### Body (application/json) This endpoint expects a CoordinationOfBenefitsRequest. - `trading_partner_service_id` (string, required) — The Payer ID. Each check must be for a participating health plan for which the patient has coverage. Medicare and Medicare Advantage plans are not supported. - `provider` (CobProvider, required) — Information about the entity requesting the COB check. Provide either organization_name (for organizations) or first_name and last_name (for individuals), plus npi. - `subscriber` (CobSubscriber, required) — The primary policyholder for the insurance plan or a dependent with a unique member ID. You must provide at least one of member_id or ssn. - `encounter` (CobEncounter, required) — Information about the encounter for the COB check. Service dates must be within the past 2 years and must not be in the future. - `dependent` (CobDependent, optional) — A dependent for which you want to check coordination of benefits. If the dependent has their own member ID, include their information in the subscriber object instead. ## Response ### 200 - `provider` (CobResponseProvider, optional) — Information about the provider who submitted the COB request. - `subscriber` (CobResponseSubscriber, optional) — Information about the primary policyholder. - `dependent` (CobResponseDependent, optional) — Information about the dependent listed in the COB request. - `payer` (CobPayer, optional) — Information about the payer listed in the COB request. - `plan_date_information` (CobPlanDateInformation, optional) — Date information for the plan. - `benefits_information` (list of any, optional) — Raw passthrough of Stedi's benefits information (coverage, service types, related entities, etc.). - `errors` (list of EligibilityCheckErrorDetails, optional) - `coordination_of_benefits` (Cob, optional) — Overview of the COB response including whether coverage overlap exists and payer primacy. ## Types ### CobProvider Information about the entity requesting the COB check. Provide either organization_name (for organizations) or first_name and last_name (for individuals), plus npi. - `npi` (string, required) — The provider's National Provider Identifier (NPI). - `organization_name` (string, optional) — The provider's business name. Required if the provider is an organization. - `first_name` (string, optional) — The provider's first name. Required if the provider is an individual. - `last_name` (string, optional) — The provider's last name. Required if the provider is an individual. ### CobSubscriber The primary policyholder for the insurance plan or a dependent with a unique member ID. You must provide at least one of member_id or ssn. - `first_name` (string, required) — The subscriber's first name. - `last_name` (string, required) — The subscriber's last name. - `date_of_birth` (string, required) — The subscriber's date of birth. - `member_id` (string, optional) — The member ID for the subscriber's insurance policy. - `ssn` (string, optional) — The subscriber's Social Security Number (SSN). ### CobEncounter Information about the encounter for the COB check. Service dates must be within the past 2 years and must not be in the future. - `date_of_service` (string, optional) — The date of service. Defaults to the current date if not specified. - `beginning_date_of_service` (string, optional) — The beginning date of service. If included, end_date_of_service is also required. - `end_date_of_service` (string, optional) — The end date of service. If included, beginning_date_of_service is also required. ### CobDependent A dependent for which you want to check coordination of benefits. If the dependent has their own member ID, include their information in the subscriber object instead. - `first_name` (string, required) — The dependent's first name. - `last_name` (string, required) — The dependent's last name. - `date_of_birth` (string, required) — The dependent's date of birth. - `ssn` (string, optional) — The dependent's Social Security Number (SSN). ### CobResponseProvider Information about the entity that submitted the original COB request. - `provider_name` (string, optional) — The provider's last name. Applies to providers that are an individual. - `provider_first_name` (string, optional) — The provider's first name. Applies to providers that are an individual. - `provider_org_name` (string, optional) — The provider's organization name. - `npi` (string, optional) — The provider's National Provider Identifier (NPI). - `aaa_errors` (list of EligibilityCheckErrorDetails, optional) — AAA errors specifying reasons for rejection and recommended follow-up actions. ### CobResponseSubscriber Information about the primary policyholder for the insurance plan listed in the COB request. - `member_id` (string, optional) — The member ID for the subscriber's insurance policy. - `first_name` (string, optional) - `last_name` (string, optional) - `middle_name` (string, optional) - `gender` (string, optional) — The subscriber's gender. Typically `F` - Female, `M` - Male, or `U` - Unknown. - `date_of_birth` (string, optional) - `ssn` (string, optional) - `group_number` (string, optional) — The group number associated with the subscriber's insurance policy. - `birth_sequence_number` (string, optional) — Birth order when there are multiple births associated with the provided birth date. - `address` (CobAddress, optional) — A patient's address as returned in a coordination of benefits response. - `aaa_errors` (list of EligibilityCheckErrorDetails, optional) — AAA errors specifying reasons for rejection and recommended follow-up actions. ### CobResponseDependent Information about the dependent listed in the original COB request. - `member_id` (string, optional) — The member ID for the subscriber's insurance policy. - `first_name` (string, optional) - `last_name` (string, optional) - `middle_name` (string, optional) - `gender` (string, optional) — The dependent's gender. Typically `F` - Female, `M` - Male, or `U` - Unknown. - `date_of_birth` (string, optional) - `ssn` (string, optional) - `group_number` (string, optional) — The group number associated with the subscriber's insurance policy. - `relation_to_subscriber` (string, optional) — The name of the relation_to_subscriber_code. For example, `Child` when the code is `19`. - `relation_to_subscriber_code` (string, optional) — The dependent's relationship to the subscriber. For example `01` - Spouse, `19` - Child, `20` - Employee, `21` - Unknown, `39` - Organ Donor, `40` - Cadaver Donor, `53` - Life Partner, or `G8` - Other Relationship. - `birth_sequence_number` (string, optional) — Birth order when there are multiple births associated with the provided birth date. - `address` (CobAddress, optional) — A patient's address as returned in a coordination of benefits response. - `aaa_errors` (list of EligibilityCheckErrorDetails, optional) — AAA errors specifying reasons for rejection and recommended follow-up actions. ### CobPayer Information about the payer listed in the COB request. - `name` (string, optional) — The payer's name, such as `CIGNA`. - `payer_identification` (string, optional) — The trading_partner_service_id (Payer ID) used to identify the payer in the COB request. ### CobPlanDateInformation Dates associated with the patient's health plan coverage. - `plan_begin` (string, optional) — When the patient's health plan coverage begins. - `plan_end` (string, optional) — When the patient's health plan coverage ends. ### EligibilityCheckErrorDetails This object is our fern representation of Stedi's EligbilityCheckError object from their API. - `field?` (string, optional) - `description?` (string, optional) - `location?` (string, optional) - `possibleResolutions?` (string, optional) - `code?` (string, optional) - `followupAction?` (string, optional) ### Cob An overview of the COB response. Indicates whether there is a coverage overlap, whether that overlap creates a coordination of benefits instance, and whether Stedi was able to identify payer primacy (when a COB instance exists). - `classification` (string, optional) — The classification for the discovered benefits. One of: `CobInstanceExistsPrimacyDetermined`, `CobInstanceExistsPrimacyUndetermined`, `CoverageOverlapNoBenefitOverlap`, `CoverageOverlapExistsNotSubjectToCob`, or `MemberFoundNoCob`. - `instance_exists` (boolean, optional) — If true, the COB response contains at least one coordination of benefits instance. - `primacy_determined` (boolean, optional) — If true, Stedi was able to determine the primary payer for the patient. - `coverage_overlap` (boolean, optional) — If true, the patient has active coverage with two or more payers during the service date. - `benefit_overlap` (boolean, optional) — If true, the patient has active coverage from two or more payers for the same service type code. ### CobAddress A patient's address as returned in a coordination of benefits response. - `address_1` (string, optional) - `address_2` (string, optional) - `city` (string, optional) - `state` (string, optional) — The US state or Canadian province code. Kept as a string rather than an enum because, per Stedi, payers may sometimes return non-compliant values. - `postal_code` (string, optional) - `country_code` (string, optional) - `country_sub_division_code` (string, optional) ## Examples **Request** ```json { "trading_partner_service_id": "trading_partner_service_id", "provider": { "npi": "npi" }, "subscriber": { "first_name": "first_name", "last_name": "last_name", "date_of_birth": "date_of_birth" } } ``` **Response** ```json { "provider": { "provider_name": "provider_name", "provider_first_name": "provider_first_name", "provider_org_name": "provider_org_name", "npi": "npi", "aaa_errors": [ { "field?": "field?", "description?": "description?", "location?": "location?", "possibleResolutions?": "possibleResolutions?", "code?": "code?", "followupAction?": "followupAction?" }, { "field?": "field?", "description?": "description?", "location?": "location?", "possibleResolutions?": "possibleResolutions?", "code?": "code?", "followupAction?": "followupAction?" } ] }, "subscriber": { "member_id": "member_id", "first_name": "first_name", "last_name": "last_name", "middle_name": "middle_name", "gender": "gender", "date_of_birth": "date_of_birth", "ssn": "ssn", "group_number": "group_number", "birth_sequence_number": "birth_sequence_number", "address": { "address_1": "address_1", "address_2": "address_2", "city": "city", "state": "state", "postal_code": "postal_code", "country_code": "country_code", "country_sub_division_code": "country_sub_division_code" }, "aaa_errors": [ { "field?": "field?", "description?": "description?", "location?": "location?", "possibleResolutions?": "possibleResolutions?", "code?": "code?", "followupAction?": "followupAction?" }, { "field?": "field?", "description?": "description?", "location?": "location?", "possibleResolutions?": "possibleResolutions?", "code?": "code?", "followupAction?": "followupAction?" } ] }, "dependent": { "member_id": "member_id", "first_name": "first_name", "last_name": "last_name", "middle_name": "middle_name", "gender": "gender", "date_of_birth": "date_of_birth", "ssn": "ssn", "group_number": "group_number", "relation_to_subscriber": "relation_to_subscriber", "relation_to_subscriber_code": "relation_to_subscriber_code", "birth_sequence_number": "birth_sequence_number", "address": { "address_1": "address_1", "address_2": "address_2", "city": "city", "state": "state", "postal_code": "postal_code", "country_code": "country_code", "country_sub_division_code": "country_sub_division_code" }, "aaa_errors": [ { "field?": "field?", "description?": "description?", "location?": "location?", "possibleResolutions?": "possibleResolutions?", "code?": "code?", "followupAction?": "followupAction?" }, { "field?": "field?", "description?": "description?", "location?": "location?", "possibleResolutions?": "possibleResolutions?", "code?": "code?", "followupAction?": "followupAction?" } ] }, "payer": { "name": "name", "payer_identification": "payer_identification" }, "plan_date_information": { "plan_begin": "plan_begin", "plan_end": "plan_end" }, "benefits_information": [ { "key": "value" }, { "key": "value" } ], "errors": [ { "field?": "field?", "description?": "description?", "location?": "location?", "possibleResolutions?": "possibleResolutions?", "code?": "code?", "followupAction?": "followupAction?" }, { "field?": "field?", "description?": "description?", "location?": "location?", "possibleResolutions?": "possibleResolutions?", "code?": "code?", "followupAction?": "followupAction?" } ], "coordination_of_benefits": { "classification": "classification", "instance_exists": true, "primacy_determined": true, "coverage_overlap": true, "benefit_overlap": true } } ``` **SDK Code** ```python import requests url = "https://pre-api.joincandidhealth.com/eligibility-checks/v1/coordination-of-benefits" payload = { "trading_partner_service_id": "trading_partner_service_id", "provider": { "npi": "npi" }, "subscriber": { "first_name": "first_name", "last_name": "last_name", "date_of_birth": "date_of_birth" } } headers = { "Authorization": ".", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://pre-api.joincandidhealth.com/eligibility-checks/v1/coordination-of-benefits'; const options = { method: 'POST', headers: {Authorization: '.', 'Content-Type': 'application/json'}, body: '{"trading_partner_service_id":"trading_partner_service_id","provider":{"npi":"npi"},"subscriber":{"first_name":"first_name","last_name":"last_name","date_of_birth":"date_of_birth"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://pre-api.joincandidhealth.com/eligibility-checks/v1/coordination-of-benefits" payload := strings.NewReader("{\n \"trading_partner_service_id\": \"trading_partner_service_id\",\n \"provider\": {\n \"npi\": \"npi\"\n },\n \"subscriber\": {\n \"first_name\": \"first_name\",\n \"last_name\": \"last_name\",\n \"date_of_birth\": \"date_of_birth\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", ".") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://pre-api.joincandidhealth.com/eligibility-checks/v1/coordination-of-benefits") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = '.' request["Content-Type"] = 'application/json' request.body = "{\n \"trading_partner_service_id\": \"trading_partner_service_id\",\n \"provider\": {\n \"npi\": \"npi\"\n },\n \"subscriber\": {\n \"first_name\": \"first_name\",\n \"last_name\": \"last_name\",\n \"date_of_birth\": \"date_of_birth\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://pre-api.joincandidhealth.com/eligibility-checks/v1/coordination-of-benefits") .header("Authorization", ".") .header("Content-Type", "application/json") .body("{\n \"trading_partner_service_id\": \"trading_partner_service_id\",\n \"provider\": {\n \"npi\": \"npi\"\n },\n \"subscriber\": {\n \"first_name\": \"first_name\",\n \"last_name\": \"last_name\",\n \"date_of_birth\": \"date_of_birth\"\n }\n}") .asString(); ``` ```php request('POST', 'https://pre-api.joincandidhealth.com/eligibility-checks/v1/coordination-of-benefits', [ 'body' => '{ "trading_partner_service_id": "trading_partner_service_id", "provider": { "npi": "npi" }, "subscriber": { "first_name": "first_name", "last_name": "last_name", "date_of_birth": "date_of_birth" } }', 'headers' => [ 'Authorization' => '.', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://pre-api.joincandidhealth.com/eligibility-checks/v1/coordination-of-benefits"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "."); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"trading_partner_service_id\": \"trading_partner_service_id\",\n \"provider\": {\n \"npi\": \"npi\"\n },\n \"subscriber\": {\n \"first_name\": \"first_name\",\n \"last_name\": \"last_name\",\n \"date_of_birth\": \"date_of_birth\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": ".", "Content-Type": "application/json" ] let parameters = [ "trading_partner_service_id": "trading_partner_service_id", "provider": ["npi": "npi"], "subscriber": [ "first_name": "first_name", "last_name": "last_name", "date_of_birth": "date_of_birth" ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://pre-api.joincandidhealth.com/eligibility-checks/v1/coordination-of-benefits")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```