Field Data Types

“Data Types” are the type of data that you send in your API request.

Data types can be different to the Display Types that you use to render data on the PDF. For example, a boolean true or false value can be used to show or hide a check mark on the PDF. Or if you set the display type to “Text”, the field could display the text “true” or “false” (or any other values you configure.)

String

Field Options

If you add some Field Options, then the value must be one of those options. A select list will be displayed on online forms.

Conditions

When a String field is displayed as a Check or Shape, you can define a Condition. The field is only displayed when its value matches the condition. (Static check marks and shapes are always displayed.) The condition can be:

• Equals, Contains, Starts with or Ends with the condition’s text, or the opposite: Doesn’t equal, Doesn’t contain, Doesn’t start with or Doesn’t end with.
• Matches regex or Doesn’t match regex: the condition is a regular expression (see below).
• Is blank or Isn’t blank: whether the value is empty or has only spaces, tabs and line breaks. These conditions have no text.

On a visual form, clicking a check mark or shape with an Equals, Contains, Starts with or Ends with condition selects it, and sets the value to the condition’s text. The others only show whether the value matches. Embedded visual forms need version 2.20.0 for the Doesn’t, Is blank and Isn’t blank conditions, and to match regex conditions as the PDF does.

A Matches regex condition is an RE2 regular expression. The value matches when the expression matches any part of it: use ^ and $ to match the whole value, and start with (?i) to ignore case, as in (?i)^(yes|y)$. In a value with several lines, ^ and $ match at the start and end of each line, and \A and \z only at the start and end of the value. \w, \d, \s, \b and classes like [[:alpha:]] only know ASCII characters: list accented letters in a class, as in [a-zA-ZÀ-ÿ].

RE2 matches any expression in a time proportional to the length of the value, so no condition can slow down a PDF or a form. Visual forms and signature requests match with RE2’s JavaScript version, and show the same check marks and shapes as the PDF. So that the two always agree, a regex condition can’t use:

• Lookaheads or lookbehinds ((?=...), (?!...), (?<=...), (?<!...)), backreferences (\1), atomic groups, conditionals or recursion, which RE2 doesn’t have. For “not”, use a condition like Doesn’t contain or Doesn’t match regex.
• Unicode classes like \pL or \p{Greek}: list the characters in a class instead.
• \B, \C or \Z (RE2 doesn’t have \Z: use \z for the end of the value).
• With (?i), the few letters that the two versions of RE2 case differently (such as ɤ).
• More than 1,000 repeats of a part (a{1001}), including repeats inside repeats, or groups nested more than 100 deep. The whole expression can have up to 10,000 characters, counting a repeated part once for each repeat.
• Group names with characters other than the letters a to z and A to Z, digits and _, or two groups with the same name.

The template editor shows what’s wrong under the condition as you type, and a template can’t be saved with a regex condition that breaks these rules. The API’s error says what to change.

Display Types

TextCheckShapeQR CodeBarcode

Number

A Number field can be an integer or a float. When Integer is checked, the value must be an integer. (No decimal places.)

When Currency is checked, online forms show a currency input. When a Number field is displayed as Text, Decimal Places sets the number of fixed decimal places used to format the number. (Set it to 0 to round to the nearest integer.)

Validations

You can define a Minimum and Maximum value. You can check the “Exclusive” checkboxes to exclude the given value from the range. For example:

• When “Exclusive Minimum” is checked: value > Minimum
• When “Exclusive Minimum” is not checked: value >= Minimum

In the following example, the value must be an integer. The value must be greater than 0, and less than or equal to 1000.

Formulas

A Number field can be a formula that performs a calculation. Formulas can reference other Number fields. View the Formula documentation for more information about formula syntax, operators, and functions.

Conditions

When a Number field is displayed as a Check or Shape, you can define a Condition. The field will only be displayed when the value matches the condition. The condition predicate can be one of: Equals, Greater or Equal, Greater, Less or Equal, Less, or In Range.

Display Types

TextCheckShape

Boolean

A Boolean value must be either true or false.

Text

When a Boolean field is displayed as Text, the text will be either “Yes” or “No”. These strings can be configured for each field. You can also set default values in the template settings.

Check or Shape

When a Boolean field is displayed as a Check or Shape, the field will only be displayed when the value is true. When Invert Boolean Condition is checked, the field will only be displayed when the value is false or missing. (Static check marks and shapes are always displayed.)

Display Types

TextCheckShape

Date

Date values must be a string formatted as: YYYY-MM-DD.

When Include Time is checked, the value must be a timestamp formatted as: YYYY-MM-DDThh:mm:ss.fffZ.

Dates sent as numbers like 05/07/2024 are read day first (July 5), unless the template’s Parse Dates setting is checked. Then they’re read in the order of the template’s default date format, so 05/07/2024 is May 7 for %m/%d/%Y.

A Date field can be formatted using a format string. DocSpring supports the strftime format directives from the Ruby programming language. Japanese calendar (wareki) directives are also supported, e.g. %Jf (令和5年4月1日) and %JF (令和五年四月一日).

The Difference formats (Difference: Years, Difference: Months, Difference: Weeks, Difference: Days, and Hours, Minutes, or Seconds when Include Time is checked) show the number of whole units between the date and the time when the PDF is generated. Years and months are counted using their average lengths (365.2425 days and 30.436875 days), so a result can be one unit off close to an anniversary.

Example

Some forms may have separate fields for month, day, and year. You could configure three fields that all share the name date, but use different format strings for each field:

• %-m for month
• %-d for day
• %Y for year

Display Types

Text

Address

The Address type can be used to show a text input that autocompletes an address. Address autocompletion is powered by Google Maps.

The address is formatted as a single string. If you need to render the address parts separately, create separate text fields for each part (e.g. street, city, state, zip, country.)

Display Types

Text

Country

The Country type can be used to show a dropdown list of countries in the online form. Otherwise, it is just a String field that can accept any value.

Display Types

TextCheckShape

Email

An Email value must be a valid email address.

Display Types

TextQR CodeBarcode

URL

A URL value must be a valid URL.

Display Types

TextQR CodeBarcode

Image

An Image value can be a Base64 encoded image, or a URL where the image can be downloaded. Images downloaded from a URL can be up to 100 MB.

• Request with a Base64 encoded image:

"photo": {
  "base64": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAgGB ..."
}

• Request with an image URL:

"photo": {
  "url": "https://example.com/images/photo.jpg"
}

See the Image Display Type section for information about resizing and cropping images.

Display Types

Image

Signature

A Signature field allows you to collect legally binding e-signatures with a signature request.

You can also ask the user to type their full name and select a typeface from one of the following options:

• Dancing Script
• Satisfy
• Cookie
• Great Vibes
• Caveat
• Sunshiney
• Sedgwick Ave
• Sacramento
• Lovtony Script

Note

Let us know if you want us to add a new font.

Display Types

Image

(used internally)

Initials

An Initials field adds an initials pad to the online form, similar to the signature field:

The initials field input aspect ratio is 3:2 (width:height), which is closer to a square than the signature input.

Display Types

Image

(used internally)

Barcode

A Barcode data type ensures that you submit a valid barcode. The value can be rendered as a barcode image or as a string.

You must configure the correct barcode symbology (type). DocSpring supports the following symbologies:

• EAN-13
  • 12 digits (the check digit is added), or 13 ending with the check digit (it must be correct)
  • Pattern: /^[0-9]{12,13}$/
• EAN-8
  • 7 digits (the check digit is added), or 8 ending with the check digit (it must be correct)
  • Pattern: /^[0-9]{7,8}$/
• UPC-A
  • 11 digits (the check digit is added), or 12 ending with the check digit (it must be correct)
  • Pattern: /^[0-9]{11,12}$/
• PDF417
  • Any ASCII character
  • (No validation)
• Code 128
  • Any ASCII character
  • (No validation)
• Code 93
  • Uppercase letters, digits, - . $ / + % SPACE
  • Pattern: /^[A-Z0-9\-\.\$\/\+% ]+$/
• Code 39
  • Uppercase letters, digits, - . $ / + % SPACE
  • Pattern: /^[A-Z0-9\-\.\$\/\+% ]+$/
• Code 25
  • Digits
  • Pattern: /^[0-9]+$/

Note

Please contact [email protected] if you need a different symbology.

Display Types

TextBarcode

Combined

Combined fields allow you to combine multiple field values into a single string.

For example, you could combine first_name and last_name fields into a single full_name field:

Choose Use Separator or Use Format String:

• Separator: Joins the values with any string (including an empty string.)
• Format String: A string containing numbered variables that start at $0, in the order of the Combined Field Names. Example: Full Name: $0, Address: $1

Each value is printed as its own field prints it: a date in the field’s date format, a number with its decimal places, and a check box as its true or false text. A value is printed as written, even when it contains something like $1.

Display Types

Text