The Welcome section is an optional first step you can add to the beginning of a KYC boarding form. It's the only content in a boarding form that you fully author yourself — everything after it (business identity, ownership, banking, and so on) is fixed by your connection's requirements.

Use the Welcome section to:

• Show your own introduction or welcome copy before the merchant starts
• Present a platform agreement the merchant must accept to continue
• Capture who is completing the application (name, email, phone, title)

Each of these three pieces is independently toggleable, so you can use all of them, just one, or none at all.

How the Welcome Step Works

When enabled, the Welcome step renders as the first step in the form, ahead of business identity. It's configured per form template in the dashboard, with the same per-form API override available on every other boarding form section — see API Override below.

flowchart TD
    A[Welcome step] --> B[Render enabled cards in order:<br/>Introduction, Agreement, Person Completing]
    B --> C{Agreement shown?}
    C -- Yes --> D[Agree and Continue]
    C -- No --> E[Continue]
    D --> F{Person Completing<br/>fields submitted?}
    E --> F
    F -- Yes --> G[Server stamps<br/>agreedOn and ipAddress]
    F -- No --> H[Next step:<br/>Business Identity]
    G --> H

The Welcome step renders when introduction.display or agreement.display or any personCompleting.fields.*.display is true. If none are on, no step renders and the button logic above never applies.

The step re-hydrates on every load, including reloads after the merchant has already completed it — values remain editable until the full form is submitted.

Configuring the Welcome Section

Configure the Welcome section from a form template's Field Customization tab, the same place you configure every other section (business info, owners, banking). See Boarding Form Templates for the full template editor.

Introduction and Agreement appear as their own toggle rows. Each Person Completing field — first name, last name, email, phone, title — is its own independent toggle row. Selecting Edit on a row opens a drawer where you author that piece's detail:

• The Introduction and Agreement drawers include a title field and a full-height markdown editor for the card's body copy.
• The Person Completing drawer includes the section title and an optional description shown above the contact fields.

Changes commit when you select Apply in the drawer, or discard with Cancel.

Introduction and Agreement

The Introduction card (if shown) renders above the Agreement card. Both are optional and independent — you can show an agreement with no introduction, an introduction with no agreement, or both.

Each card's body comes from its markdown property. Whatever you supply is rendered on the boarding form as formatted content — the merchant sees the formatted result, not the raw text.

There's no independent "required" flag on Person Completing fields — a displayed field is required to advance, the same convention used by business info, owners, and banking fields elsewhere in the form.

Person Completing This Application

When any Person Completing field is enabled, the section title (defaults to "Person Completing This Application") and your optional description render above the enabled fields. The phone field uses a US/CA phone input and stores the value as E.164 with a leading + (for example, +14155552671).

Because the title and description are yours to set, you can frame this section for either of two purposes — or both at once:

• A point of contact — the person to reach with questions or operations assistance about the in-flight application. A description like "We'll reach out to this person with any questions about your application" sets that expectation.
• The person agreeing to the terms — when an Agreement card is shown, this is the individual accepting it on the business's behalf, and their submission is what records the acceptance evidence (agreedOn, ipAddress). A description like "This person is agreeing to the terms above on behalf of the business" makes that role explicit.

With an agreement displayed, these aren't mutually exclusive: the same person is both the party accepting the terms and your point of contact for the application.

Config Reference

All Welcome section configuration lives under customFormFields.welcome on the form template.

Authoring the Markdown

Each markdown value holds Markdown source — write it the way you'd write any Markdown. For example, this Introduction:

Thanks for choosing Acme Payments — this application takes about **10 minutes**. Before you begin, have these ready:

- Your legal business name and EIN
- A bank account for deposits
- Ownership details for anyone who owns 25% or more

renders on the form as a paragraph and a bulleted list, below the card's title.

When you send that content through the API, it's a JSON string value — and JSON strings can't contain literal line breaks, so each newline is encoded as \n. The template config below shows the same Introduction (and an Agreement with a link and a numbered list) in that encoded form:

{
  "customFormFields": {
    "welcome": {
      "sectionTitle": "Before You Begin",
      "introduction": {
        "display": true,
        "title": "Welcome to Acme Payments",
        "markdown": "Thanks for choosing Acme Payments — this application takes about **10 minutes**. Before you begin, have these ready:\n\n- Your legal business name and EIN\n- A bank account for deposits\n- Ownership details for anyone who owns 25% or more"
      },
      "agreement": {
        "display": true,
        "title": "Acme Platform Agreement",
        "markdown": "By continuing, you agree to the [Acme Platform Agreement](https://acme.example.com/legal) and authorize Acme to:\n\n1. Share your application data with our payment processing partners\n2. Verify the information you provide\n\n**You must accept these terms to continue.**"
      },
      "personCompleting": {
        "title": "Person Completing This Application",
        "description": "We'll use this to follow up if we have questions about your application.",
        "fields": {
          "firstName": { "display": true },
          "lastName": { "display": true },
          "email": { "display": true },
          "phone": { "display": true },
          "title": { "display": false }
        }
      }
    }
  }
}

Submitted Data and Acceptance Evidence

When the merchant submits the Welcome step, the values are saved as a top-level personCompleting object on the form — a sibling of customFormFields, not nested inside it. Configuration (which fields are shown) and submitted data (what the merchant entered) are separate concerns.

{
  "personCompleting": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "+14155552671",
    "title": "Owner",
    "agreedOn": "2026-06-30T14:22:08.000Z",
    "ipAddress": "203.0.113.42"
  }
}

sequenceDiagram
    participant Platform
    participant Template as Form Template
    participant API as Create Form API
    participant Merchant
    participant Preczn

    Platform->>Template: Configure customFormFields welcome
    Platform->>API: Optionally override welcome config per form
    Merchant->>Preczn: Opens form URL and completes Welcome step
    Preczn->>Preczn: Stamp agreedOn and ipAddress when contact fields shown
    Preczn-->>Platform: Form personCompleting saved

API Override

Like every other customFormFields section, the Welcome config can be overridden per form at creation time via the customFormFields object on the create-form call:

POST /v1/forms

{
  "merchantId": "mid_1sxmscs49g95t8y6n79nt922xr",
  "connectionId": "Payrix",
  "formTemplateId": "formTemp_test_7ffxgaw71x82zsg0psxd7q73nh",
  "customFormFields": {
    "welcome": {
      "personCompleting": {
        "fields": {
          "email": { "display": true }
        }
      }
    }
  }
}

You can also pre-populate the person-completing values themselves at form creation, as a top-level personCompleting object (each field individually optional, format-validated):

{
  "merchantId": "mid_1sxmscs49g95t8y6n79nt922xr",
  "connectionId": "Payrix",
  "formTemplateId": "formTemp_test_7ffxgaw71x82zsg0psxd7q73nh",
  "personCompleting": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]"
  }
}

FAQ