Editor integration

Use these calls to let your users edit a document in the Pages Editor before it is distributed. Your system creates a document instance, sends the user to the Editor, and then follows the instance until the user has finished.

Paths on this page leave out the optional environment group. The common parts of every call are on Calling the Pages API. For every endpoint with its fields, see the API reference at https://webeditor.metaforce.net/documentation-api.

The OpenAPI specification can be downloaded from the API reference and used in Postman to try the calls.

Client applications written in .NET can use the NuGet package Metaforce.WebEditor.Api.Client that makes it even easier to integrate with the Pages API.

Interactive document editing and management

Listing all available online document templates

GET /{customerEnvironment}/onlinedocuments/{metaFile}

The client system makes a call to the Pages API to get a list of available online document templates in the specific logic file. The response contains a structure of templates where each document template can contain a list of keywords/tags that can be used to filter relevant templates in the context of the user. Each template also shows its name, its description, whether it has a process, and its AttributeStoreKey when it has one. The response also lists, in Distributions, the distribution channels that the Editor’s end form offers in this environment.

Select template and initiate the Editor

POST /{customerEnvironment}/dxml/create

The user selects a template and the client system instantiates a document instance from the specific logic file together with XML data and an optional callback/webhook endpoint for the Editor to call once the document instance is completed.

POST /{customerEnvironment}/dxml/create/jsondata

Creates a document instance with JSON data (instead of XML). The request and the response are the same.

The request body has these fields:

{
  "MetaFile": "OrderConfirmations",
  "Document": "OrderConfirmation",
  "DataAsBase64": "PE9yZGVyPjxDdXN0b21lcj5Ob3JkbHlzIEFTPC9DdXN0b21lcj48TnVtYmVyPjEwMDQyPC9OdW1iZXI+PC9PcmRlcj4=",
  "UserName": "kari.nordmann",
  "SenderCallBackEndpoint": "https://client.example.com/pages-callback"
}

The response contains these fields:

{
  "DxmlUID": "03755a3e-bdbf-44ef-98b7-af89feb88644",
  "StartURL": "https://.../WebEditor/x7bHmq...",
  "JWT": "eyJhb...",
  "ValidTo": "2026-10-06T08:15:00Z"
}

The client system should store the DxmlUID, StartURL and ValidTo to keep track of the specific document instance.

If the data should not produce a document, the call returns 204. If something is missing in the logic file, it returns 406.

JWT token

The client system uses the StartURL to initiate the Editor for the user. If the environment has “Require JWT Authentication” turned on one also has to append the query parameter “jwt=JWT token” to the URL.

Editing the document instance, select distribution channel and CallBack

The user edits the document and finally approves the document. This leads to the distribution endform where the user selects the distribution channel of choice to the receiving customer. If the document instance has been started with a defined callback a request will be made to the endpoint. A request will also be made if the user discards the document instance. The third reason for a webhook to be made is when the system does maintenance and deletes an instance that is in draft state.

When you set SenderCallBackUserName and SenderCallBackPassword, every callback carries a Basic authentication header with them, so you can protect your endpoint.

CallBack format

The structure of the callback URL depends on the configured distribution scenario. The callback is an HTTP GET request.

CallBack format - No distribution

In this scenario, the HTTP GET request will look like:

https://host.domain.net/03755a3e-bdbf-44ef-98b7-af89feb88644?Status=OK

• 03755a3e-bdbf-44ef-98b7-af89feb88644 is the DxmlUID.
• Status=OK indicates that the process completed successfully and the document is ready.
• The Status parameter can also have the value Discarded to indicate user cancellation or Deleted to indicate that a document in Draft mode has been deleted by the system.

CallBack format - OmniChannel/MFDX distribution

In this scenario, the HTTP GET request will include additional parameters:

https://host.domain.net/03755a3e-bdbf-44ef-98b7-af89feb88644?Status=OK&Id=33755a3e-bdbf-44ef-98b7-af89feb88666&CorrelationId=93755a3e-bdbf-44ef-98b7-af89feb88655&Distribution=OnPremArchiving

• Id: A customer-provided identifier (empty if not provided).
• CorrelationId: The correlation ID from OmniChannel/MFDX.
• Distribution: The selected distribution method (e.g., OnPremArchiving).

CallBack format - Dynamo

In this case, the HTTP GET request includes Dynamo specific identifiers:

https://host.domain.net/03755a3e-bdbf-44ef-98b7-af89feb88644?Status=OK&Id=33755a3e-bdbf-44ef-98b7-af89feb88666&JobId=12312&DocId=1&Distribution=CentralDistribution

• JobId and DocId represent indexes from the Dynamo database.
• Other parameters follow similar meanings as above.

Retrieving a new JWT token

GET /{customerEnvironment}/dxml/jwt/{startParameter}

Submit the startParameter (the last part of the StartURL) to retrieve a new JWT token. The call returns 200 with the token, or 204 when the environment does not require JWT authentication.

The startParameter is the “x7bHmq…” in the sample below

https://webeditor.metaforce.net/WebEditor/x7bHmq...

Client system checking document instance status

A document instance has one of these statuses: Draft (the user is still editing), OK (the user approved it), Discarded and Deleted (removed by maintenance).

In the search, repeat status to match several statuses, for example status=OK&status=Draft. Without any parameter the search returns all instances of your company. A start time after its end time fails with error (018). In this call an environment group, when you use one, goes in the query parameter environmentGroupNameOrId instead of the path. The search is part of newer versions. If your environment answers 405 to it, use the draft and OK calls instead.

The client system can use different methods to check the document instance status:

1. Using the callback/webhook attribute when initiating a document instance. The callback will be made once the user has approved the document instance. This process flow is more advanced but will enable a faster overall process.

2. Scheduled job that uses the endpoints to either check the specific document instance using the DxmlUID or the more generic endpoints to list all document instances in Draft or Ok status.

Discarding an instance from the client system

PUT /{customerEnvironment}/status/discard/{dxmlUID}

Sets the instance to Discarded, for example when the case it belongs to is closed. Pages sends the callback with Status=Discarded and writes the change to the audit log. The call returns 200, or 404 when the instance does not exist.

Creating output from a stored instance

You can create a finished document from an instance that is still stored, without opening the Editor.

Each call returns 404 when the instance does not exist.

Document instance maintenance

The Pages service will maintain the created document instances and delete any instance older than 5 days, or the number of days set in the retention policy of the environment.

All data stored is encrypted according to best practices.

A document instance will be removed regardless of whether it has been published or not, according to the configured retention period (or standard 5 days). If the document hasn’t been finalized and if a callback has been provided, the callback endpoint will receive a request with the document status “Deleted”. If one does a status search for a deleted DxmlUID the response will be 404 (NotFound).

You can also work with the stored instance yourself:

Delaying instance deletion

If needed one can delay the deletion of a document instance by doing PUT with a datetime in the body to the endpoint below. The body is only the datetime, for example "2026-10-20T00:00:00Z". The call returns 200, or 404 when the instance does not exist.

PUT /{customerEnvironment}/dxml/{dxmlUID}