Add additional data to boarding applications

The additionalData object is a flexible extension point in Payabli’s boarding APIs that allows you to pass custom key-value pairs associated with the application, business, owners, or signers. This flexibility is useful for enriching the application context or aligning with your existing systems.

Common use cases

Here are some common scenarios where additionalData is useful:

• Add business-level additionalData to indicate how long you’ve worked with the merchant. Payabli uses this data to inform custom underwriting policies.
• Include a unique user ID in the owner’s additionalData to streamline post-boarding user provisioning in their portal.
• Supply historical risk scores and account balance information in additionalData to inform your own underwriting decisions while leveraging Payabli for orchestration.

Best practices

Keep these best practices in mind when using additionalData with boarding operations:

• Avoid transmitting unstructured or nested data. Stick to flat key-value pairs.
• Keep keys predictable and consistent across environments and integrations.
• Don’t use additionalData as a substitute for core schema fields like legal name or Social Security Number.
• If a field is critical for compliance or reconciliation, consider formalizing it in your integration rather than relying on additionalData.

Where additionalData is available

You can add the additionalData object to three main objects in the boarding template to be captured on boarding applications:

• Root business level: Fields that apply to the business entity
• Owners: Fields associated with each beneficial owner
• Signers: Fields associated with individuals signing on behalf of the business

This allows precise scoping of data depending on the entity to which it pertains.

Adding additionalData to templates

Boarding templates are essential for defining how services, pricing, and dynamic fields (including additionalData) are presented during boarding. To make sure that your additionalData fields are rendered in boarding applications, you must first declare them in your boarding templates.

1
  "additionalData": {
2
    "visible": true,
3
    "fields": {
4
      "HQ-Location": {
5
          "label": "Where is your headquarters located?",
6
          "type": "text",
7
          "options": null,
8
          "posRow": 0,
9
          "posCol": 0,
10
          "value": "",
11
          "visible": true,
12
          "readOnly": false,
13
          "required": true
14
      },
15
      "ERP Usage": {
16
          "label": "Do you use an accounting system (e.g., QuickBooks, Xero)?",
17
          "type": "boolean",
18
          "options": null,
19
          "posRow": 0,
20
          "posCol": 0,
21
          "value": "",
22
          "visible": true,
23
          "readOnly": false,
24
          "required": true
25
      },
26
      "adBudget": {
27
          "label": "How much do you spend each month advertising your services?",
28
          "type": "number",
29
          "options": null,
30
          "posRow": 0,
31
          "posCol": 0,
32
          "value": "",
33
          "visible": true,
34
          "readOnly": false,
35
          "required": false
36
      },
37
      "referralSource": {
38
          "label": "How did you hear about us?",
39
          "type": "dropdown",
40
          "options": [
41
              {"label": "Search engine", "value": "search"},
42
              {"label": "Referral", "value": "referral"},
43
              {"label": "Social media", "value": "social"}
44
          ],
45
          "value": "",
46
          "visible": true,
47
          "readOnly": false,
48
          "required": true
49
      },
50
      "session_id": { // Prefilled field for tracking session. Notice that it includes a value and is not visible to the user.
51
          "label": "Session ID", 
52
          "type": "text",
53
          "options": null,
54
          "posRow": 0,
55
          "posCol": 0,
56
          "value": "sesh-21dh2-jf4493-f34h4f8-2323",
57
          "visible": false,
58
          "readOnly": false,
59
          "required": false
60
      },
61
      "partnerScore": { // Prefilled field for custom risk score. Notice that it includes a value and is not visible to the user.
62
          "label": "Partner Risk Score",
63
          "type": "dropdown",
64
          "options": [
65
              {"label": "Low Risk", "value": "low-risk"},
66
              {"label": "Medium Risk", "value": "medium-risk"}, 
67
              {"label": "High Risk", "value": "high-risk"}
68
          ],
69
          "posRow": 0,
70
          "posCol": 0,
71
          "value": "low-risk",
72
          "visible": false,
73
          "readOnly": false,
74
          "required": false
75
      }
76
  }

The next section describes the configuration options available for each additionalData field in your boarding templates.

Field configuration options

Each additionalData object on a boarding template has these parameters:

Field types

These settings let you customize boarding flows based on operational or compliance requirements while creating a user-friendly experience.

Passing additionalData on applications

When using the POST /Boarding/app endpoint, you can pre-populate additionalData to streamline the user experience and enrich the application context.

Here is an example of how to pass additionalData at the business level:

1
"additionalData": {
2
  "referralSource": "search", // Custom field for tracking referral source
3
  "session_id": "sesh-21dh2-jf4493-f34h4f8-2323",   // Correlates session data
4
  "partnerScore": "low-risk"                       // Custom risk signal
5
}

This data is visible in the Payabli dashboard under the “Additional Data” section of the application or paypoint’s record, and you can also retrieve it via the API by calling any of the GET boarding app endpoints, such as GET /Boarding/read/:appId.