Participating parties

Add a notification block to the request that creates a Smartform to send the new form to people by email or SMS. Each person is a participating party.

Find the party ids

A multi-step Smartform has participating parties, such as an employee and a manager. To list the parties of a Smartform with their ids, call:

GET https://api.smartforms.metaforce.net/Integrations/{dialogDefinitionId}/participatingParties

Each item in the response has an id, a name, a defaultLanguage, a companyId and a dialogDefinitionId. Older Smartforms that were set up with a list of phone numbers return one item per number instead, with a phoneNumber and with id and name set to null.

The notification block

"notification": {
    "sendEmail": true,
    "sendSms": false,
    "participatingParties": [
        {
            "id": "Employee",
            "name": "Ingrid Berg",
            "email": "ingrid.berg@example.com",
            "phone": "+4790000000",
            "languageCode": "nb"
        }
    ]
}

Field	What it is
`sendEmail`, `sendSms`	Which channels to use.
`participatingParties`	The people to send to. If the list is empty, nothing is sent.

Each party takes these fields:

Field	What it is
`id`	The id of the party, or its name. Doc Gen matches a name to the parties of the Smartform without regard to case.
`name`	The name of the person.
`email`, `phone`	Where to send. Use the phone number in international format.
`nationality`	The nationality of the person.
`ssn`, `birthDate`	Doc Gen stores a hash of these values, never the plain text.
`languageCode`	The language of the notification.

Single-step and multi-step forms

A single-step Smartform has one receiver. Only the first party in the list is used, with its name, email and phone.
A multi-step Smartform has one party per step. Each party in the list is matched to a step by id or by name.

When nothing is sent

With no participating parties, the form is created and nobody is notified.
The PDF call POST /Integrations/dialog/json/pdf never notifies anyone. The submit variant does.

Example

This example creates a two-step form and sends a notification to each party. Use your own addresses when you try it.

const axios = require('axios').default;

async function main() {
  var client_id = 'ex_e0JBQ0I3NTQyLUE1NzgtNDI0Nixxxxxxxxxxxxxxxx';
  var client_secret = 'ezMzMjA2MTU5LTRGNTktNDM5Mixxxxxxxxxxxxxxxx';
  var idDialogId = '646f3df4f70bcab31bsssssssss';

  var authHeader = 'Basic ' + Buffer.from(client_id + ':' + client_secret).toString('base64');

  const tokenOptions = {
      method: 'POST',
      url: 'https://identity-v2.metaforce.net/connect/token',
      headers: { 'content-type': 'application/x-www-form-urlencoded', 'Authorization': authHeader },
      data: 'grant_type=client_credentials&scope=api.external'
  };

  try {
      var tokenResponse = await axios.request(tokenOptions);
      axios.defaults.headers.common['Authorization'] = `Bearer ${tokenResponse.data.access_token}`;

      const SmartformBody = {
          dialogDefinitionId: idDialogId,
          notification: {
              sendSms: false,
              sendEmail: true,
              participatingParties: [
                  { id: 'Employee', name: 'Ingrid Berg', email: 'ingrid.berg@example.com', phone: '+4790000000' },
                  { id: 'Manager', name: 'Ola Dahl', email: 'ola.dahl@example.com', phone: '+4790000001' }
              ]
          },
          values: {
              Headline: 'Employee onboarding'
          }
      };

      var postResponse = await axios.request({
          method: 'POST',
          url: 'https://api.smartforms.metaforce.net/Integrations/dialog/json',
          headers: { 'Content-Type': 'application/json' },
          data: SmartformBody
      });
      console.log(postResponse.data.id);
  } catch (error) {
      console.error('Error:', error.message);
  }
}

main();