> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rxscale.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Anamnesis (v4)
> Read questionnaire models and submit anamnesis responses
# Anamnesis (v4)
The v4 Anamnesis API lets you fetch a questionnaire model, render it on your own surface, and submit the patient's answers back to RxScale. Every submission is validated against the questionnaire model before it is stored, so an invalid payload never creates a record.
This is the v4 Anamnesis API. The legacy `/api/v3-1/anamnesis` endpoints are still available — see [Anamnesis](/api-reference/public/anamnesis) for that reference.
## Base Path
```
/v4/anamnesis
```
## Authentication
The read endpoints (questionnaire model, public files) and the standard `POST /submissions` endpoint are **public** and require **no API key**. They are intended to be called directly from storefronts and other client surfaces that render RxScale questionnaires.
The **external** submission endpoint (`POST /external/submissions`) is **authenticated** and requires an API key passed in the `X-API-Key` header, with the `anamnesis:external_submit` permission. You may only submit on behalf of an external anamnesis provider that belongs to your organisation — the `provider_identifier` you pass is resolved to a provider owned by the API key's organisation.
For the public endpoints, because no credentials are sent, only non-sensitive read operations (questionnaire model, public files) and write operations that are validated against the questionnaire model are exposed. Submitted answers are transmitted over HTTPS, and an encrypted copy of each submission is retained at rest.
## Endpoint Summary
| Method | Endpoint | Auth | Description |
| ------ | --------------------------------------------------------- | ----------- | ----------------------------------------------------- |
| `GET` | `/questionnaires/{questionnaire_id}` | Public | Fetch the questionnaire model and rendering metadata |
| `GET` | `/questionnaires/{questionnaire_id}/files/{filename}` | Public | Download a file referenced by the questionnaire |
| `POST` | `/questionnaires/{questionnaire_id}/submissions` | Public | Submit an anamnesis for a questionnaire |
| `POST` | `/questionnaires/{questionnaire_id}/external/submissions` | `X-API-Key` | Submit an anamnesis on behalf of an external provider |
## Get Questionnaire
Fetch the questionnaire model and the metadata you need to render it. This endpoint is **public** and requires no API key.
```bash theme={null}
GET /v4/anamnesis/questionnaires/{questionnaire_id}
```
The UID of the questionnaire
### Example Request
```bash theme={null}
curl -X GET "https://api.rxscale.com/v4/anamnesis/questionnaires/abc123-def456"
```
### Response
```json theme={null}
{
"model": {
"title": "Patient Intake",
"pages": [
{
"name": "page1",
"elements": [
{ "type": "text", "name": "lastName", "title": "Last name", "isRequired": true },
{ "type": "text", "name": "dob", "title": "Date of birth", "inputType": "date" }
]
}
]
},
"theme": {
"themeName": "default",
"colorPalette": "light"
},
"type": "direct_to_cart",
"identifier": "patient-intake",
"version": 3
}
```
| Field | Type | Description |
| ------------ | ------- | ------------------------------------------------------------------------------ |
| `model` | object | The SurveyJS questionnaire model. Pass this to the SurveyJS renderer |
| `theme` | object | The SurveyJS theme used for rendering |
| `type` | string | The questionnaire type (for example `direct_to_cart` or `product_recommender`) |
| `identifier` | string | A stable human-readable identifier for the questionnaire |
| `version` | integer | The published version of the questionnaire |
Returned when no questionnaire exists for the given `questionnaire_id`.
## Download Questionnaire File
Download a file referenced by the questionnaire (for example an image or an information PDF). The file is returned as an attachment with its original filename. This endpoint is **public** and requires no API key.
```bash theme={null}
GET /v4/anamnesis/questionnaires/{questionnaire_id}/files/{filename}
```
The UID of the questionnaire
The name of the file to download
### Example Request
```bash theme={null}
curl -X GET "https://api.rxscale.com/v4/anamnesis/questionnaires/abc123-def456/files/info.pdf" \
-o info.pdf
```
The response is the raw file bytes, served as an attachment (`Content-Disposition: attachment; filename="info.pdf"`).
Returned when the questionnaire or the requested file does not exist.
## Submit Anamnesis
Submit the patient's answers for a questionnaire. This endpoint is **public** and requires no API key. The `data` payload is validated against the questionnaire model before anything is stored. On success the submission is persisted (with an encrypted copy of the answers retained at rest) and its UID is returned.
```bash theme={null}
POST /v4/anamnesis/questionnaires/{questionnaire_id}/submissions
```
The UID of the questionnaire being answered
### Request Body
```json theme={null}
{
"data": {
"lastName": "Müller",
"dob": "1990-05-15"
}
}
```
| Field | Type | Required | Description |
| ------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `data` | object | Yes | The SurveyJS answer payload. Its structure must match the questionnaire model returned by [Get Questionnaire](#get-questionnaire) |
### Example Request
```bash theme={null}
curl -X POST "https://api.rxscale.com/v4/anamnesis/questionnaires/abc123-def456/submissions" \
-H "Content-Type: application/json" \
-d '{
"data": {"lastName": "Müller", "dob": "1990-05-15"}
}'
```
### Response
```json theme={null}
{
"uid": "anam-9f8e7d6c"
}
```
| Field | Type | Description |
| ----- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uid` | string | The UID of the created anamnesis. Use it to link the submission to a Shopify order — see the [Questionnaire Integration guide](/guides/questionnaire-integration) |
The endpoint responds with `201 Created` on success.
## Submit External Anamnesis
Submit a questionnaire response on behalf of an external anamnesis provider. The `data` payload is validated against the questionnaire model in exactly the same way as a regular submission.
This endpoint is **authenticated**: send your API key in the `X-API-Key` header. The key must have the `anamnesis:external_submit` permission. Instead of a provider UID, you pass a `provider_identifier`, which is resolved to an external anamnesis provider owned by the API key's organisation — you may only submit for a provider that belongs to your organisation.
```bash theme={null}
POST /v4/anamnesis/questionnaires/{questionnaire_id}/external/submissions
```
The UID of the questionnaire being answered
### Request Body
```json theme={null}
{
"provider_identifier": "my-clinic-provider",
"external_identifier": "ext-submission-001",
"data": {
"lastName": "Müller",
"dob": "1990-05-15"
}
}
```
| Field | Type | Required | Description |
| --------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider_identifier` | string | Yes | The identifier of your external anamnesis provider (provided by RxScale). This is an identifier, not a UID, and the provider must belong to the organisation that owns the API key |
| `external_identifier` | string | Yes | Your own identifier for this submission, used for tracking and for linking to orders |
| `data` | object | Yes | The SurveyJS answer payload. Its structure must match the questionnaire model |
### Example Request
```bash theme={null}
curl -X POST "https://api.rxscale.com/v4/anamnesis/questionnaires/abc123-def456/external/submissions" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"provider_identifier": "my-clinic-provider",
"external_identifier": "ext-submission-001",
"data": {"lastName": "Müller", "dob": "1990-05-15"}
}'
```
### Response
```json theme={null}
{
"uid": "ext-anam-1a2b3c4d"
}
```
| Field | Type | Description |
| ----- | ------ | ---------------------------------------------------- |
| `uid` | string | The UID of the created external anamnesis submission |
The endpoint responds with `201 Created` on success.
## Submission Validation
Both submission endpoints validate the `data` payload against the questionnaire model **before** writing anything to the database. If validation fails, the request is rejected with `400 Bad Request` and **no record is created**.
The error body contains the list of validation problems reported against the questionnaire model:
```json theme={null}
{
"error": [
"lastName is required",
"dob must be a valid date"
]
}
```
If the request body itself is malformed — for example a missing required field such as `data` or `provider_identifier` — the `400` response instead reports the offending field:
```json theme={null}
{
"error": {
"data": ["Missing data for required field."]
}
}
```
If the submission validator is temporarily unreachable, the request fails with `502 Bad Gateway` and **no record is created**. This is a transient upstream failure, not a problem with your payload — retry the request:
```json theme={null}
{
"error": "submission validator unavailable"
}
```
Always fetch the latest questionnaire model with [Get Questionnaire](#get-questionnaire) and render your form from it. Submitting answers that do not match the current model will fail validation and the submission will not be stored.
### Error Responses
| Status | Meaning |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | The submission failed questionnaire model validation, or the request body was malformed. No record is created |
| `401` | Missing or invalid API key (external submission endpoint only) |
| `403` | The API key lacks the `anamnesis:external_submit` permission (external submission endpoint only) |
| `404` | No questionnaire exists for the given `questionnaire_id`, or the `provider_identifier` does not match a provider owned by your organisation |
| `409` | An external submission with this `external_identifier` already exists for the provider (external submission endpoint only) |
| `502` | The submission validator was temporarily unavailable. No record is created — retry the request |
## Typical Integration Flow
Call `GET /questionnaires/{questionnaire_id}` to retrieve the `model` and `theme`.
Render the model with the SurveyJS renderer (or use the RxScale snippet, which does this for you).
Post the collected `data` to `/submissions` (public), or to `/external/submissions` with your `X-API-Key` for external providers. RxScale validates the answers against the model.
Persist the returned `uid` and use it to link the submission to a Shopify order. See the [Questionnaire Integration guide](/guides/questionnaire-integration).