Field Mapping

What this does

Field mapping is how you send your data to a Quik! form so the form arrives prefilled for the user. You provide a list of field name and value pairs in your generation request, and Quik! places the values on the right fields automatically.

The same approach prefills any form in the Quik! library. Build the mapping once between your data source (CRM, account system, internal database) and the Quik! Field Definition, and you can prefill any form your account is subscribed to.

When to use this

Every time you generate a form for a user who already has data in your system. Common scenarios:

• Pre-populating account opening forms with client data from your CRM.
• Filling in transfer forms with existing account numbers.
• Auto-completing fields a back-office team would otherwise type by hand.
• Including hidden data (transaction IDs, internal references) that should travel with the form but stay invisible to the user.

If a user is filling a form from scratch with no prior data, you can skip field mapping. Quik! will generate a blank form.

Before you start

You should have:

• An understanding of the Quik! Field Definition naming convention. See Concepts > Data Model > Fields and Field Names.
• The role prefixes used on the form. See Concepts > Data Model > Roles and Role Prefixes.
• A list of the Form IDs you'll be generating. The fields available on a form depend on the form.

How to do it

The FormFields array

In REST, all field mapping happens through the FormFields array in your execute/html or execute/pdf request body. Each entry is an object with at minimum a field name and a value.

Minimum example:

{
  "QuikFormID": "12",
  "FormFields": [
    { "FieldName": "1own.FName", "FieldValue": "John" },
    { "FieldName": "1own.LName", "FieldValue": "Doe" }
  ]
}

The same field name on multiple forms in a package will prefill on all of them. If a form does not have a field you sent, Quik! ignores it without raising an error.

Field attributes you can set

Beyond a name and a value, you can control how a field behaves at runtime by adding attributes to the FormFields entry.

For runtime rule logic that goes beyond what attributes can express (conditional visibility, complex required logic), see Field Rules.

Sample requests

Simple prefill, two owners on one form:

{
  "QuikFormID": "12",
  "FormFields": [
    { "FieldName": "1own.FName", "FieldValue": "John" },
    { "FieldName": "1own.LName", "FieldValue": "Doe" },
    { "FieldName": "2own.FName", "FieldValue": "Jane" },
    { "FieldName": "2own.LName", "FieldValue": "Doe" }
  ]
}

Prefill with a read-only field and a formatted phone number:

{
  "QuikFormID": "12",
  "FormFields": [
    { "FieldName": "1own.FName", "FieldValue": "John" },
    {
      "FieldName": "1own.AcctNum",
      "FieldValue": "12345678",
      "FieldReadOnly": 1
    },
    {
      "FieldName": "1own.H.Phone",
      "FieldValue": "3105551222",
      "FieldFormat": "(###) ###-####"
    }
  ]
}

Hidden field to carry an internal transaction ID:

{
  "QuikFormID": "12",
  "FormFields": [
    { "FieldName": "1own.FName", "FieldValue": "John" },
    {
      "FieldName": "TransactionID",
      "FieldValue": "TXN-2026-00481",
      "HiddenField": true
    }
  ]
}

The hidden field is added to the form and travels with submitted data, but the user never sees it.

Conditional required field (require spouse's name only if marital status is "Married"):

{
  "QuikFormID": "12",
  "FormFields": [
    {
      "FieldName": "1spou.FName",
      "RequiredByField": "1own.MaritalStatus",
      "RequiredByFieldValues": "Married"
    }
  ]
}

The shotgun approach

Quik!'s recommended pattern: send every field you have data for, even if you are not sure which fields appear on the form. Quik! ignores anything that does not match a field on the generated package, so you cannot over-send.

The benefit is that you write the prefill logic once for your CRM and reuse it across every Quik! form. You do not need a form-specific mapping table for each Form ID.

The exception: do not send to Generic field names (see Pitfalls).

Alternative: LoadXML for XML data pipelines

If your data source already produces XML, you can use the LoadXML property to send a structured XML payload instead of a FormFields array. This is most common for SDK integrations and for customers with existing XML pipelines.

The XML schema is documented in the LoadXML reference. All the attributes available in FormFields are also available in the XML format. For REST customers without an existing XML dependency, FormFields is simpler and we recommend starting there.

Pitfalls

• Do not map to Generic field names. Field names like NFSVC2349.txt1.01 are auto-generated and can change in future form versions. If a form has Generic fields you need to map, add a copy of the form to your private library so the field names are under your control. See Concepts > Data Model > Fields and Field Names.
• Strip the QuikRadio<FormID> prefix from checkbox and radio field names. When you inspect a checkbox in the browser, the field name looks like QuikRadio38002.1acc.RegType. The value you send to the API should be 1acc.RegType. Sending the version with the prefix will silently fail to prefill.
• Checkbox and radio fields need a value, not just a name. Each checkbox option has an export value (often a short code like "57"). Prefilling a checkbox means setting its field to the matching export value, not to true or to the visible label.
• Prefill data for fields that do not exist on the form is ignored, not flagged. This is by design for the shotgun approach, but it also means typos in field names fail silently. Use /forms/fields to confirm field names exist before prefilling, or use TestDataMode: true to visually inspect the form with field names labeled.
• FieldFormat affects display, not validation. A phone field formatted as (###) ###-#### will display formatted, but the underlying value is what gets submitted. Submit data quality is still your responsibility.
• MaxCharLength does not block prefilled values. It limits what users can type, not what you can send. If your prefilled value is longer than MaxCharLength, the value still goes onto the form.

Related articles

Continue with these articles to understand the related concepts and workflows:

• Fields and Field Names — Learn the naming structure Quik! uses to identify every field.

• Roles and Role Prefixes — Understand how field names identify the person or entity each value belongs to.

• Field Rules — See how form logic can affect which fields are shown, required, or filled.

• Launch a Form — Learn where mapped data is sent when generating a form.