Extract API v2

From version 5.10.0 of forms4health you can use V2 of the Extract API. The main new features for this version are as follows:

Improved data structures for some of the more complex controls e.g. Annotated Image
New API to provide extract details of a form or building blockto help build an extract definition
New subject instance API to target extracting a specific form instance
Multi extract API to support multiple extract definitions in one request

Extract definition APIs

Note all API's require authentication

Form level

Route: GET /api/v2.0/extract/formdefinition/{formKey}/{formVersion}
Example: /api/v2.0/extract/formdefinition/example-form/1

Building block level

Route: GET api/v2.0/extract/buildingblockdefinition/{key}/{version}
Example: /api/v2.0/extract/buildingblockdefinition/example-building-block/1

Response types

Form definition

property	type
key	`string`
version	`number`
buildingBlocks	`BuildingBlock[]`

Building block definition

property	type
key	`string`
version	`number`
controls	`Control[]`

Control definition

property	type
id	`string`
label	`string`
dataType	`DataType`
extractValueType	`ValueType`

Example form extract definition response

json

{
  "key": "example-form",
  "version": 1,
  "buildingBlocks": [
    {
      "key": "building-block-a",
      "version": 2,
      "controls": [
        {
          "id": "decimal",
          "label": "Decimal",
          "dataType": "decimal",
          "extractValueType": "single-value"
        },
        {
          "id": "integer",
          "label": "Integer",
          "dataType": "integer",
          "extractValueType": "single-value"
        },
        {
          "id": "email",
          "label": "Email",
          "dataType": "email",
          "extractValueType": "single-value"
        }
      ]
    },
    {
      "key": "building-block-b",
      "version": 1,
      "controls": [
        {
          "id": "date",
          "label": "Date",
          "dataType": "date",
          "extractValueType": "single-value"
        },
        {
          "id": "time",
          "label": "Time",
          "dataType": "time",
          "extractValueType": "single-value"
        },
        {
          "id": "datetime",
          "label": "Datetime",
          "dataType": "datetime",
          "extractValueType": "single-value"
        },
        {
          "id": "boolean",
          "label": "Boolean",
          "dataType": "boolean",
          "extractValueType": "single-value"
        }
      ]
    }
  ]
}

Example building block extract definition response

json

{
    "key": "example-building-block",
    "version": 1,
    "controls": [
    {
        "id": "decimal",
        "label": "Decimal",
        "dataType": "decimal",
        "extractValueType": "single-value"
    },
    {
        "id": "integer",
        "label": "Integer",
        "dataType": "integer",
        "extractValueType": "single-value"
    },
    {
        "id": "email",
        "label": "Email",
        "dataType": "email",
        "extractValueType": "single-value"
    }
    ]
}

Multi extract api

Route: POST /api/v2.0/extract
Permission: RunExtractsAndReports

Root request

property	type	notes
subjectIdentifiers	`string[]`	Optional
from	`date`	Optional
to	`date`	Optional
maxResults	`number`	Optional
maxResultsPerDefinitionPerSubject	`number`	Optional
defintions	`(FormExtract``	`[`BuildingBlockExtract`](#building-block-extract-request)`)[]`

Example

json

{
  "subjectIdentifiers": [
    "488edeAB-5e8F-4e50-9137-24e377cf9436",
    "another-subject"
  ],
  "from": "2021-04-23T18:25:43Z",
  "to": "2021-04-24T18:25:43Z",
  "maxResults": 4,
  "maxResultsPerDefinitionPerSubject": 2,
  "definitions": [...]
}

Form extract request

property	type	notes
identifier	`string`	Required: A unique reference to identify the results in the result set.
type	`"form"`	Required
key	`string`	Required
version	`number`	Required
buildingBlocks	`BuildingBlock[]`	Optional

Form extract request - Building Block

property	type	notes
key	string	Required
controlIds	string[]	Optional

Example

json

{ 
    "definitions": [
    {
        "identifier": "form-all-bbs",
        "type": "form",
        "key": "submit-blood-pressure",
        "version": 1
    },
    {
        "identifier": "form-specific-bbs",
        "type": "form",
        "key": "submit-blood-pressure",
        "version": 2,
        "buildingBlocks": [
        {
            "key": "bb-1"
        },
        {
            "key": "bb-2",
            "controlIds": [
            "control-1",
            "control-4"
            ]
        }
        ]
    }]
}

Building block extract request

property	type	notes
identifier	`string`	Required: A unique reference to identify the results in the result set.
type	`"building-block"`	Required
key	`string`	Required
version	`number`	Required
controlIds	`string[]`	Optional

Example

json

{ 
    "definitions": [
    {
        "identifier": "bb-all-controls",
        "type": "building-block",
        "key": "bmi-reporting",
        "version": 1
    },
    {
        "identifier": "bb-specific-controls",
        "type": "building-block",
        "key": "bmi-reporting",
        "version": 2,
        "controlIds": [
            "control-6",
            "control-8"
        ]
    }]
}

Full Example

json

{
  "subjectIdentifiers": [
    "488edeAB-5e8F-4e50-9137-24e377cf9436",
    "another-subject"
  ],
  "from": "2021-04-23T18:25:43Z",
  "to": "2021-04-24T18:25:43Z",
  "maxResults": 4,
  "maxResultsPerDefinitionPerSubject": 2,
  "definitions": [
    {
      "identifier": "form-all-bbs",
      "type": "form",
      "key": "submit-blood-pressure",
      "version": 1
    },
    {
      "identifier": "form-specific-bbs",
      "type": "form",
      "key": "submit-blood-pressure",
      "version": 2,
      "buildingBlocks": [
        {
          "key": "bb-1"
        },
        {
          "key": "bb-2",
          "controlIds": [
            "control-1",
            "control-4"
          ]
        }
      ]
    },
    {
      "identifier": "bb-all-controls",
      "type": "building-block",
      "key": "bmi-reporting",
      "version": 1
    },
    {
      "identifier": "bb-specific-controls",
      "type": "building-block",
      "key": "bmi-reporting",
      "version": 2,
      "controlIds": [
        "control-6",
        "control-8"
      ]
    }
  ]
}

Response

property	type	notes
results	`(FormExtract``	`[`BuildingBlockExtract`](#building-block-extract)`)[]`

json

{
    "results": [...]
}

Form extract

property	type	notes
identifier	string	The identifier specific in the extract request.
type	`"form"`
results	`FormExtractResult[]`

Form extract result

property	type
instanceGuid	`guid`
subjectIdentifier	`string`
submittedByUserIdentifier	`string`
submissionDateTime	`date`
buildingBlocks	`BuildingBlock[]`

Form extract result - building block

property	type
key	`string`
controls	`Control[]`

Example

json

{
    "identifier": "form-example",
    "type": "form",
    "results": [
    {
        "instanceGuid": "a4ebe221-42ae-497d-b026-58992b8f4a52",
        "subjectIdentifier": "subject-1",
        "submittedByUserIdentifier": "user-1",
        "submissionDateTime": "2021-04-11T00:00:00",
        "buildingBlocks": []
    },
    {
        "instanceGuid": "a77a83b4-2e7c-4089-b1ab-eb19fa2794ed",
        "subjectIdentifier": "subject-2",
        "submittedByUserIdentifier": "user-2",
        "submissionDateTime": "2021-11-12T00:00:00",
        "buildingBlocks": [
        {
            "key": "bb-1",
            "controls": []
        },
        {
            "key": "bb-2",
            "controls": [
            {
                "id": "control-1",
                "dataType": "string",
                "label": "control 1 label",
                "values": []
            },
            {
                "id": "control-2",
                "dataType": "decimal",
                "label": "control 2 label",
                "values": [
                {
                    "value": "1.00",
                    "repeatIterationIndex": null,
                    "type": "single-value"
                }
                ]
            }
            ]
        }
        ]
    }
    ]
}

Building block extract

property	type	notes
identifier	string	The identifier specific in the extract request.
type	`"building-block"`
results	`BuildingBlockExtractResult[]`

Building block extract result

property	type
instanceGuid	`guid`
subjectIdentifier	`string`
submittedByUserIdentifier	`string`
submissionDateTime	`date`
controls	`Control[]`

Example

json

{
    "identifier": "example-bb",
    "type": "building-block",
    "results": [
    {
        "instanceGuid": "a4ebe221-42ae-497d-b026-58992b8f4a52",
        "subjectIdentifier": "subject-1",
        "submittedByUserIdentifier": "user-1",
        "submissionDateTime": "2021-04-11T00:00:00",
        "controls": []
    },
    {
        "instanceGuid": "a77a83b4-2e7c-4089-b1ab-eb19fa2794ed",
        "subjectIdentifier": "subject-2",
        "submittedByUserIdentifier": "user-2",
        "submissionDateTime": "2021-11-12T00:00:00",
        "controls": [
        {
            "id": "control-1",
            "dataType": "string",
            "label": "control 1 label",
            "values": []
        },
        {
            "id": "control-2",
            "dataType": "decimal",
            "label": "control 2 label",
            "values": [
            {
                "value": "1.00",
                "repeatIterationIndex": null,
                "type": "single-value"
            }
            ]
        }
        ]
    }
    ]
}

Control extract result

property	type
id	`string`
label	`string`
dataType	`DataType`
values	`ControlValue[]`

Example

json

{
    "id": "control-2",
    "dataType": "decimal",
    "label": "control 2 label",
    "values": [...]
}

Full extract response example

json

{
  "results": [
    {
      "identifier": "form-no-results",
      "type": "form",
      "results": []
    },
    {
      "identifier": "form-example",
      "type": "form",
      "results": [
        {
          "instanceGuid": "a4ebe221-42ae-497d-b026-58992b8f4a52",
          "subjectIdentifier": "subject-1",
          "submittedByUserIdentifier": "user-1",
          "submissionDateTime": "2021-04-11T00:00:00",
          "buildingBlocks": []
        },
        {
          "instanceGuid": "a77a83b4-2e7c-4089-b1ab-eb19fa2794ed",
          "subjectIdentifier": "subject-2",
          "submittedByUserIdentifier": "user-2",
          "submissionDateTime": "2021-11-12T00:00:00",
          "buildingBlocks": [
            {
              "key": "bb-1",
              "controls": []
            },
            {
              "key": "bb-2",
              "controls": [
                {
                  "id": "control-1",
                  "dataType": "string",
                  "label": "control 1 label",
                  "values": []
                },
                {
                  "id": "control-2",
                  "dataType": "decimal",
                  "label": "control 2 label",
                  "values": [
                    {
                      "value": "1.00",
                      "repeatIterationIndex": null,
                      "type": "single-value"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "identifier": "bb-no-results",
      "type": "building-block",
      "results": []
    },
    {
      "identifier": "example-bb",
      "type": "building-block",
      "results": [
        {
          "instanceGuid": "a4ebe221-42ae-497d-b026-58992b8f4a52",
          "subjectIdentifier": "subject-1",
          "submittedByUserIdentifier": "user-1",
          "submissionDateTime": "2021-04-11T00:00:00",
          "controls": []
        },
        {
          "instanceGuid": "a77a83b4-2e7c-4089-b1ab-eb19fa2794ed",
          "subjectIdentifier": "subject-2",
          "submittedByUserIdentifier": "user-2",
          "submissionDateTime": "2021-11-12T00:00:00",
          "controls": [
            {
              "id": "control-1",
              "dataType": "string",
              "label": "control 1 label",
              "values": []
            },
            {
              "id": "control-2",
              "dataType": "decimal",
              "label": "control 2 label",
              "values": [
                {
                  "value": "1.00",
                  "repeatIterationIndex": null,
                  "type": "single-value"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Control value types

Empty value type

Empty value indicates that the control was relevant but the user did not enter any information.

property	type
type	`"empty"`
repeatIterationIndex	`number

Example

json

{
    "repeatIterationIndex": null,
    "type": "empty"
}

Simple value type

property	type
type	`"single-value"`
repeatIterationIndex	`number
value	`string`

Example

json

{
    "value": "bob@example.com",
    "repeatIterationIndex": null,
    "type": "single-value"
}

Single selection value type

property	type
type	`"single-selection"`
repeatIterationIndex	`number
value	`string`
displayName	`string`

Example

json

{
    "value": "1",
    "displayName": "One",
    "repeatIterationIndex": null,
    "type": "single-selection"
}

Multiple selection value type

property	type
type	`"multiple-selection"`
repeatIterationIndex	`number
selections	`Selection[]`

Selection

property	type
value	`string`
displayName	`string`

Example

json

{
    "selections": [
    {
        "value": "1",
        "displayName": "one"
    },
    {
        "value": "2",
        "displayName": "two"
    }
    ],
    "repeatIterationIndex": null,
    "type": "multiple-selection"
}

Geolocation value type

property	type
type	`"geolocation"`
repeatIterationIndex	`number
latitude	`number`
longitude	`number`

Example

json

{
    "latitude": -1.22,
    "longitude": 5.222,
    "repeatIterationIndex": null,
    "type": "geolocation"
}

Annotated image value type

property	type	notes
type	`"annotated-image"`
repeatIterationIndex	`number	null`
imageDataUri	`string`	This is a dataurl of the image and its pins
annotations	`Annotation[]`

Annotation

property	type
position	`number`
value	`string`

Example

json

{
    "imageDataUri": "data:image/*;base64, ...",
    "annotations": [
    {
        "position": 1,
        "value": "The first annotation"
    },
    {
        "position": 2,
        "value": "The second annotation"
    }
    ],
    "repeatIterationIndex": null,
    "type": "annotated-image"
}

Partial date (7.5.0)

property	type
dateKind	`string`
date	`date`
repeatIterationIndex	`number

Example

json

{
    "dateKind": "YYYY-MM",
    "date": "2024-05-01",
    "repeatIterationIndex": null,
    "type": "partial-date"
}

Translatable Text Control (9.2.0)

property	type
originalText	`string`
translatedText	`string`
sourceLanguageCode	`string`
targetLanguageCode	`string`
translatedDateTime	`date
repeatIterationIndex	`number

Example

json

{
    "originalText": "entered text",
    "translatedText": "translated text",
    "sourceLanguageCode": "fr",
    "targetLanguageCode": "en",
    "translatedDateTime": "2024-06-17T11:45:00.000",
    "repeatIterationIndex": null,
    "type": "translatable-text-value"
}

Subject instance extract api

Route: GET /api/v2.0/extract/subject/{subjectIdentifier}/instance/{instance:guid}
Permission: RunExtractsAndReports

This route will return all building blocks and controls for the latest reportable version of this form instance.

Route: POST /api/v2.0/extract/subject/{subjectIdentifier}/instance/{instance:guid}
Permission: RunExtractsAndReports

This route allows you to specify building blocks and controls to narrow down the extract

Post request

property	type	notes
definitions	`BuildingBlockDefinition[]`	Required

Example

json

{
    "definitions": [
        {
          "key": "bb-1"
        },
        {
          "key": "bb-2",
          "controlIds": [
            "control-1",
            "control-4"
          ]
        }
      ]
}

Response

For schema see Form extract result

Example

json

{
  "subjectIdentifier": "patientId",
  "instanceGuid": "9f208b41-46d8-4e36-a5d4-3bde5f571c96",
  "submittedByUserIdentifier": "userId",
  "submissionDateTime": "2022-01-13T11:00:00",
  "buildingBlocks": [
    {
      "key": "bb-a",
      "controls": [
        {
          "id": "control-1",
          "dataType": "string",
          "label": "control 1 label",
          "values": []
        },
        {
          "id": "control-2",
          "dataType": "decimal",
          "label": "control 2 label",
          "values": [
            {
              "value": "1.00",
              "repeatIterationIndex": null,
              "type": "single-value"
            }
          ]
        },
        {
          "id": "control-3",
          "dataType": "string",
          "label": "control 3 label",
          "values": [
            {
              "type": "single-selection",
              "value": "1",
              "displayName": "one",
              "repeatIterationIndex": null
            }
          ]
        },
        {
          "id": "control-4",
          "dataType": "decimal",
          "label": "control 4 label",
          "values": [
            {
              "selections": [
                {
                  "value": "1",
                  "displayName": "one"
                },
                {
                  "value": "2",
                  "displayName": "two"
                }
              ],
              "repeatIterationIndex": null,
              "type": "multiple-selection"
            }
          ]
        },
        {
          "id": "control-5",
          "dataType": "geolocation",
          "label": "control 5 label",
          "values": [
            {
              "latitude": "-1.22",
              "longitude": "5.222",
              "repeatIterationIndex": null,
              "type": "geolocation"
            }
          ]
        },
        {
          "id": "control-6",
          "dataType": "annotated-image",
          "label": "control 6 label",
          "values": [
            {
              "imageDataUri": "data:image/*;base64, dooo",
              "annotations": [
                {
                  "position": 1,
                  "value": "The first annotation"
                },
                {
                  "position": 1,
                  "value": "The second annotation"
                }
              ],
              "repeatIterationIndex": null,
              "type": "annotated-image"
            }
          ]
        },
        {
          "id": "control-7",
          "dataType": "string",
          "label": "control 7 label",
          "values": [
            {
              "repeatIterationIndex": null,
              "type": "empty"
            }
          ]
        },
        {
          "id": "richtext",
          "dataType": "html",
          "label": "Rich Text",
          "values": [
            {
              "value": "<p><br></p><ol><li><strong>This&nbsp;<em>Is</em></strong><em>&nbsp;some rich text </em></li></ol>",
              "repeatIterationIndex": null,
              "type": "single-value"
            }
          ]
        }
      ]
    },
    {
      "key": "bb-b",
      "controls": []
    }]
}

Data types

integer
decimal
string
boolean
email
date
time
datetime
annotated-image
geolocation
html
data-url
url
translatable-text-value

Value Types

empty
single-value
single-selection
multiple-selection
geolocation
annotated-image
translatable-text-value

Value type / Data type mappings

Value type	Supported data types
empty-value	`All`
single-value	`integer
single-selection	`integer
multiple-selection	`integer
geolocation	`geolocation`
annotated-image	`annotated-image`
translatable-text-value	`translatable-text-value`

Extract API v2 ​

Extract definition APIs ​

Form level ​

Building block level ​

Response types ​

Form definition ​

Building block definition ​

Control definition ​

Example form extract definition response ​

Example building block extract definition response ​

Multi extract api ​

Root request ​

Example ​

Form extract request ​

Form extract request - Building Block ​

Example ​

Building block extract request ​

Example ​

Full Example ​

Response ​

Form extract ​

Form extract result ​

Form extract result - building block ​

Example ​

Building block extract ​

Building block extract result ​

Example ​

Control extract result ​

Example ​

Full extract response example ​

Control value types ​

Empty value type ​

Example ​

Simple value type ​

Example ​

Single selection value type ​

Example ​

Multiple selection value type ​

Selection ​

Example ​

Geolocation value type ​

Example ​

Annotated image value type ​

Annotation ​

Example ​

Partial date (7.5.0) ​

Example ​

Translatable Text Control (9.2.0) ​

Example ​

Subject instance extract api ​

Post request ​

Example ​

Response ​

Example ​

Data types ​

Value Types ​

Value type / Data type mappings ​

Extract API v2

Extract definition APIs

Form level

Building block level

Response types

Form definition

Building block definition

Control definition

Example form extract definition response

Example building block extract definition response

Multi extract api

Root request

Example

Form extract request

Form extract request - Building Block

Example

Building block extract request

Example

Full Example

Response

Form extract

Form extract result

Form extract result - building block

Example

Building block extract

Building block extract result

Example

Control extract result

Example

Full extract response example

Control value types

Empty value type

Example

Simple value type

Example

Single selection value type

Example

Multiple selection value type

Selection

Example

Geolocation value type

Example

Annotated image value type

Annotation

Example

Partial date (7.5.0)

Example

Translatable Text Control (9.2.0)

Example

Subject instance extract api

Post request

Example

Response

Example

Data types

Value Types

Value type / Data type mappings