Aidbox SDC API

• $generate-link
• $save
• $submit
• $notify-patient

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

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.

name: redirect-on-save
value:
  String: https://example.com/submit-hook?questionnaire=123

expiration

Link expiration period (days)

name: expiration
value:
  Integer: 30

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.

- 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

link: http://forms.aidbox.io/ui/sdc#/questionnaire-response/12c1178c-70a9-4e02-a53d-65b13373926e?token=eyJhbGciOiJIUzI

resourceType: OperationOutcome
text:
  status: generated
  div: Parameters are invalid
issue:
- severity: error
  code: invalid
  expression:
  - parameter.0.resource
  diagnostics: unknown key :resource

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

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: text/yaml

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

resourceType: Parameters
parameter:
- name: response
  resource:
    resourceType: QuestionnaireResponse
    id: 12c1178c-70a9-4e02-a53d-65b13373926e
    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

resourceType: Parameters
parameter:
- name: issue
  resource:
    resourceType: OperationOutcome
    issue:
    - severity: fatal
      code: invalid
      expression:
      - QuestionnaireResponse.item[0].item[1].answer[0].valueDecimal
      details:
        coding:
        - system: http://aidbox.app/CodeSystem/operation-outcome-type
          code: invalid-type
        - system: http://aidbox.app/CodeSystem/schema-id
          code: QuestionnaireResponse
      diagnostics: Invalid type for the field. Expected 'string', but got 'decimal'

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

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: text/yaml

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

resourceType: Parameters
parameter:
- name: response
  resource:
    resourceType: QuestionnaireResponse
    id: 12c1178c-70a9-4e02-a53d-65b13373926e
    questionnaire: Questionnaire/patient-registration
    status: completed
    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

resourceType: Parameters
parameter:
- name: issues
  resource:
    resourceType: OperationOutcome
    issue:
    - severity: error
      code: required
      expression:
      - QuestionnaireResponse.item[3]
      diagnostics: 'Missing required field: Contact Information'

Notify a Patient - $notify-patient

This operation sends an email notification to a patient (or to a provided email) with a generated form link for a QuestionnaireResponse. It sends a single email per request.

If email is not provided in a context, the operation tries to resolve the patient email from QuestionnaireResponse.subject -> Patient.telecom.where(system = 'email').

URLs

POST [base]/fhir/QuestionnaireResponse/$notify-patient

Parameters

resourceType: Parameters
parameter:
- name: provider
  valueString: smtp-provider # required. One of: smtp-provider, postmark-provider, mailgun-provider, sendgrid-provider
- name: response
  valueReference:
    reference: QuestionnaireResponse/qr1 # required
- name: email
  valueString: joe@mail.com # optional
- name: template
  valueReference:
    reference: NotificationTemplate/my-template # optional
- name: context
  part:
  - name: any-other-field
    valueString: foo # optional, passed to email template payload

The operation takes:

• provider (required): Email provider name. Must be one of smtp-provider, postmark-provider, mailgun-provider, sendgrid-provider.
• response (required): QuestionnaireResponse reference.
• email (optional): Direct recipient email. If missing, patient email from QuestionnaireResponse.subject is used.
• template (optional): NotificationTemplate reference. If not provided, the default template sdc-form-link-email is used.
• context (optional): Custom payload fields for template rendering. All fields are passed to the email template payload along with the generated link

System takes by default preexisted NotificationTemplate, that looks like this.

resourceType: NotificationTemplate
id: sdc-form-link-email
subject: New form available
template: 'A new form is ready for you. Open: {{link}}'

It's possible to create other templates see docs

Output Parameters

The operation returns Parameters that includes:

• response: QuestionnaireResponse reference
• email: Resolved recipient email
• status: "sent" or "failed"
• message: Error message if status is "failed"

Usage Example

POST [base]/fhir/QuestionnaireResponse/$notify-patient
content-type: text/yaml

resourceType: Parameters
parameter:
- name: provider
  valueString: smtp-provider
- name: response
  valueReference:
    reference: QuestionnaireResponse/qr-direct
- name: email
  valueString: direct@mail.com
- name: context
  part:
  - name: foo
    valueString: bar

resourceType: Parameters
parameter:
- name: response
  valueReference:
    reference: QuestionnaireResponse/qr-direct
- name: email
  valueString: direct@mail.com
- name: status
  valueString: sent

resourceType: OperationOutcome
text:
  status: generated
  div: <div xmlns="http://www.w3.org/1999/xhtml"><p>'provider' parameter id is not provided. Should be one of: smtp-provider, postmark-provider, mailgun-provider, sendgrid-provider</p></div>
issue:
- severity: fatal
  code: invalid
  diagnostics: "'provider' parameter id is not provided. Should be one of: smtp-provider, postmark-provider, mailgun-provider, sendgrid-provider"