> 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.

# Recommendation

GET https://pre-api.joincandidhealth.com/eligibility-checks/v1/recommendation

Gets recommendation for eligibility checks based on filters. This endpoint will retrieve all the latest eligibility recommendations for each 
eligibility recommendation type for the given filters. If you want to get a specific recommendation type, you can use the `type` query parameter.

Reference: https://docs.joincandidhealth.com/api-reference/pre-encounter/eligibility-checks/v-1/recommendation

## Authentication

- OAuth2 — send the obtained token as `Authorization: Bearer <token>`

## 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

### Query parameters

- `filters` (string, optional) — A serialized list of filters separated by commas indicating filters to apply. Each filter is of the form 'path:operator:value'. Example: 'patient.mrn|eq|12345'. Filters are separated by commas. Example: 'patient.mrn|eq|12345,appointment.startDate|gt|67890'. All filters are ANDed together. Valid operators are 'eq', 'gt', 'lt', 'contains', 'ieq', 'in'. ieq is a case-insensitive equality operator. in allows searching for values that match any item in a semicolon-separated list (e.g., 'patient.id|in|foo;bar;baz'). Path values are camelCase.

## Response

### 200

- `list of EligibilityRecommendation`

## Types

### EligibilityRecommendation

An eligibility recommendation object that contains an EligibilityRecommendationType and a payload of data denoting the recommendation.

- `deactivated` (boolean, required) — True if the object is deactivated. Deactivated objects are not returned in search results but are returned in all other endpoints including scan.
- `eligibility_check_id` (string, required)
- `id` (string, required) — The unique UUID identifier for an EligibilityRecommendation.
- `organization_id` (string, required) — The organization that owns this object.
- `patient` (EligibilityRecommendationPatientInfo, required) — An object representing patient information for an eligibility recommendation. This is used to find recommendations. Each field helps us find the right corresponding eligibility recommendation for the patient.
- `recommendation` (EligibilityRecommendationPayload, required)
- `updated_at` (datetime, required)
- `updating_user_id` (string, required) — The user ID of the user who last updated the object.
- `version` (integer, required) — The version of the object. Any update to any property of an object object will create a new version.
- `coverage_id` (UUID, optional) — The unique identifier for a Coverage in the database
- `votes` (list of Vote, optional) — Array of votes for this recommendation

### EligibilityRecommendationPatientInfo

An object representing patient information for an eligibility recommendation. This is used to find recommendations. Each field helps us find the right corresponding eligibility recommendation for the patient.

- `id` (string, optional) — The unique identifier for a Patient
- `mrn` (string, optional)
- `organization_id` (string, optional) — The unique identifier for an Organization in the database
- `last_name` (string, optional)
- `first_name` (string, optional)
- `date_of_birth` (date, optional)
- `member_id` (string, optional)

### EligibilityRecommendationPayload

- `type`: `MEDICARE_ADVANTAGE`
  - `payload` (MedicareAdvantageRecommendationPayload, required) — An object representing the payload for a Medicare Advantage recommendation.
- `type`: `MEDICAID_MANAGED_CARE`
  - `payload` (MedicareAdvantageRecommendationPayload, required) — An object representing the payload for a Medicare Advantage recommendation.
- `type`: `COORDINATION_OF_BENEFITS`
  - `payload` (any, required)
- `type`: `COPAY_ESTIMATION`
  - `payload` (CopayEstimationRecommendationPayload, required) — Payload for MD visit copay estimation from AI analysis
- `type`: `USER_CONFIGURED_PROMPTS`
  - `payload` (UserConfiguredPromptsRecommendationPayload, required) — Payload for user-configured prompt recommendations from AI analysis

### Vote

User feedback on a recommendation

- `user_id` (string, required) — The user who voted
- `value` (enum, required) — The vote value
  - Allowed values: `UPVOTE`, `DOWNVOTE`

### MedicareAdvantageRecommendationPayload

An object representing the payload for a Medicare Advantage recommendation.

- `ma_benefit` (any, optional)
- `payer_id` (string, optional)
- `payer_name` (string, optional)
- `member_id` (string, optional)

### CopayEstimationRecommendationPayload

Payload for MD visit copay estimation from AI analysis

- `exposition` (string, required) — The AI's explanation of the copay estimate
- `structured_response` (integer, optional) — The estimated copay amount in cents

### UserConfiguredPromptsRecommendationPayload

Payload for user-configured prompt recommendations from AI analysis

- `results` (list of UserConfiguredPromptsResult, required) — Array of results from all enabled user-configured prompts

### UserConfiguredPromptsResult

Individual result from a single user-configured prompt execution

- `user_prompt_id` (string, required) — Reference to the user prompt in eligibility config
- `prompt_name` (string, required) — User-defined name for the prompt
- `structured_response` (any, required) — The AI's structured answer (boolean, number, or string)
- `exposition` (string, required) — The AI's explanation of the answer

## Examples

**Response**

```json
[
  {
    "deactivated": true,
    "eligibility_check_id": "eligibility_check_id",
    "id": "id",
    "organization_id": "organization_id",
    "patient": {
      "id": "id",
      "mrn": "mrn",
      "organization_id": "organization_id",
      "last_name": "last_name",
      "first_name": "first_name",
      "date_of_birth": "2023-01-15",
      "member_id": "member_id"
    },
    "recommendation": {
      "type": "MEDICARE_ADVANTAGE",
      "payload": {
        "ma_benefit": {
          "key": "value"
        },
        "payer_id": "payer_id",
        "payer_name": "payer_name",
        "member_id": "member_id"
      }
    },
    "updated_at": "2024-01-15T09:30:00Z",
    "updating_user_id": "updating_user_id",
    "version": 1,
    "coverage_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    "votes": [
      {
        "user_id": "user_id",
        "value": "UPVOTE"
      },
      {
        "user_id": "user_id",
        "value": "UPVOTE"
      }
    ]
  },
  {
    "deactivated": true,
    "eligibility_check_id": "eligibility_check_id",
    "id": "id",
    "organization_id": "organization_id",
    "patient": {
      "id": "id",
      "mrn": "mrn",
      "organization_id": "organization_id",
      "last_name": "last_name",
      "first_name": "first_name",
      "date_of_birth": "2023-01-15",
      "member_id": "member_id"
    },
    "recommendation": {
      "type": "MEDICARE_ADVANTAGE",
      "payload": {
        "ma_benefit": {
          "key": "value"
        },
        "payer_id": "payer_id",
        "payer_name": "payer_name",
        "member_id": "member_id"
      }
    },
    "updated_at": "2024-01-15T09:30:00Z",
    "updating_user_id": "updating_user_id",
    "version": 1,
    "coverage_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    "votes": [
      {
        "user_id": "user_id",
        "value": "UPVOTE"
      },
      {
        "user_id": "user_id",
        "value": "UPVOTE"
      }
    ]
  }
]
```

**SDK Code**

```python
import requests

url = "https://pre-api.joincandidhealth.com/eligibility-checks/v1/recommendation"

headers = {"Authorization": "<token>."}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://pre-api.joincandidhealth.com/eligibility-checks/v1/recommendation';
const options = {method: 'GET', headers: {Authorization: '<token>.'}};

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"
	"net/http"
	"io"
)

func main() {

	url := "https://pre-api.joincandidhealth.com/eligibility-checks/v1/recommendation"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<token>.")

	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/recommendation")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<token>.'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://pre-api.joincandidhealth.com/eligibility-checks/v1/recommendation")
  .header("Authorization", "<token>.")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://pre-api.joincandidhealth.com/eligibility-checks/v1/recommendation', [
  'headers' => [
    'Authorization' => '<token>.',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://pre-api.joincandidhealth.com/eligibility-checks/v1/recommendation");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "<token>.");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "<token>."]

let request = NSMutableURLRequest(url: NSURL(string: "https://pre-api.joincandidhealth.com/eligibility-checks/v1/recommendation")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
```