Skip to main content
Version: 4.0 (2026 H1)

Connect API

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

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/File 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://primedocs.example.org/ids/connect/token"
$connectUrl = "https://primedocs.example.org/webapi/api/v3/$datasourceId/connect/file"

$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
}

# Request the access token

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
}

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

# Prepare headers for request
$apiRequestHeaders = @{
    "Authorization" = "Bearer $accessToken"
    "Content-Type" = "application/xml; charset=utf-8"
}

$xmlBody = @"
<primedocsConnect>
  <Template Id="30b55516-80b5-41d7-801b-b31d6da376ac" />
  <Author><Profile Id="191d8f76-16e5-43fb-a6df-03b234b9d32a" /></Author>
  <Forms>
    <Value Key="Subject">From Sample Script</Value>
    <Value Key="Notes">Sample Note</Value>
  </Forms>
  <Data>
    <Value Key="InvoiceNumber">1234</Value>
  </Data>
</primedocsConnect>
"@


Write-Host "Invoke Connect..."
try {
    $filePath = "C:\temp\test.docx"

    $response = Invoke-RestMethod -Uri $connectUrl -Method POST -Headers $apiRequestHeaders -Body $xmlBody -OutFile $filePath 
    
    Write-Host "Connect result file saved at: $($filePath)"
}
catch {
    Write-Error "Error making the request: $_"
    exit 1;
}

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/File": {
            "post": {
                "tags": ["Connect"],
                "parameters": [
                    {
                        "name": "proposedFileName",
                        "in": "query",
                        "schema": { "type": "string" }
                    },
                    {
                        "name": "datasourceId",
                        "in": "path",
                        "required": true,
                        "schema": { "type": "string", "format": "uuid" }
                    }
                ],
                "responses": {
                    "200": { "description": "Success" }
                }
            }
        }
    }
}