Conditional Logic

Understand how Nature of Business and JSON Schema conditionals control which fields are required

The Partner Onboarding schema uses JSON Schema if/then constructs to express conditional requirements. Not all sections and fields apply to every application. The schema defines what is required based on the application’s configuration.

Nature of business

The primary conditional driver is Nature of Business (NOB). This classification is set during application creation and determines which sections and fields appear. For example, a cryptoExchange application may require different documentation than a trust application.

How conditionals work

The allOf array in the schema contains if/then blocks:

• The if clause checks the value of a parent field (most commonly nature_of_business).
• When the condition is met, the then clause adds fields to the required array, making them mandatory.

Supported condition types:

Condition	Description
Exact string match	A field equals a specific value
boolean match	A field is true or false
enum (OR)	A field matches any value in a list
contains	An array field contains a specific value
Negation	A field does not match a value

The following example shows an exact string match condition:

{
  "if": {
    "properties": {
      "natureOfBusiness": { "const": "cryptoExchange" }
    }
  },
  "then": {
    "properties": {
      "cryptoExchangeLicenseNumber": {
        "type": "string",
        "minLength": 1
      }
    },
    "required": ["cryptoExchangeLicenseNumber"]
  }
}

In this example, when natureOfBusiness is cryptoExchange, the schema requires the cryptoExchangeLicenseNumber field.

Conditional side effects

After saving a section that contains a conditional parent field (for example, beneficialOwnersExist), other sections may activate or deactivate. This includes array sections, which can be conditionally activated. The API signals this through two mechanisms:

1. sectionsChanged flag—Returned in every save response. When true, the section list has changed and you should re-fetch sections.
2. Updated sections array—The response includes the current status of all active sections, not just the one you saved.

Always check the sectionsChanged flag after saving section data. If you ignore it, your integration may submit incomplete applications or miss newly required sections.

Mutually exclusive groups

Some conditionals create mutually exclusive branches. For example, different variants of basic_business_info may exist for different NOB values. Only one branch’s fields are required at a time. The schema enforces this automatically.

Design considerations

• Integrations that skip re-fetching after a sectionsChanged response risk submitting incomplete applications.
• Client-side validation against the schema (minLength, pattern, enum) before submitting reduces round-trips and improves the user experience.