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

# Vote Recommendation

PUT https://pre-api.joincandidhealth.com/eligibility-checks/v1/recommendation/{recommendation_id}/{version}/vote
Content-Type: application/json

Submit user feedback on an eligibility recommendation. The path must contain the next version number to prevent race conditions. For example, if the current version of the recommendation is n, you will need to send a request to this endpoint with `/{recommendation_id}/{n+1}/vote` to update the vote.

Reference: https://docs.joincandidhealth.com/api-reference/pre-encounter/eligibility-checks/v-1/vote-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

### Path parameters

- `recommendation_id` (string, required)
- `version` (string, required)

### Body (application/json)

This endpoint expects a Vote.

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

## Response

### 200

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

## Errors

### 404 Not Found Error

- `errorName` ("NotFoundError", required)
- `content` (ErrorBase4xx, required)

### 409 Version Conflict Error

- `errorName` ("VersionConflictError", required)
- `content` (VersionConflictErrorBody, required)

## Types

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

### ErrorBase4xx

- `message` (string, required)
- `data` (any, optional)

### VersionConflictErrorBody

- `message` (string, required)
- `data` (any, optional)
- `latest_version` (integer, optional)

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

**Request**

```json
{
  "user_id": "user_id",
  "value": "UPVOTE"
}
```

**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"
    }
  ]
}
```

**SDK Code**

```python
import requests

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

payload = {
    "user_id": "user_id",
    "value": "UPVOTE"
}
headers = {
    "Authorization": "<token>.",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://pre-api.joincandidhealth.com/eligibility-checks/v1/recommendation/recommendation_id/version/vote';
const options = {
  method: 'PUT',
  headers: {Authorization: '<token>.', 'Content-Type': 'application/json'},
  body: '{"user_id":"user_id","value":"UPVOTE"}'
};

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/recommendation/recommendation_id/version/vote"

	payload := strings.NewReader("{\n  \"user_id\": \"user_id\",\n  \"value\": \"UPVOTE\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "<token>.")
	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/recommendation/recommendation_id/version/vote")

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = '<token>.'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"user_id\": \"user_id\",\n  \"value\": \"UPVOTE\"\n}"

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.put("https://pre-api.joincandidhealth.com/eligibility-checks/v1/recommendation/recommendation_id/version/vote")
  .header("Authorization", "<token>.")
  .header("Content-Type", "application/json")
  .body("{\n  \"user_id\": \"user_id\",\n  \"value\": \"UPVOTE\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://pre-api.joincandidhealth.com/eligibility-checks/v1/recommendation/recommendation_id/version/vote', [
  'body' => '{
  "user_id": "user_id",
  "value": "UPVOTE"
}',
  'headers' => [
    'Authorization' => '<token>.',
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://pre-api.joincandidhealth.com/eligibility-checks/v1/recommendation/recommendation_id/version/vote");
var request = new RestRequest(Method.PUT);
request.AddHeader("Authorization", "<token>.");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"user_id\": \"user_id\",\n  \"value\": \"UPVOTE\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "<token>.",
  "Content-Type": "application/json"
]
let parameters = [
  "user_id": "user_id",
  "value": "UPVOTE"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://pre-api.joincandidhealth.com/eligibility-checks/v1/recommendation/recommendation_id/version/vote")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
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()
```