External data

A request that creates a Smartform can carry data in three places: values fills fields and editable text, dataTableValue holds data the form shows through placeholders, and externalMetaData travels with the form back to your system. This is the usual round trip:

See Variables and placeholders for how the Smartform shows this data. To send the form to people, see Participating parties. To get a PDF, see PDF. To list, read or delete forms, see Read and delete forms.

Values and editable text

values fills the fields of the Smartform by their property name, as in Prefilled values. A name that matches no field is kept too: it answers the editable text with that name, or holds the option list of a type=select editable text that names it in source=.

"values": {
    "employeeName": "Jon Jonsson",
    "annualSalary": "700 000"
}

Here employeeName fills the Employee name field and annualSalary fills [[ INPUT : annualSalary ]] in the text of the form. The person can still change it.

dataTableValue

Data table values are data the Smartform shows without a field of its own. Refer to them in the Smartform with a placeholder such as [[ ManagerName ]]; Studio colours it blue.

"dataTableValue": {
    "ManagerName": "Ola Nordmann",
    "address": { "street": "Harbour street 23", "city": "Oslo" }
}

• A nested value is reached with a dot: [[ address.street ]].
• The field name dataTableValues is accepted too. It is the name used in webhook payloads, so you can pass a payload’s data straight into a new form.
• Always put a space on both sides of the name inside the brackets: [[ ManagerName ]]. The PDF and the webhook accept [[ManagerName]] without spaces, but the form on screen does not fill it in.
• Give every placeholder a value. A missing value shows as nothing on the form, but the PDF can print the placeholder itself.
• The Smartform’s Rules can add and change data table values. See Rules variables.
• An editable text can take its default from a data table value: [[ INPUT : contactPerson | default=$ManagerName ]].

ExternalMetaData

External metadata follows the Smartform and helps you connect the result to a record in another system. For example, a Smartform is created from a case in a CRM system: the case reference travels with the form, is returned as ExternalMetaData in the webhook and when you fetch the form, and lets your system match the result to the case. It is not shown on the form.

"externalMetaData": {
    "CRM_Key": "918203981203",
    "Case_Key": "0209384028340"
  }

Other request fields

These optional fields can be sent next to values:

You can also name the environment in the path instead of the body:

POST https://api.smartforms.metaforce.net/Test/Integrations/dialog/json

Example

This example body contains both ExternalMetaData and dataTableValue.

{
    "dialogDefinitionId": "64e4a31fdf775xxxxxxxxxxxx",
    "notification": 
    {
        "sendSms": true,
        "sendEmail": true,
        "participatingParties": 
        [
            {
                "id": "Reciever", 
                "name": "Peter",
                "email": "xxxxxxxxxl@doxis.se",
                "phone": "+46999999999999"
            }
        ]
    },
    "dataTableValue": {
        "ext1": "Leading the paperless revolution",
        "ext2": "test 1",
        "ext3": "test 2"
    },
 
    "externalMetaData": {
    "CRM_Key": "918203981203",
    "Case_Key": "0209384028340"
  },
    "values" : 
    {
        "Headline":"Doxis", 
        "List1":"V1",
        "drp1" : "V3"
    }
}

Reading a form back

Fetch a form with its id:

GET https://api.smartforms.metaforce.net/Integrations/dialogValues/{id}?readableValues=true

• Without readableValues, the response has the same shape as the webhook: a Values array, integrationValues and DataTableValues. Editable text answers are not in this shape.
• With readableValues=true, the response has values, with the answers by property name and the editable text answers in inlineInputs, and datatablevalues. Editable text answers are given as they are printed: a date in its format, a select as its display text.
• omitImagesAndFiles leaves uploaded images and files out. It is on by default.
• includeRawValues and IncludeFlattenedValues have no effect.
• With an environment in the path, for example /Test/Integrations/dialogValues/{id}, a form that belongs to another environment is reported as not found. Forms created before environments were recorded are returned for any environment.

"values": {
    "employeeName": "Jon Jonsson",
    "department": "sales",
    "inlineInputs": {
        "firstWorkingDay": "01.12.2026",
        "employmentType": "Permanent",
        "annualSalary": "720 000"
    }
},
"datatablevalues": {
    "ManagerName": "Ola Nordmann",
    "OfficeLocation": "Oslo",
    "ProbationMonths": "6"
}

The webhook sent when a form is submitted uses the shape without readableValues. To read editable text answers, fetch the form with readableValues=true.