Create a Forever Form ​

Forever Forms are persistent patient assignments designed to be made available immediately and to remain active until completed. Patients will receive automated reminders until the assigned forms are completed and submitted.

Before getting started ​

Before you get started you may like to reference Initial API Setup

Example Forever Form Creation ​

Request ​

import axios from 'axios'

const FORMS_API_BASE_URL = 'https://api.visiontree.com/v1'
const TENANT_ID = '1'
const AUTH_TOKEN = 'Your_Auth_Token'
const options = {
  headers: {
    Authorization: `Bearer ${AUTH_TOKEN}`,
  },
}

const body = {
	correlationTag: 'DEIDENTIFIED-ID-0001',
  forms: [
    {
      formId: 'bf484e43-bdc0-4cdd-859b-a9505f025adc',
      revisionId: '2eceef09-e867-4111-81a8-543841fac543',
      communicationMethod: {
        type: 'sms',
        phoneNumber: '1234567890'
      }
    }
  ]
}


axios.post(`${FORMS_API_BASE_URL}/tenants/${TENANT_ID}/assignments`, body, options)
	.then(res => console.log(res.data))

Response ​

[
  {
    id: 'cf33c7a2-1dea-4387-8e78-b7fe0f9a5e71',
    tenantId: '1',
    formId: 'bf484e43-bdc0-4cdd-859b-a9505f025adc',
    correlationTag: 'DEIDENTIFIED-ID-0001',
    startDate: null,
    endDate: null,
    createdOn: '2024-03-25T19:52:14.962Z',
    updatedOn: '2024-03-25T19:52:14.962Z',
    revisionId: '2eceef09-e867-4111-81a8-543841fac543',
    communicationMethod: { type: 'sms', phoneNumber: '1234567890' }
  }
]

Explanations ​

Request ​

We will discuss the request line-for-line next. First, we made use of the axios library to simplify promise-based HTTP requests. You may use any HTTP library of your choosing. The following three lines set our base Forms API URL, our Tenant ID as well as our Auth Token previously retrieved. The Tenant ID here will be used to create a Forever Form that will adhere to the tenant's reminder configuration settings.

Next, the request's body, similar to creating any other form assignment, is filled out, however, the major difference here is the omission of the following fields: startDate, completionWindow and recurrence. The omission of these fields is required to create a Forever Form.

The property correlationTag is used as an identifier for whom the forms will be filled out by. This should be a deidentified ID if referring to a patient.

The properties formId and revisionId denote which form and version are assigned to the patient to complete.

Lastly, the communicationMethod describes how the patient will be notified of their form to complete, be that by email or SMS.

The final line is the HTTP request itself where we introduce the full API endpoint, body and headers.

Response ​

The response body shows the form assignment record created in the Forms API. It's important to retain the id, which is also known as the formAssignmentId, as this is used when a patient submits their response in a form submission. The id (formAssignmentId), is used to stop notifications for this particular Forever Form after the patient has submitted their responses to the Forms API.