Business Context

Organizations often need to deliver merged, data-driven documents directly to a recipient's inbox without manual intervention. By combining the Composer Merge API with an email template, a company can generate a document from a JSON payload, render it to PDF, and email it automatically as part of a broader integration or business process. This reduces manual document handling, ensures consistent branding and content, and speeds up delivery to customers or internal stakeholders.

Objective

Enable a system integrator or developer to programmatically merge a template with JSON data, convert the output to PDF, and send the generated document to a specified email address using the Composer REST API.

Actors/Roles

• Integration developer at a company implementing the Composer API.
• Composer Platform: generates the merged document and sends the email on behalf of the integration.
• Recipient: the person or system at the designated email address who receives the generated document.

Prerequisites

• The company's Account Executive has enabled the Composer API feature using the 18-digit Salesforce OrgID.
• A Client ID and Client Secret have been generated for authenticating to the Conga Authorization server.
• Email integration settings are configured on the platform.
• An email template has been created on the Conga Platform, and its File ID is available.
• A cloud storage integration (for example, Box) hosts the template referenced by the merge request.

Trigger

The use case begins when the integration submits a merge request to the Composer Merge API with a JSON data payload and email delivery options, typically as part of an automated business process such as quote finalization, order confirmation, or proposal delivery.

Tasks

1. Prepare the template. Create an email template on the Conga Platform and note its File ID for use in the merge request. For more information, see JSON Payload Template Example and Creating an Email Platform Template.

2. Retrieve the Conga authentication token. Call the token endpoint to obtain a bearer token used for subsequent API calls.

   Table 1. Authentication Request

   End Point	https://services.congamerge.com/api/v1/auth/connect/token
   Request 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>

3. Create and submit the merge request. Build a merge request body that includes the LegacyOptions, JsonData, TemplateSources, and output parameters, then submit it to the Merge API endpoint.

   • DefaultPdf: generates the output document in PDF format.
   • OFN: overrides the default output file name.
   • CongaEmailTemplateId, EmailAdditionalTo, and EmailFromId: configure the email template and delivery addresses.
   • JsonData: the JSON payload used to merge into the template. Escape double quotes within the value.
   • TemplateSources: identifies the cloud storage integration (for example, box) and the template File ID.
   • output.generateDocumentDownload: must be set to true.

   The Merge API returns a correlationId and a status of Accepted.

4. Check the merge request status. Poll the status endpoint using the correlationId returned in the previous task, repeating the call with a delay until the status changes from Pending to Completed or Error.

5. Verify the email was generated. Check the target email address to confirm that the email and the generated document were received.

Variations

This use case can be adapted to generate and download a document without emailing it, to send the generated document to multiple recipients, or to source the template from a different cloud storage integration. It can also be combined with other Composer API use cases, such as generating a document for e-signature.

Tips and Best Practices