Business Context

Organizations that generate high volumes of business documents, such as proposals, contracts, or order confirmations, often store reusable templates in a cloud storage provider and need to merge those templates with dynamic data at the time of generation. Rather than manually assembling documents, an integration developer can use the Composer API to programmatically merge a stored template with JSON data, produce a PDF, and deliver it directly to an end user or downstream system. This approach reduces manual effort, ensures consistent formatting, and allows document generation to be embedded into existing applications or workflows.

Overview

In this use case, a template saved in a Box account is merged with JSON data, converted to PDF format, and downloaded. The Composer parameters that control this behavior are included in the LegacyOptions tag of the merge request body, along with a JSON payload in the JsonData tag and template source details in the TemplateSources tag.

Actors/Roles

• Integration developer: Configures the API client, authenticates to the Conga Authorization server, and submits the merge and download requests.
• Composer API: Processes the merge request, generates the document, and makes it available for download.
• Cloud storage provider (Box): Stores the source template referenced by the merge request.

Prerequisites

• The Composer API feature is enabled for the Salesforce org. Contact your Account Executive with your 18-digit Org ID to enable this feature.
• A Client ID and Client Secret have been generated for connecting to the Conga Authorization server. See Authentication.
• A template containing the required merge fields has been created and uploaded to a Box account folder, and its File ID has been noted.

Trigger

An integration developer initiates the process by submitting a merge request to the Composer API that references a template stored in Box and includes a JSON data payload. The request explicitly sets generateDocumentDownload to true under output, which signals that the resulting document should be made available for download rather than routed through another delivery method.

Tasks

1. Prepare the template and store it in the Box account folder. Create a template that contains the required merge fields and upload it to the Box folder. Note the template's File ID for use in the merge request.

2. Retrieve the Conga authentication token. Call the Composer REST API token endpoint using the Client ID and Client Secret to obtain a bearer token required for subsequent requests.

   Field	Value
   Endpoint	https://login-rls.congacloud.com/api/v1/auth/connect/token
   Method	POST
   Request header	Content-Type: application/x-www-form-urlencoded
   Request body	grant_type=client_credentials&scope=doc-gen.composer&client_id=<congaAuthClientId>&client_secret=<congaAuthClientSecret>

   The response includes an access_token, its expires_in value (in seconds), and the token_type (Bearer).

3. Create and submit the merge request. Submit a merge request that includes the PDF output option and output file name in LegacyOptions, the merge data in JsonData, the Box template reference in TemplateSources, and generateDocumentDownload set to true.

   Note: Escape double quotes inside the JsonData tag with a backslash (\).

   Field	Value
   Endpoint	https://coreapps-rlsprod.congacloud.com/api/ingress/v1/Merge
   Method	POST
   Request header	Authorization: Bearer <congaAuthToken>; Content-Type: application/json

   {
     "LegacyOptions": {
       "DefaultPdf": "1",
       "OFN": "Box + Document Download Testing"
     },
     "JsonData": "{\"firstName\":\"John\",\"lastName\":\"Doe\",
       \"executiveSummary\":\"Below, you will find a proposal, etc. etc.\",
       \"products\":[{\"name\":\"test product\",\"quantity\":5,
       \"price\":10,\"total\":50},{\"name\":\"Creative Name\",
       \"quantity\":10,\"price\":20,\"total\":200}]}",
     "TemplateSources": [
       {"IntegrationName":"box", "FileId": "{{FileId}}"}
     ],
     "output": {"generateDocumentDownload": true}
   }

   A successful response returns a correlationId and a status of Accepted.

4. Check the merge request status. Poll the status endpoint using the correlationId from the previous step until the status changes from Pending to Completed or Error.

   Field	Value
   Endpoint	https://coreapps-rlsprod.congacloud.com/api/status/v1/status/{correlationId}
   Method	GET
   Request header	Authorization: Bearer <congaAuthToken>

5. Get the downloadable URL. Once the status is Completed, call the pre-signed service endpoint using the correlationId (as lookupId) to retrieve the URL for the generated document.

   Field	Value
   Endpoint	https://coreapps-rlsprod.congacloud.com/api/presigned/v1/PreSignedService/{lookupId}
   Method	GET
   Request header	Authorization: Bearer <congaAuthToken>

   The response contains isSuccessful and a URL similar to https://ENVIRONMENT_DOMAIN/PreSignedService/{lookupId1}/{lookupId2}/{{filename}}.

6. Download the document. Parse lookupId1 and lookupId2 from the URL returned in the previous step, and call the download endpoint to retrieve the generated document.

   Field	Value
   Endpoint	https://coreapps-rlsprod.congacloud.com/api/presigned/v1/PreSignedService/{lookup1}/{lookup2}
   Method	GET
   Request header	Authorization: Bearer <congaAuthToken>

Result

Variations

This use case can be adapted to reference a template stored in a different cloud storage provider, such as AWS, SharePoint, Google Drive, Dropbox, OneDrive, Salesforce, or SFTP, by changing the IntegrationName value in TemplateSources. It can also be adapted to generate the document in a different output format, or to deliver the generated document by email instead of a direct download.

Tips and Best Practices