Choosing between Variables and Fields

When building a PandaDoc API workflow, understanding the distinction between Fields and Variables is crucial. This guide will explain the difference and help you decide which one to use for your specific needs.

What are Variables?

Variables are used to push data into a document. They are placeholders in your templates that you can populate with information from your CRM or any other data source.

Key characteristics of Variables:

One-way data flow: You can only send data into a PandaDoc document. You cannot use a variable to collect information from a recipient.

Available in Templates only: Variables are primarily a feature of PandaDoc Templates.

Ideal for personalization: Use variables to auto-fill information like client names, addresses, and company details.

What are Fields?

Fields, on the other hand, allow for a two-way data flow. You can use them to pre-fill information and to collect data from your document recipients.

Key characteristics of Fields:

Two-way data flow: You can both pre-define the value of a field and allow recipients to edit or fill it in.

Available in Templates and Documents, including those created from PDFs.

Interactive data collection: Fields are what your recipients will interact with to provide information like signatures, dates, or text input.

Data retrieval: The information entered into fields by recipients can be retrieved via the API and stored in your database.

When to Use Which: Practical Examples

Use Variables when:

• You want to personalize a sales quote with the customer's name, company, and address from your CRM.
• You need to insert a product's SKU or a service's start date that is already known and should not be changed by the recipient.

Use Fields when:

• You are sending a contract that requires the recipient's signature and the date of signing.
• You are sending a form where the recipient needs to provide their billing information.
• You want to pre-fill a field with a suggested value (e.g., a "quantity" of 1) but allow the recipient to change it.