> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cail.health/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cail.health/_mcp/server.

# Submit a PREM response

POST https://staging.cail.health/v1/prem/responses
Content-Type: application/json

Records Patient-Reported Experience Measure (PREM) feedback after a navigation session. Captured anonymously: only the navigation session, rating, optional free text, and optional provider/outcome context are stored. Submitting a rating that mismatches the linked session’s recorded outcome is accepted but warn-logged for analytics review. Idempotent on (navigationSessionId, anonymousUid): repeated submissions for the same session by the same client update the same row.

Reference: https://docs.cail.health/api-references/api-reference/share-feedback/submit

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: cail-api
  version: 1.0.0
paths:
  /v1/prem/responses:
    post:
      operationId: submit
      summary: Submit a PREM response
      description: >-
        Records Patient-Reported Experience Measure (PREM) feedback after a
        navigation session. Captured anonymously: only the navigation session,
        rating, optional free text, and optional provider/outcome context are
        stored. Submitting a rating that mismatches the linked session’s
        recorded outcome is accepted but warn-logged for analytics review.
        Idempotent on (navigationSessionId, anonymousUid): repeated submissions
        for the same session by the same client update the same row.
      tags:
        - subpackage_shareFeedback
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The recorded PREM response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitPremResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitPremRequest'
servers:
  - url: https://staging.cail.health
    description: https://staging.cail.health
components:
  schemas:
    SubmitPremRequest:
      type: object
      properties:
        navigationSessionId:
          type: string
          description: >-
            Identifier of the navigation session this feedback is for. Accepts
            the snake_case key `navigation_session_id`.
        q1Rating:
          type: number
          format: double
          description: >-
            Member satisfaction rating from 1 (very dissatisfied) to 5 (very
            satisfied). Accepts the snake_case key `q1_rating`.
        q2FreeText:
          type: string
          description: >-
            Free-text feedback about the experience. Accepts the snake_case key
            `q2_free_text`.
        q3ConditionalText:
          type: string
          description: >-
            Conditional follow-up text (only shown to members whose rating
            triggered the follow-up question). Accepts the snake_case key
            `q3_conditional_text`.
        providerId:
          type: string
          description: >-
            Identifier of the provider the member visited, when known. Accepts
            the snake_case key `provider_id`.
        outcomeCode:
          type: string
          description: >-
            Outcome code of the session being rated. Accepts the snake_case key
            `outcome_code`.
      required:
        - navigationSessionId
        - q1Rating
      title: SubmitPremRequest
    SubmittedPremResponse:
      type: object
      properties:
        id:
          type: string
          description: Stable identifier for the recorded PREM response.
        q1Rating:
          type: number
          format: double
          description: Rating echoed back from the submission.
        submittedAt:
          type: string
          description: ISO 8601 timestamp at which the response was recorded.
      required:
        - id
        - q1Rating
        - submittedAt
      title: SubmittedPremResponse
    SubmitPremResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/SubmittedPremResponse'
        message:
          type: string
          description: Human-readable acknowledgement.
      required:
        - data
        - message
      title: SubmitPremResponse
  securitySchemes:
    firebaseBearer:
      type: http
      scheme: bearer

```

## Examples



**Request**

```json
{
  "navigationSessionId": "3a4b5c6d-7e8f-4901-92b3-c4d5e6f7a8b9",
  "q1Rating": 5
}
```

**Response**

```json
{
  "data": {
    "id": "d4c5b6a7-9e8f-4012-83a4-5b6c7d8e9f01",
    "q1Rating": 5,
    "submittedAt": "2026-05-13T14:21:00.000Z"
  },
  "message": "Response submitted"
}
```

**SDK Code**

```python A 5-star submission with a free-text comment
import requests

url = "https://staging.cail.health/v1/prem/responses"

payload = {
    "navigationSessionId": "3a4b5c6d-7e8f-4901-92b3-c4d5e6f7a8b9",
    "q1Rating": 5
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript A 5-star submission with a free-text comment
const url = 'https://staging.cail.health/v1/prem/responses';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"navigationSessionId":"3a4b5c6d-7e8f-4901-92b3-c4d5e6f7a8b9","q1Rating":5}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go A 5-star submission with a free-text comment
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://staging.cail.health/v1/prem/responses"

	payload := strings.NewReader("{\n  \"navigationSessionId\": \"3a4b5c6d-7e8f-4901-92b3-c4d5e6f7a8b9\",\n  \"q1Rating\": 5\n}")

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

	req.Header.Add("Authorization", "Bearer <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 A 5-star submission with a free-text comment
require 'uri'
require 'net/http'

url = URI("https://staging.cail.health/v1/prem/responses")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"navigationSessionId\": \"3a4b5c6d-7e8f-4901-92b3-c4d5e6f7a8b9\",\n  \"q1Rating\": 5\n}"

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

```java A 5-star submission with a free-text comment
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://staging.cail.health/v1/prem/responses")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"navigationSessionId\": \"3a4b5c6d-7e8f-4901-92b3-c4d5e6f7a8b9\",\n  \"q1Rating\": 5\n}")
  .asString();
```

```php A 5-star submission with a free-text comment
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://staging.cail.health/v1/prem/responses', [
  'body' => '{
  "navigationSessionId": "3a4b5c6d-7e8f-4901-92b3-c4d5e6f7a8b9",
  "q1Rating": 5
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp A 5-star submission with a free-text comment
using RestSharp;

var client = new RestClient("https://staging.cail.health/v1/prem/responses");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"navigationSessionId\": \"3a4b5c6d-7e8f-4901-92b3-c4d5e6f7a8b9\",\n  \"q1Rating\": 5\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift A 5-star submission with a free-text comment
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "navigationSessionId": "3a4b5c6d-7e8f-4901-92b3-c4d5e6f7a8b9",
  "q1Rating": 5
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://staging.cail.health/v1/prem/responses")! 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()
```