Forms API

Forms in Lotus are represented as Questionnaire FHIR objects. Our REST API for forms includes default options, checks for minimum requirements, and ensures that forms are securely attached to the correct users. This guarantees that all information remains private and secure.

The following page includes information on how to use the Forms API to create, view and edit forms.

Authorization

To ensure that data is scoped to a user and remains private, our API uses a client ID and secret for authorization. Each client application must provide these credentials when making API requests. The client ID and secret are used to authenticate the application and ensure that it has the necessary permissions to access the data.

How to Obtain Client ID and Secret

In your lotus-medplum dashboard, the client can be found in the Project section, or in the list of Client Applications.

Screenshot of Medplum/Lotus Dashboard

Using Client ID and Secret

When making API requests, include your client ID and secret in the request headers as follows:

POST /api/auth/token
Host: https://dev.lotuscares.ai
Content-Type: application/json
Headers: {
  "client_id": "XXXX",
  "client_secret": "XXXX"
}

Use the access token from the response.

{
    "access_token": "XXXX",
}

For additional information, checkout the AUTH documentation.

For testing and development purposes, ensure that you're using the correct id and secret for the correct environment. Forms created under your personal credentials will not be available to other users.

Endpoints

GET /api/forms/[id]

To retrieve a form, you need to provide the form ID. You can find form IDs using the dashboard or keep track of them from the result of a POST request.

Screenshot of Medplum/Lotus Dashboard

GET /api/forms/{form_id}
Host: https://dev.lotuscares.ai
Content-Type: application/json+fhir
Headers: {
  "token": "YOUR_ACCESS_TOKEN"
}

The response will be a JSON representation of the form.

{
    "resourceType": "Questionnaire",
    "id": "XXXX",
    "status": "active",
    "identifier": [
        {
            "system": "https://dev.lotuscares.ai/api/extensions/slug",
            "value": "XXXX"
        }
    ],
    "item": [
        {
            "linkId": "1",
            "text": "What is your name?",
            "type": "string"
        }
    ]
}

The identifier on the form, that is the slug, is used when requesting forms for a patient.

Review the instructions for get_form_url.

POST /api/forms

To create a new form, you need to send a POST request with the form data in the body. The request must include the access token in the headers.

Screenshot of POST form

POST /api/forms/
Host: https://dev.lotuscares.ai
Content-Type: application/json+fhir
Headers: {
  "token": "YOUR_ACCESS_TOKEN"
}
Body: {
    "resourceType": "Questionnaire",
    "status": "active",
    "item": [
        {
            "linkId": "1",
            "text": "What is your name?",
            "type": "string"
        }
    ]
}

The response will include the form information and the form ID. The form ID can be used to retrieve and edit the form later.

{
    "resourceType": "Questionnaire",
    "id": "XXXX",
    "status": "active",
    "item": [
        {
            "linkId": "1",
            "text": "What is your name?",
            "type": "string"
        }
    ]
}

PUT /api/forms/[id]

To edit a form, you need to send a PUT request with the form data in the body. Similar to the POST request, the request must include the access token in the headers.

Screenshot of PUT form

The form id in the URL must match the form id in the body.

PUT /api/forms/
Host: https://dev.lotuscares.ai
Content-Type: application/json+fhir
Headers: {
  "token": "YOUR_ACCESS_TOKEN"
}
Body: {
    "resourceType": "Questionnaire",
    "status": "active",
    "item": [
        {
            "linkId": "1",
            "text": "What is your name?",
            "type": "string"
        }
    ]
}

The response will include the form information and the form ID. The form ID can be used to retrieve and edit the form later.

{
    "resourceType": "Questionnaire",
    "id": "XXXX",
    "status": "active",
    "item": [
        {
            "linkId": "1",
            "text": "What is your name?",
            "type": "string"
        }
    ]
}

GET_FORM_URL

To create a unique link for a patient to fill out a form, you can use this endpoint.

This is a special claimpower feature, the form is retrieved using the slug identifier from the form.

POST api/claimpower/patient/get_form_url
Host: https://dev.lotuscares.ai
Content-Type: application/json
Headers: {
  "token": "YOUR_ACCESS_TOKEN"
}
Body: {
  "form_id": "rsv-consent",
  "claimpower_patient_id": "00000064",
  "claimpower_db_name": "cernea_old"
}

When making a request to this endpoint, the response will be a URL that can be sent to the patient.

The lotus server attempts to preload information from the EHR by making a request to the claimpower API that includes the db_name and patient_id. The form is then prepopulated with the patient's information by matching the LinkId of every item to the corresponding field in the EHR.

{
    "form_url": "https://dev.lotuscares.ai/forms/consent/rsv-cons...",
    "error": {
        "message": "",
        "status": 0
    }
}

The lotus server has a special client_id and secret assigned to it, and it limits the forms that can be accessed to those that are created with specific credentials. The Production servers have additional security measures in place to ensure that the forms are only accessible to the correct users.

Screenshot of GET_FORM_URL in POSTMAN