Framework v1.5 now available!

Appearance

On this page

Create a Form Assignment ​

This section will demonstrate how to create a form assignment. A form assignment creates a reminder for a patient and is used to assign a PROM to the patient and to provide the reminder details such as how to notify the patient (SMS or email) as well as when. You will need your Access Token and Tenant ID.

Sample Request Template ​

javascript
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',
      startDate: '2023-12-01T00:00:00Z',
      completionWindow: {
        quantity: 1,
        unit: 'weeks',
      },
      recurrence: {
        numberOfOccurences: 4,
        interval: {
          quantity: 2,
          unit: 'weeks',
        },
      },
      communicationMethod: {
        type: 'sms',
        phoneNumber: '12345678910',
      },
    },
  ],
}

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

Sample Response Template ​

javascript
[
  {
    id: 'e73ecc69-bdf1-44f3-9129-f0450cbadeb4',
    tenantId: '1',
    formId: 'bf484e43-bdc0-4cdd-859b-a9505f025adc',
    revisionId: '2eceef09-e867-4111-81a8-543841fac543',
    correlationTag: 'DEIDENTIFIED-ID-0001',
    startDate: '2023-12-01T00:00:00.000Z',
    endDate: '2023-12-08T00:00:00.000Z',
    createdOn: '2023-12-04T14:23:22.729Z',
    updatedOn: '2023-12-04T14:23:22.729Z',
    communicationMethod: { type: 'sms', phoneNumber: '12345678910' },
  },
  {
    id: 'ab1bd87d-2439-4e5f-a294-59140ae7213b',
    tenantId: '1',
    formId: 'bf484e43-bdc0-4cdd-859b-a9505f025adc',
    revisionId: '2eceef09-e867-4111-81a8-543841fac543',
    correlationTag: 'DEIDENTIFIED-ID-0001',
    startDate: '2023-12-15T00:00:00.000Z',
    endDate: '2023-12-22T00:00:00.000Z',
    createdOn: '2023-12-04T14:23:22.729Z',
    updatedOn: '2023-12-04T14:23:22.729Z',
    communicationMethod: { type: 'sms', phoneNumber: '12345678910' },
  },
  {
    id: 'e18fa4cf-5c6f-45c4-8fec-01f3ebb054c7',
    tenantId: '1',
    formId: 'bf484e43-bdc0-4cdd-859b-a9505f025adc',
    revisionId: '2eceef09-e867-4111-81a8-543841fac543',
    correlationTag: 'DEIDENTIFIED-ID-0001',
    startDate: '2023-12-29T00:00:00.000Z',
    endDate: '2024-01-05T00:00:00.000Z',
    createdOn: '2023-12-04T14:23:22.729Z',
    updatedOn: '2023-12-04T14:23:22.729Z',
    communicationMethod: { type: 'sms', phoneNumber: '12345678910' },
  },
  {
    id: '9d681663-08de-4b37-829e-d2e1230adbed',
    tenantId: '1',
    formId: 'bf484e43-bdc0-4cdd-859b-a9505f025adc',
    revisionId: '2eceef09-e867-4111-81a8-543841fac543',
    correlationTag: 'DEIDENTIFIED-ID-0001',
    startDate: '2024-01-12T00:00:00.000Z',
    endDate: '2024-01-19T00:00:00.000Z',
    createdOn: '2023-12-04T14:23:22.729Z',
    updatedOn: '2023-12-04T14:23:22.729Z',
    communicationMethod: { type: 'sms', phoneNumber: '12345678910' },
  },
]

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 form assignment that adheres to the tenant's reminder configuration settings.

Next, we have the request's body, which represents the Forms API's form assignment. Here we will set a recurring PROM, for example for a longitudinal study. The PROM will be made available every other week and recur 4 times. Each time the PROM is made available the patient will have 1 week to complete it.

Let's look at how the request body depicts these settings. The startDate property is self-explanatory, this is the date at which the assignment takes effect. The completionWindow sets the time a patient has to complete the PROM, in this case 1 week per occurence of the PROM. The next attribute recurrence sets how many times the PROM will be made available to the patient and the time interval between each start date of each recurring instance. Lastly, we have the communicationMethod attribute which sets the method in which to send the reminder to the patient by.

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

Communication Methods ​

There are 3 types of communication methods:

  1. SMS
  2. email
  3. callback

The communicationMethod attribute takes the following forms in the request body for assigned forms:

javascript
// SMS
communicationMethod: {
  type: 'sms',
  phoneNumber: '12345678910'
}

// email
communicationMethod: {
  type: 'email',
  emailAddress: 'test@test.com'
}

// callback
communicationMethod: {
  type: 'callback',
  callback: 'https://your-callback.com/deindentified-id'
}

The callback communication method allows you to provide your own URL to connect the Forms API's assigner to your own notification service. We will describe this in the section Connect Forms API Notifications to Your Custom Notification Service

Response ​

We will now take a look at the response body after creating the new form assignment. We first see that we are returned an array of objects, where each object represent one form assignment. We have one form assignment for each recurrence as defined in the attribute recurrence.numberOfOccurences. Just as we had set the parameters in our request, we can now see the first object starts on our defined startDate and every recurrence happens 2 weeks after the previous. The startDate and stopDate are set one week apart, just as we'd expect since we chose a completionWindow of 1 week. You can also see in the formId attribute the ID of the PROM assigned in each form assignment.