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 will only be displayed when the value matches the condition. The condition predicate can be one of: Equals, Contains, Starts With, Ends With, or Regex.

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.)

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.

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.

A Date field can be formatted using a format string. DocSpring supports the strftime format directives from the Ruby programming language.

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 currently formatted as a single string. We are working to improve this so that you can render the address parts as separate fields.

If you need this ability now, you should 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.

(Support for direct image uploads is coming soon.)

• Request with a Base64 encoded image:

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

• Request with an image URL:

"photo": {
  "url": "https://source.unsplash.com/random"
}

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

Display Types

Image

Signature

A Signature field adds a signature pad to the online form:

The online form will submit the signature as a Base64 encoded image.

When you are generating a PDF via an API request, the Signature type is a subset of the Image type: You can submit a Base64 encoded image (base64), or a URL where the image can be downloaded (url).

Note

When requesting signatures from your users, we recommend using the signature_pad library. You can generate a PNG image with signaturePad.toDataURL()

You can also ask the user to type their full name. Then submit a text object with the user’s name and their choice of typeface:

"signature": {
  "text": {
    "name": "John Smith",
    "typeface": "Dancing Script"
  },
}

• name must be the user’s full name.
• typeface must be one of the following fonts:
  • 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)

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 (a checksum digit is added)
  • Pattern: /^[0-9]{12}$/
• EAN-8
  • 7 digits (a checksum digit is added)
  • Pattern: /^[0-9]{7}$/
• UPC-A
  • 11 digits (DocSpring adds the leading zero)
  • Pattern: /^[0-9]{11}$/
• 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:

The Separator value can be any string (including an empty string.)

Display Types

Text