Aidbox SDC API
Custom SDC operations supported by Aidbox Forms.
Generate a link to a QuestionnaireResponse - $generate-link
This operation generates a link to a web page to be used to continue answering a specified QuestionnaireResponse .
URLs
POST [base]/QuestionnaireResponse/[id]/$generate-link
Parameters
NOTE: All parameters wrapped with Parameters object
resourceType: Parameters
parameter:
- name: [var-name]
value: [var-value]
allow-amend
Whether the generated link will allow amending and re-submitting the form.
name: allow-amend
value:
Boolean: true
allow-repopulate
Whether the generated link will allow re-populating the form.
NOTE: Repopulate will be working only with forms that contain populate behavior
name: allow-repopulate
value:
Boolean: true
redirect-on-submit
A URL where the user will be redirected to after successfully submitting the form.
name: redirect-on-submit
value:
String: https://example.com/submit-hook?questionnaire=123
redirect-on-save
A URL where the user will be redirected to after hitting Save button.
By default Save button is not visible - form autosaved after every keystroke. But sometimes it's usefull to close form in a partially-filled state
name: redirect-on-save
value:
String: https://example.com/submit-hook?questionnaire=123
expiration
Link expiration period (days)
name: expiration
value:
Integer: 30
By default thir parameter = 7 days
theme
Form theme.
name: theme
value:
String: hs-theme
read-only
Show form in a read-only mode
name: read-only
value:
Boolean: true
app-name
Application name that will be used in Audit logging when returned link was used.
Audit logging should be enabled.
- name: app-name
value
String: my-app
Usage Example
POST [base]/QuestionnaireResponse/[id]/$generate-link
content-type: text/yaml
resourceType: Parameters
parameter:
- name: allow-amend
value:
Boolean: true
- name: redirect-on-submit
value:
String: https://example.com/submit-hook?questionnaire=123
Aidbox uses HS256 to sign JWT token by default. To use RS256 you need to set
BOX_AUTH_KEYS_PRIVATE and BOX_AUTH_KEYS_PUBLIC environment variables.
Save a QuestionnaireResponse - $save
This operation validates the structure of a QuestionnaireResponse and saves it. It performs basic structural validation, but does not validate against the associated Questionnaire definition.
The operation validates only FHIR structure of QuestionnaireResponse and have associated Questionnaire. Operation doesn't validate for example — required fields like $submit operation
URLs
POST [base]/fhir/QuestionnaireResponse/$save
Parameters
NOTE: All parameters wrapped with Parameters object
resourceType: Parameters
parameter:
- name: response
resource:
# QuestionnaireResponse resource here
The operation takes a single input parameter named "response" containing a QuestionnaireResponse resource wrapped in a Parameters resource.
Output Parameters
The operation returns:
- response: The saved QuestionnaireResponse resource
- issues: Any validation issues encountered (if applicable)
Usage Example
POST [base]/fhir/QuestionnaireResponse/$save
content-type: application/json
accept: application/json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "response",
"resource": {
"resourceType": "QuestionnaireResponse",
"questionnaire": "Questionnaire/patient-registration",
"status": "in-progress",
"item": [
{
"linkId": "name",
"text": "Patient Name",
"item": [
{
"linkId": "name.given",
"text": "Given Name",
"answer": [
{
"valueString": "John"
}
]
},
{
"linkId": "name.family",
"text": "Family Name",
"answer": [
{
"valueString": "Smith"
}
]
}
]
}
]
}
}
]
}
Submit a QuestionnaireResponse - $submit
This operation validates and submits a QuestionnaireResponse, marking it as "completed" or "amended". It performs comprehensive validation against the associated Questionnaire definition. If validation fails, it returns only the "issues" parameter without the "response" parameter and does not save the QuestionnaireResponse.
URLs
POST [base]/fhir/QuestionnaireResponse/$submit
Parameters
NOTE: All parameters wrapped with Parameters object
resourceType: Parameters
parameter:
- name: response
resource:
# QuestionnaireResponse resource here
The operation takes a single input parameter named "response" containing a QuestionnaireResponse resource wrapped in a Parameters resource.
Output Parameters
The operation returns:
- response: The submitted QuestionnaireResponse resource with status updated to "completed"
- issues: Any validation issues encountered (if applicable)
Usage Example
POST [base]/fhir/QuestionnaireResponse/$submit
content-type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "response",
"resource": {
"resourceType": "QuestionnaireResponse",
"questionnaire": "Questionnaire/patient-registration",
"status": "in-progress",
"item": [
{
"linkId": "name",
"text": "Patient Name",
"item": [
{
"linkId": "name.given",
"text": "Given Name",
"answer": [
{
"valueString": "John"
}
]
},
{
"linkId": "name.family",
"text": "Family Name",
"answer": [
{
"valueString": "Smith"
}
]
}
]
},
{
"linkId": "birthDate",
"text": "Date of Birth",
"answer": [
{
"valueDate": "1970-01-01"
}
]
},
{
"linkId": "gender",
"text": "Gender",
"answer": [
{
"valueCoding": {
"system": "http://hl7.org/fhir/administrative-gender",
"code": "male",
"display": "Male"
}
}
]
}
]
}
}
]
}
Last updated 2025-07-09T17:06:42Z