Integrations

Connect your CRM, database, or spreadsheet to generate dynamic PDFs with real data. This guide covers all supported integrations and how to set them up.

Overview

Our platform supports four data source integrations:

---

Salesforce Integration

Overview

Connect your Salesforce org to access all your CRM data for document generation. This includes:

• Standard and custom objects
• Related records and lookups
• Child relationships for tables
• File attachment capabilities

Prerequisites

Before connecting Salesforce, you need to create a Connected App in your Salesforce org. This requires Salesforce administrator privileges.

Creating a Salesforce Connected App

Follow these steps to create and configure a Connected App:

Step 1: Access App Manager

1. Log in to Salesforce as an administrator
2. Click the gear icon (⚙️) in the top-right corner
3. Select Setup
4. In the Quick Find box, type App Manager
5. Click App Manager under Apps

Step 2: Create a New Connected App

1. Click New Connected App in the top-right corner
2. Fill in the Basic Information:
   • Connected App Name: PDF Generator (or your preferred name)
   • API Name: This auto-fills based on the name
   • Contact Email: Your email address

Step 3: Configure OAuth Settings

1. Check Enable OAuth Settings

2. Set the Callback URL to:

   https://datatopdf/api/salesforce/callback
   

3. Select the following OAuth Scopes (move from Available to Selected):

   • Access and manage your data (api)
   • Perform requests on your behalf at any time (refresh_token, offline_access)
   • Access your basic information (id, profile, email, address, phone)
   • Full access (full) - Optional but recommended for full functionality

4. Leave other settings as default:

   • Require Secret for Web Server Flow: Checked (default)
   • Require Secret for Refresh Token Flow: Checked (default)

5. Click Save

Step 4: Wait for Activation

After saving, Salesforce displays a message that changes can take up to 10 minutes to take effect. In practice, it's usually ready within 2-5 minutes.

Step 5: Retrieve Your Credentials

1. After saving, click Continue to view the Connected App details
2. Click Manage Consumer Details (you may need to verify your identity)
3. Copy and save these values:
   • Consumer Key (this is your Client ID)
   • Consumer Secret (this is your Client Secret)

Step 6: Configure OAuth Policies (Recommended)

After creating your Connected App, configure the OAuth policies for easier connectivity:

1. From the Connected App page, click Manage
2. Click Edit Policies
3. Configure the following settings under OAuth Policies:

Key settings to configure:

1. Enable the following Flows :

1. Click Save

Connecting Salesforce

Once your Connected App is created, you can connect it to the PDF Generator:

Step 1: Enter Credentials

1. Go to Settings → Salesforce
2. Enter your Client ID (Consumer Key)
3. Enter your Client Secret (Consumer Secret)
4. Click Save Credentials

Step 2: Authorize Access

1. Click Connect Salesforce
2. You'll be redirected to Salesforce login
3. Enter your Salesforce credentials
4. Review the permission request
5. Click Allow to authorize

Step 3: Verify Connection

1. You'll be redirected back to the app
2. The status should show "Connected"
3. Your Salesforce instance URL will be displayed

What Gets Connected

Selecting an Object

When creating a template:

1. Choose Salesforce as your data source
2. Select the object type (Account, Contact, Opportunity, etc.)
3. Available fields for that object are loaded automatically

Standard Objects

Common Salesforce objects available:

• Account
• Contact
• Opportunity
• Lead
• Case
• Quote
• Order
• Custom Objects (ending in __c)

Field Access

Fields available depend on your Salesforce permissions:

• Standard fields (Name, Email, Phone, etc.)
• Custom fields (My_Field__c)
• Formula fields
• Lookup fields

Parent Relationships

Access related record data:

{{Account.Name}}          → Parent account name
{{Owner.Name}}            → Record owner
{{CreatedBy.Name}}        → User who created record
{{Account.Owner.Name}}    → Account owner's name

Child Relationships

For tables, access related records:

{{OpportunityLineItems.Name}}      → Line item names
{{Contacts.Email}}                  → Related contact emails
{{Cases.Subject}}                   → Related case subjects

Uploading PDFs to Salesforce

Generated PDFs can be uploaded directly to Salesforce:

1. Generate your PDF
2. Click Upload to Salesforce
3. Select the record to attach to
4. The PDF is saved as a File attachment

Disconnecting Salesforce

1. Go to Settings → Integrations
2. Find Salesforce
3. Click Disconnect
4. Confirm the disconnection

Note: Templates using Salesforce data will no longer work until reconnected.

Troubleshooting Salesforce

"Missing credentials" Error

• Ensure you've saved your Client ID and Client Secret before clicking Connect
• Verify the credentials are for the correct Salesforce org (Production vs Sandbox)

"Invalid client credentials" Error

• Double-check your Consumer Key and Consumer Secret
• Ensure the Connected App has been activated (wait 2-10 minutes after creation)
• Verify you're using Production credentials for Production orgs, and Sandbox credentials for Sandbox orgs

"Redirect URI mismatch" Error

• The Callback URL in your Connected App must exactly match your application URL
• Check for trailing slashes - https://app.com/callback is different from https://app.com/callback/
• For local development, ensure you're using http://localhost:3000/api/salesforce/callback

"Access denied" or Authorization Failed

• Your Salesforce admin may have restricted OAuth access
• Check if your profile has "API Enabled" permission
• Verify the Connected App is assigned to your profile or permission set

Connection Failed

• Verify Salesforce credentials
• Check if your org allows OAuth
• Contact your Salesforce admin if access is restricted

Missing Objects/Fields

• Check your Salesforce profile permissions
• Verify field-level security settings
• Ensure objects are visible in your profile

Session Expired

• Reconnect your Salesforce account
• Token refresh is automatic, but may occasionally fail

"IP not whitelisted" Error

• Set IP Relaxation to "Relax IP restrictions" in Connected App policies
• Or add your server's IP address to the trusted IP ranges

---

HubSpot Integration

Overview

Connect HubSpot to access contacts, companies, deals, and more for document generation.

Prerequisites

Before connecting HubSpot, you need to create a Private App in your HubSpot account. This requires HubSpot Super Admin privileges.

Creating a HubSpot Private App

Follow these step-by-step instructions to create and configure a Private App:

Step 1: Access Private Apps Settings

1. Log in to your HubSpot account as a Super Admin
2. Click the Settings icon (⚙️) in the main navigation bar
3. In the left sidebar, navigate to Integrations → Private Apps
4. Click Create a private app

Step 2: Configure Basic Information

1. Enter a Name for your app (e.g., PDF Generator)
2. Optionally, add a Description (e.g., "Generates PDF documents from CRM data")
3. Upload a Logo (optional)

Step 3: Configure Scopes

Click the Scopes tab and enable the following permissions:

CRM Scopes (under "CRM"):

Files Scope (under "Files"):

Tip: To find scopes quickly, use the search box at the top of the scopes list.

Step 4: Create the App

1. Review your configuration in the Overview tab
2. Click Create app in the top-right corner
3. A dialog will appear with important information about your access token

Step 5: Copy Your Access Token

1. In the dialog that appears, you'll see your Access Token
2. Click Copy to copy the token to your clipboard
3. Save this token securely - you won't be able to see it again!

⚠️ Important:

• The access token is shown only once. If you lose it, you'll need to create a new one.
• Keep your access token confidential. Never share it publicly or commit it to version control.
• Treat this token like a password.

Step 6: Rotate Token (If Needed)

If you need to generate a new token:

1. Go to Settings → Integrations → Private Apps
2. Click on your Private App name
3. Go to the Auth tab
4. Click Rotate token
5. Copy and save the new token
6. Update your application with the new token

Connecting HubSpot

Once your Private App is created, connect it to the PDF Generator:

Step 1: Navigate to Settings

1. Go to Settings → HubSpot
2. You'll see a form to enter your access token

Step 2: Enter Your Access Token

1. Paste your Private App Access Token in the input field
2. Click Connect or Save
3. The system will validate your token

Step 3: Verify Connection

1. If successful, the status will show "Connected"
2. You can now use HubSpot data in your templates

Required Scopes Summary

Your HubSpot private app needs these scopes at minimum:

• crm.objects.contacts.read
• crm.objects.companies.read
• crm.objects.deals.read
• crm.objects.line_items.read (for deal products)
• files (for file uploads)

Using HubSpot Data

Available Objects

• Contacts: Individual people
• Companies: Organizations
• Deals: Sales opportunities
• Tickets: Support tickets
• Products: Product catalog
• Line Items: Deal line items

HubSpot Properties

Access standard and custom properties:

{{firstname}}
{{lastname}}
{{email}}
{{company}}
{{dealname}}
{{amount}}

Associations

Access related records for tables:

{{contacts.firstname}}     → Associated contacts
{{line_items.name}}        → Deal line items
{{companies.name}}         → Associated companies

Uploading to HubSpot

Generated PDFs can be attached to HubSpot records:

1. Generate your PDF
2. Click Upload to HubSpot
3. Select the record type and record
4. The PDF is saved as an engagement/attachment

Troubleshooting HubSpot

"Invalid Token" or "Unauthorized" Error

• Verify you copied the complete access token (they are long strings)
• Regenerate your private app token if it may have been compromised
• Check that the token hasn't been rotated or the app deleted
• Ensure you're using the access token, not the app ID

"Insufficient Scopes" Error

• Go to your Private App settings and verify all required scopes are enabled
• After adding scopes, you may need to rotate the token
• The most common missing scope is files for PDF uploads

"Private App Not Found"

• Ensure you're logged into the correct HubSpot portal
• Verify the Private App hasn't been deleted
• Check if another admin may have modified the app

Missing Properties/Fields

• Ensure properties exist in your HubSpot portal
• Use internal property names, not display labels (e.g., firstname not "First Name")
• Check that your private app has read access for the relevant object schemas
• Custom properties require crm.schemas.[object].read scope

Cannot Upload Files

• Verify the files scope is enabled on your Private App
• The scope needs both Read and Write permissions
• Check that your HubSpot subscription includes file uploads

Rate Limiting Errors

• HubSpot has API rate limits based on your subscription tier
• Reduce the frequency of requests or implement request queuing
• Consider upgrading your HubSpot subscription for higher limits

Token Expired

• HubSpot Private App tokens do not expire automatically
• If you're seeing expiration errors, the token may have been manually rotated
• Create a new token or check with your HubSpot admin

---

SQL Database Integration

Overview

Connect directly to your SQL database for custom data sources. Perfect for:

• Legacy systems
• Custom applications
• Data warehouses
• Any SQL-compatible database

Supported Databases

Connecting a Database

Step 1: Navigate to Integrations

1. Go to Settings → Integrations
2. Find SQL Database
3. Click Configure

Step 2: Enter Connection Details

Step 3: Test Connection

1. Click Test Connection
2. Verify the connection succeeds
3. If failed, check credentials and network access

Step 4: Save Configuration

1. Click Save
2. The connection is stored securely
3. Password is encrypted

Security Best Practices

1. Use a read-only user: Create a dedicated database user with SELECT-only permissions
2. Limit table access: Grant access only to tables needed for templates
3. Enable SSL: Use encrypted connections when possible
4. Use strong passwords: Generate complex passwords for database users
5. Network security: Consider IP whitelisting if supported

Using SQL Data

Selecting Tables

When creating a template:

1. Choose SQL Database as your data source
2. Select the table to use
3. Available columns are loaded automatically

Field Mapping

Column names become merge fields:

{{customer_name}}
{{email_address}}
{{order_total}}
{{created_at}}

Record Selection

Records are identified by:

• Primary key (usually id)
• Lookup by column value

Limitations

• No joins: Each table is accessed independently
• Simple tables: Limited support for complex relationships
• Performance: Large tables may have slower field loading

Troubleshooting SQL

Connection Failed

• Verify database credentials
• Check if host allows external connections
• Verify firewall rules and network access
• Ensure database is running

Tables Not Showing

• Check user has SELECT permission on tables
• Verify schema access (for PostgreSQL)
• Ensure tables exist in specified database

---

Google Sheets Integration

Overview

Connect Google Sheets for simple, spreadsheet-based data sources. Great for:

• Quick data setup
• Non-technical users
• Small datasets
• Marketing campaigns

Connecting Google Sheets

Option 1: OAuth Connection

1. Go to Settings → Integrations
2. Find Google Sheets
3. Click Connect with Google
4. Log in to your Google account
5. Authorize access to Google Sheets

Option 2: API Key

1. Go to Settings → Integrations
2. Find Google Sheets
3. Enter your Google API key
4. Click Save

Using Google Sheets

Setting Up Your Spreadsheet

1. Create or open a Google Sheet
2. Use the first row for column headers
3. Each subsequent row is a record
4. Column headers become field names

Example Spreadsheet:

Connecting a Spreadsheet

1. Copy the spreadsheet URL or ID
2. In template creation, paste the spreadsheet ID
3. Select the sheet (tab) to use
4. Fields are loaded from column headers

Field Names

Column headers become merge fields:

{{Name}}
{{Email}}
{{Company}}
{{Amount}}

Tip: Keep column headers simple—no spaces, special characters, or very long names.

Selecting Records

Records can be selected by:

• Row number: Specify which row (2 = first data row)
• Lookup value: Find row by column value (e.g., Email = "[email protected]")

Best Practices for Google Sheets

1. Consistent formatting: Keep data types consistent within columns
2. No empty rows: Remove blank rows in your data
3. Clear headers: Use descriptive, simple column names
4. Share appropriately: Ensure the sheet is accessible to your connected account
5. Lock headers: Prevent accidental header changes

Limitations

• Simple structure: One sheet = one table
• No relationships: Cannot link between sheets
• Performance: Large sheets may be slower
• Real-time sync: Data is fetched at generation time

Troubleshooting Google Sheets

Sheet Not Found

• Verify the spreadsheet ID is correct
• Check the sheet is shared with your Google account
• Ensure the sheet hasn't been deleted

Fields Not Loading

• Verify header row is present
• Check for merged cells in headers
• Ensure headers are in row 1

---

Managing Integrations

Checking Connection Status

1. Go to Settings → Integrations
2. Each integration shows its status:
   • ✅ Connected
   • ❌ Not connected
   • ⚠️ Error (reconnection needed)

Refreshing Connections

For OAuth integrations (Salesforce, HubSpot, Google):

• Tokens refresh automatically
• If issues occur, disconnect and reconnect

Multiple Integrations

You can connect multiple data sources:

• Each template uses one data source
• Different templates can use different sources
• Team members share connection access

Integration Security

---

Comparing Data Sources

---

Next Steps

• Merge Fields - Use data in templates
• Tables - Display related records
• Templates - Create documents
• API Reference - Programmatic access