Getting started with the forms registry ​

This section will focus on providing a walkthrough for sending your first requests to the Forms API's forms registry.

Here you will learn to manage the form repository and:

1. Create a form
2. Retrieve the form

Sending your first request ​

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

Saving a FHIR-based PROM ​

After obtaining your Access Token and Tenant ID you will be able to access the API's full functionality.

Here we will demonstrate how to save your first FHIR form to the forms registry via Node.js

Request Template ​

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 = {
  visibility: 'Public',
  content: {
    resourceType: 'Questionnaire',
    id: 'Example FHIR Questionnaire',
  },
}

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

Response Template ​

{
  formId: 'bf484e43-bdc0-4cdd-859b-a9505f025adc',
  revisionId: '2eceef09-e867-4111-81a8-543841fac543',
  revision: '1',
  tenantId: '1',
  visibility: 'Public',
  content: {
    resourceType: 'Questionnaire',
    id: 'Example FHIR Questionnaire'
  },
  createdOn: '2023-11-29T13:50:35.421Z',
  updatedOn: '2023-11-29T13:50:35.421Z'
}

Request and Response Explanations ​

Request ​

Let's take a look at each part of the request. 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 denotes which account's PROMs repository you wish to connect to, in this case your new PROM will be saved under this Tenant ID's repository.

Next, we have the request's body. Here, we are setting two properties: visibility and content. The visibility property takes one of two values Public or Private, if set to private only users with access to your Tenant ID can access this form, otherwise anyone with access to the Forms API can read this form. The content attribute is simply your FHIR-based PROM, using the JSON format, you wish to save to the repository.

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

Response ​

In this example we just output the reponse from the request's promise, but it is a good practice to keep record of the returned formId property in the response as this is the unique ID of the form you saved to the respository. With this ID and your Tenant ID you can search for, update the record or delete it.

The response will also contain a revisionId this is a unique identifier to a specific version of a form. Moreover, the revision property acts as the version number for a single form or formId.

Important: Remember to swap out TENANT_ID with your own.