Version: 4.1 (2026-H2)

Connect API

Via the Connect API, third-party systems can use primedocs document generation on the server side via the primedocs Connect interface.

Endpoints

All Connect API endpoints live under …/api/v3/{datasourceId}/Connect. The request body is the primedocs Connect XML. The Connect API runs without a user context (client credentials); for scenarios with a user context and connected services, use the Connect Session API.

Method	Endpoint	Purpose
`POST`	`/Document`	Generates a document and returns the file. With the query parameter `conversion=Pdf` the result is returned as a PDF (default: `None`).
`POST`	`/Result`	Runs the generation and returns a `ConnectResultReport` (JSON). The document itself is handled by a command (e.g. `InvokeUrl`).
`GET`	`/Templates`	Lists the available templates (paged).
`POST`	`/Session`	Creates a Connect Session and returns a link to the web app.
`POST`	`/File`	Deprecated — use `/Document` instead.

warning

/File is deprecated

The former /File endpoint remains for compatibility but redirects to /Document. New integrations should use /Document.

PDF output

POST …/Connect/Document?conversion=Pdf returns the generated document as a PDF. Without the parameter (or conversion=None), the native Office format is returned.

Querying templates (`/Templates`)

GET …/Connect/Templates returns a paged list (query parameters page, pageSize; default 10, max 100). Optional filters:

userQuery — e.g. title:*Letter* field[FIELD.ID]:*value*
templateQuery — e.g. templateId:GUID active:true tags:TAG1;TAG2 localizedName:*Letter*
uiLcid, userId — optional.

Result

The result depends on the template type. In all cases, a file is created.

For Word, Excel and PowerPoint templates, it is a corresponding file.

Outlook

For all Outlook templates, HTML is returned by default, along with a list of linked images in json format:

{
   "Body":"<html><head></head><body><p>Hello World</p>\r\n<p><b>My Firstname</b> My LastName</p>\r\n<img src=\"cid:profile-org-logo-1312016b.png\"></body></html>",
   "AttachmentImages":[
      {
         "Name":"profile-org-logo-1312016b.png",
         "Base64Data":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAAadEVYdFNvZnR3YXJlAFBhaW50Lk5FVCB2My41LjEwMPRyoQAAAA1JREFUGFdj+P//PwMACPwC/ohfBuAAAAAASUVORK5CYII="
      }
   ]
}

Body: Contains the HTML content of the signature or email template. If image data from the profile is accessed in the template (e.g. via <img src="{{Profile.Org.Logo}}" />), the image is replaced via a cid-link and stored in AttachmentImages.
Note: If external images are linked or images are stored directly via base64 in the template/signature, no cid-link is added. This only happens via primedocs images.
AttachmentImages: Contains all cid-images.

<primedocsConnect>
  <Template Id="e76712a7-d7ab-4112-9240-e688522e5f75" />
  <Author>
    <Profile Id="dfc92748-fbf2-4861-bfac-683fec6139fe" />
  </Author>
  <!-- This can be omitted, because this is the default: -->
  <Outlook ContentType="Html" />
</primedocsConnect>

PlainText

PlainText signatures and email templates can also be defined via the Connect API. To do this, Connect must be configured with the Outlook-element:

<primedocsConnect>
  <Template Id="e76712a7-d7ab-4112-9240-e688522e5f75" />
  <Author>
    <Profile Id="dfc92748-fbf2-4861-bfac-683fec6139fe" />
  </Author>
  <Outlook ContentType="PlainText" />
</primedocsConnect>

In this case, the following json is returned:

{
  "PlainTextContent":"My Firstname My Lastname"
}

Authentication and call

To call the Connect APIs, such a client must be registered in the primedocs.config, see primedocs.config.

After registration, an AccessToken can be requested from the IdS. The actual call can then be made against the Connect/Document endpoint of the WebApi using the AccessToken.

This PowerShell example shows how to obtain the AccessToken and call the endpoint:

﻿# Configuration
$datasourceId = "b78c3707-d7c7-4fc7-b97f-87d70f63c1ac"
$tokenUrl = "https://{instanz}/ids/connect/token"
$baseApiUrl = "https://{instanz}/webapi/api"
$clientID = "CustomApiClient"
$clientSecret = "CustomClient_Secret_123"
$scope = "pd_ConnectWebApi"

$tokenRequestHeaders = @{
    "Content-Type" = "application/x-www-form-urlencoded"
}
$tokenRequestBody = @{
    client_id     = $clientID
    client_secret = $clientSecret
    grant_type    = "client_credentials"
    scope         = $scope
}

try {
    $tokenResponse = Invoke-RestMethod -Uri $tokenUrl -Method POST -Headers $tokenRequestHeaders -Body $tokenRequestBody
}
catch {
    Write-Error "Error making the request: $_"
    exit 1;
}
if (-not $tokenResponse.access_token) {
    Write-Error "Failed to obtain an access token!"
    exit 1
}

Write-Host "Access Token: $($tokenResponse.access_token)"
$accessToken = $tokenResponse.access_token

$apiRequestHeaders = @{
    "Authorization" = "Bearer $accessToken"
}

$putBodyRequestHeaders = @{
    "Content-Type"  = "application/json"
    "Authorization" = "Bearer $accessToken"
}

$xmlBodyRequestHeaders = @{
    "Content-Type"  = "application/xml"
    "Authorization" = "Bearer $accessToken"
}

function Show-Menu {
    Write-Host "================ Main Menu ================"
    Write-Host "1: Generate Document"
    Write-Host "2: Validate Connect Form"
    Write-Host "3: Create Connect Session"
    Write-Host "4: Get Templates"
    Write-Host "Q: Exit"
}

function GenerateDocument {
    $connectFilePath = Read-Host "Enter connect file path"
    $proposedFileName = Read-Host "Enter proposed file name (without extension, optional)"
    $outputFilePath = Read-Host "Enter output file path (e.g., C:\\Temp\\Generated.docx)"
    $pdfConversion = Read-Host "Convert result to pdf (y/n, default n)"

    if (-not (Test-Path $connectFilePath)) {
        Write-Error "Connect file not found: $connectFilePath"
        return
    }

    $connectFileContent = Get-Content -Path $connectFilePath -Raw

    $apiUrl = "$($baseApiUrl)/v3/$($datasourceId)/Connect/Document"
    if (![string]::IsNullOrWhiteSpace($proposedFileName)) {
        $apiUrl += "?proposedFileName=$proposedFileName"
    }
    
    if ($pdfConversion -eq "y" -or $pdfConversion -eq "Y") {
        if ($apiUrl -like "*?*") {
            $apiUrl += "&conversion=Pdf"
        }
        else {
            $apiUrl += "?conversion=Pdf"
        }
    }

    try {
        Invoke-WebRequest -Uri $apiUrl -Method POST -Headers $xmlBodyRequestHeaders -Body $connectFileContent -OutFile $outputFilePath
        Write-Host "File saved to: $outputFilePath"
    }
    catch {
        Write-Error "Error making the request: $_"
        exit 1;
    }
}

function ValidateConnectForm {
    $templateId = Read-Host "Enter Template ID"
    $fieldKey = Read-Host "Enter field key"
    $fieldValue = Read-Host "Enter field value"

    $body = @{
        templateId = $templateId
        formValues = @{
            $fieldKey = $fieldValue
        }
    }

    $apiUrl = "$($baseApiUrl)/v3/$($datasourceId)/Connect/Validate"

    try {
        $utf8body = ([System.Text.Encoding]::UTF8.GetBytes(($body | ConvertTo-Json)))
        $response = Invoke-RestMethod -Uri $apiUrl -Method POST -Headers $putBodyRequestHeaders -Body $utf8body
        $response | ConvertTo-Json -Depth 6
    }
    catch {
        Write-Error "Error making the request: $_"
        exit 1;
    }
}

function CreateConnectSession {
    $connectFilePath = Read-Host "Enter connect file path"

    if (-not (Test-Path $connectFilePath)) {
        Write-Error "Connect file not found: $connectFilePath"
        return
    }

    $connectFileContent = Get-Content -Path $connectFilePath -Raw

    $apiUrl = "$($baseApiUrl)/v3/$($datasourceId)/Connect/Session"

    try {
        $response = Invoke-RestMethod -Uri $apiUrl -Method POST -Headers $xmlBodyRequestHeaders -Body $connectFileContent
        Write-Output "SessionId: $($response.sessionId)"
    }
    catch {
        Write-Error "Error making the request: $_"
        exit 1;
    }
}

function GetTemplates {
    $pageSize = Read-Host "Enter pagesize"
    $page = Read-Host "Enter page"
    $userId = Read-Host "Enter userId (or empty)"
    $userQuery = Read-Host "Enter userQuery (or empty)"
    $templateQuery = Read-Host "Enter templateQuery (or empty)"
    $uiLcid = Read-Host "Enter uiLcid (or empty)"

    $apiUrl = "$($baseApiUrl)/v3/$($datasourceId)/Connect/Templates?pageSize=$($pageSize)&page=$($page)"

    if (![string]::IsNullOrWhiteSpace($userId)) { $apiUrl += "&userId=$userId" }
    if (![string]::IsNullOrWhiteSpace($userQuery)) { $apiUrl += "&userQuery=$userQuery" }
    if (![string]::IsNullOrWhiteSpace($templateQuery)) { $apiUrl += "&templateQuery=$templateQuery" }
    if (![string]::IsNullOrWhiteSpace($uiLcid)) { $apiUrl += "&uiLcid=$uiLcid" }

    try {
        $response = Invoke-RestMethod -Uri $apiUrl -Method GET -Headers $apiRequestHeaders
        foreach ($template in $response.data) {
            Write-Output "$($template.id): $($template.localizedName)'"
        }
        Write-Output "Page: $($response.pagingDetails.page) / $($response.pagingDetails.totalPages)"
    }
    catch {
        Write-Error "Error making the request: $_"
        exit 1;
    }
}


do {
    Show-Menu
    $selection = Read-Host "Please select an option"

    switch ($selection) {
        '1' { GenerateDocument }
        '2' { ValidateConnectForm }
        '3' { CreateConnectSession }
        '4' { GetTemplates }
        'Q' { break; }
        Default {
            Write-Host "Invalid option selected"
        }
    }
} while ($selection -ne 'Q')

Swagger / Open API

The current Connect API Open API looks as follows. You can visualise this description using the Swagger Editor, for example.

{
    "openapi": "3.0.1",
    "info": {
        "title": "primedocs WebApi",
        "version": "v3"
    },
    "paths": {
        "/api/v3/{datasourceId}/Connect/Document": {
            "post": {
                "tags": ["Connect"],
                "parameters": [
                    {
                        "name": "proposedFileName",
                        "in": "query",
                        "schema": { "type": "string" }
                    },
                    {
                        "name": "conversion",
                        "in": "query",
                        "schema": { "type": "string", "enum": ["None", "Pdf"] }
                    },
                    {
                        "name": "datasourceId",
                        "in": "path",
                        "required": true,
                        "schema": { "type": "string", "format": "uuid" }
                    }
                ],
                "responses": {
                    "200": { "description": "Success" }
                }
            }
        }
    }
}

Endpoints​

PDF output​

Querying templates (/Templates)​

Result​

Outlook​

PlainText​

Authentication and call​

Swagger / Open API​