Verdocs - Developer Documentation

Fill templates from your data

Map template fields to your own data structures to make pre-filling data fast and painless.

Use your own data structures to make pre-filling data, such as a customer's name, a policy number, or a start date, fast and painless. Throughout this document, we will use the following data structure as an example record, but any flat or nested data structure may be used.

{
  "policy_id": "1234567890",
  "applicant": {
    "full_name": "Jordan Rivera",
    "date_of_birth": "1988-04-12",
    "email": "jordan.rivera@example.com",
    "phone": "(555) 010-0199",
    "mailing_address": {
      "line1": "100 Example Ave",
      "city": "Springfield",
      "state": "OH",
      "postal_code": "45402"
    }
  },
  "co_applicant": {
    "full_name": "Casey Rivera"
  },
  "property": {
    "address": {
      "line1": "48 Harbor Rd",
      "city": "Springfield",
      "state": "OH",
      "postal_code": "45404"
    },
    "year_built": 1994
  },
  "policy": {
    "number": "HO-2026-001234",
    "effective_date": "2026-11-01",
    "annual_premium": 1840.00,
    "coverage": {
      "level": "standard",
      "dwelling_limit": 350000,
      "flood": true
    }
  },
  "additional_insureds": [{
    "full_name": "Riley Rivera",
    "relationship": "Child"
  }]
}

Assign data keys

A "data key" is your system's identifier for a value. Data keys may also refer to nested values, using a . period as a separator. In the example above, policy_id is the simplest type of key, while applicant.full_name and property.address.state refer to nested values.

To assign keys, set data_key on a field, either via our Template Builder's field inspector panel ("Fill with"), or when calling create or update at the API level, or createEnvelope directly without a template. When using tags, set the k option, e.g. {{textbox:Applicant;k:applicant.full_name}} (see Tagging dynamic documents).

Send your data

When calling createEnvelope, pass your data via the prefill_data parameter as shown below:

import {createEnvelope} from '@verdocs/js-sdk';

const envelope = await createEnvelope(endpoint, {
  template_id: templateId,
  recipients: [{role_name: 'Applicant', first_name: 'Jordan', last_name: 'Rivera', email: 'jordan@example.com'}],
  prefill_data: {
    applicant: {full_name: 'Jordan Rivera', state: 'TX'},
    policy: {effective_date: '2026-11-01', premium: 1234.5, coverage: {flood: true}},
    // ... More data
  },
});

Note that nested objects and dotted keys work the same way, so you can also pass the data in a flat structure such as:

const prefill_data = {'applicant.full_name': 'Jordan Rivera', 'applicant.state': 'TX', 'policy.effective_date': '2026-11-01'};

Data will be mapped to each field type as follows:

FieldSend
TextText, a number, or true/false. A number in a plain text field will be shown in a locale-friendly format, e.g. 1,234.50. A number field stores the number itself, and also accepts locale-formatted text as an input, e.g. 12.450,50 for de-DE.
DateAn ISO 8601 date, like 2026-11-01
CheckboxAccepts true or false, "yes" or "no", or 1 or 0.
DropdownThe option's id or its label
RadioThe label or name of the option to select

When you also send a fields entry for a field, that entry supersedes other settings such as from a template. This allows you to override a field placement or configuration on a one-off basis.

Developer feedback

Data mapping is a complex operation and it's easy to make mistakes when hand-typing data keys, or if data structures change over time. To help troubleshoot issues, when prefilling data Verdocs will include a prefill_result block in the response. For privacy and security reasons, data values will never be included in the response (so it should also be safe to log for most organizations). An example response is below:

{
  "placements_filled": 6,
  "unused_keys": ["applicant.ful_name"],
  "hints": [{"key": "applicant.ful_name", "did_you_mean": "applicant.full_name"}],
  "missing_keys": ["policy.coverage.flood"],
  "errors": [{"key": "applicant.state", "field": "state", "message": "No dropdown option matches this value"}],
  "format_problems": [{"key": "applicant.email", "field": "email", "message": "Not a valid email"}]
}

unused_keys are keys you sent that were not mapped to anything. In the example above, there was obviously a typo in applicant.ful_name so it would not have been mapped to any fields looking for applicant.full_name. Unused keys are not always errors - you may simply not be using one of them. But if a form is not mapping data the way you expect, this is the best first thing to check. Where possible, we will provide a hints block in the result with our best guess of what was meant.

If a field is mapped to a key your data object doesn't provide, we will list those in missing_keys. These are nearly always errors and are the second thing we recommend examining when troubleshooting.

Other errors will be listed in errors if both the field and key were found and matched, but the requested value could not be prefilled for another reason, such as calling for a dropdown entry that the dropdown does not provide, while format_problems will list cases where everything was mapped, but the value supplied doesn't match the field's validation or formatting (see Formatting text fields). If the field is not read-only, the recipient will be able to correct the issue themselves but this creates a poor user experience. If the field is read-only, they may be blocked from proceeding at all. Either way, these issues are worth fixing at the source.

Strict mode

The prefill_result block provides feedback, but doesn't necessarily block an envelope from being sent - Verdocs will make a best-efforts attempt to proceed with the data provided. In some cases you may prefer that we stop and report an error. To achieve this, set prefill_options: {strict: true} and we will refuse these requests rather than allowing them to proceed. To enable strict mode but ignore unused keys (a common need if you don't control the source data structure), set prefill_options: {strict: true, ignore_unused: true}.

We also provide a dry-run setting. If you set dry_run: true on the request (usually alongside prefill_options: {strict: true}), we will run the complete validation pass on the provided data but without creating an envelope (js-sdk users, see previewEnvelope). This can be a convenient way to verify that data mapping is complete and valid if your own system provides the UI for users to perform this task.

Bulk sends

POST /v2/envelopes/bulk takes prefill_data on each entry, so every envelope in the batch gets its own data, while prefill_options applies to the entire batch. The call response will include prefill_results as an array, with one record per entry in the bulk-send request, in the same order. For entries with no prefill_data, the prefill_results array element will be null. In strict mode, all rows must be valid or the entire batch will be rejected, avoiding any risk of a partially sent batch.

{
  "template_id": "d2338742-f3a1-465b-8592-806587413cc1",
  "prefill_options": {"strict": true},
  "entries": [
    {"recipients": [{"role_name": "Applicant", "first_name": "Jordan", "last_name": "Rivera", "email": "jordan@example.com"}], "prefill_data": {"applicant": {"full_name": "Jordan Rivera"}}},
    {"recipients": [{"role_name": "Applicant", "first_name": "Sam", "last_name": "Lee", "email": "sam@example.com"}], "prefill_data": {"applicant": {"full_name": "Sam Lee"}}}
  ]
}

Template requirements

The getTemplateDataContract method lists every data key a template uses, including its type and options, how many fields use it, and whether it's needed (a read-only field the signer can't fill in). It also returns a JSON Schema for the template's prefill_data, which may be used to validate your payloads before sending. It also provides a contract_hash value. This is a hash of the data key mapping requirements, and may be used in a CI check to determine whether a change has been made that might invalidate future sends.

import {getTemplateDataContract} from '@verdocs/js-sdk';

const {keys, json_schema, contract_hash} = await getTemplateDataContract(endpoint, templateId);

On this page