Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.circle.com/llms.txt

Use this file to discover all available pages before exploring further.

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:
ConditionDescription
Exact string matchA field equals a specific value
boolean matchA field is true or false
enum (OR)A field matches any value in a list
containsAn array field contains a specific value
NegationA 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.