Environments and languages in the API

A Smartform has a version in each of the four environments, Development, Test, Pre Production and Production. See Deployment. This page shows how an API call says which version it uses, what comes back, and how to get a PDF in a chosen language.

Every host on this page follows the environment you pick here.

The API names the environments Development, Test, PreProduction and Production, in any letter case. Studio writes Pre Production with a space. Use the name without a space in the API.

Where the environment goes

Call	Environment	What it does
`POST /Integrations/dialog/json`	In the body or the path	Creates a form from the version published to that environment.
`POST /Integrations/dialog/json/pdf`	In the body or the path	Creates the form and returns it as a PDF.
`POST /Integrations/dialog/json/submit/pdf`	In the body or the path	Creates the form, submits it and returns it as a PDF.
`GET /Integrations/dialogValues/{id}`	In the path	Checks that the record belongs to that environment, then returns its values.
`GET /Integrations/dialogDefinitions/{definitionId}/dialogValues/{id}/pdf`	In the path	Checks the record, then returns it as a PDF.
`POST /Integrations/pdf/create`	In the path	Checks the record, then returns it as a PDF.
`GET /Integrations/ping`	In the path	Answers when the API and your token work.

The calls that create a form run the version deployed to the environment you name. The calls that read an existing record do not run a version. The environment in their path only checks the record: a record filed in another environment answers 404 Not Found. Records created before Doc Gen started to record the environment match any environment.

Path or body

Name the environment as the first part of the path:

curl --location 'https://api.smartforms.metaforce.net/Test/Integrations/dialog/json' --header 'Content-Type: application/json' --header 'Authorization: Bearer <your_token>' --data '{
"dialogDefinitionId": "653689ddc3332022ee018626",
"values": { "Name": "Kari Nordmann" }
}'

Or as a field in the body. The two calls do the same:

curl --location 'https://api.smartforms.metaforce.net/Integrations/dialog/json' --header 'Content-Type: application/json' --header 'Authorization: Bearer <your_token>' --data '{
"dialogDefinitionId": "653689ddc3332022ee018626",
"environment": "Test",
"values": { "Name": "Kari Nordmann" }
}'

You can name it in both places when the names are the same. Different names give 400 Bad Request.
A name that is not one of the four gives 400 Bad Request from the body. In the path, the address does not exist.
Leave the environment out and the call uses the current saved version of the Smartform, the same as calls made before environments existed.

What comes back

When a create call names an environment, the answer tells which version ran:

{
  "id": "6697afe9b039be06934828bc",
  "dialogDefinitionId": "653689ddc3332022ee018626",
  "resolvedEnvironment": "Test",
  "versionKey": "a3c1f0e2"
}

The answer also holds the other fields of the new form. The sample shows the ones that matter here.

resolvedEnvironment is the environment that was used. versionKey identifies the published version, so you can follow a form across promotions. Both have no value when the call named no environment, and versionKey has no value when the deployment does not record one. Handle a missing value in your code.

When the Smartform is not published there

A Smartform that was never published to the environment answers 404 Not Found:

{
  "Error": "SmartformNotDeployed",
  "Environment": "Test",
  "Message": "..."
}

There is no fall back to another version. This is also true for Development. Publish the Smartform to that environment first, see Publish Smartforms. Branch on Error and not on the text in Message.

Read a definition

curl --location 'https://api.smartforms.metaforce.net/api/Test/dialogDefinitions/653689ddc3332022ee018626'

This call returns the design of the Smartform as deployed to the environment. It needs no token. The environment can be in the path, as above, or in a query parameter: /api/dialogDefinitions/{id}?environment=Test.

Unlike the create calls, an environment the Smartform was never published to returns the current saved design, the same as Development or no environment. GET /api/{environment}/dialogDefinitions/{id}/process returns the process type. Its definitionProcessId is the same in every environment.

Language

These calls take a languageCode query parameter:

POST /Integrations/dialog/json/pdf
POST /Integrations/dialog/json/submit/pdf
GET /Integrations/dialogDefinitions/{definitionId}/dialogValues/{id}/pdf

curl --location 'https://api.smartforms.metaforce.net/Integrations/dialog/json/pdf?languageCode=no' --header 'Content-Type: application/json' --header 'Authorization: Bearer <your_token>' --data '{ "dialogDefinitionId": "653689ddc3332022ee018626", "values": { "Name": "Kari Nordmann" } }' --output form.pdf

The PDF is made in that language. Leave it out to use the Smartform’s default language. POST /Integrations/pdf/create has no languageCode. The languages come from the Translations of the Smartform.

What the PDF calls do

Call	Behaviour
`dialog/json/pdf`	Nothing is sent to the parties in the request. The PDF comes back in the answer.
`dialog/json/submit/pdf`	Submits the form. The parties listed in `participatingParties` are notified by e-mail or SMS, as set in the request. Send no parties if you only want the PDF. A Smartform with several steps completes only the step, so the record stays In progress and no completion message is sent. Check the record and do not treat the PDF as proof that it closed.
`GET .../dialogValues/{id}/pdf`	Adds the PDF files held as toolbar attachments. Files uploaded into the form’s own fields are not part of the PDF. A file that is skipped is skipped without a message.
`pdf/create`	The record is named in the body. Attached files are not added to the PDF.

Render PDFs with the API renders many records in the background.
Webhooks sends the environment in the payload.
Filling elements with API has a request example for every element type.