OpalTokenCreateRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/methodfi/main/json-schema/methodfi-opal-token-create-request-schema.json",
  "title": "OpalTokenCreateRequest",
  "description": "Request to create an Opal token. Supports three creation patterns: (A) existing entity via `entity_id`, (B) inline entity via `entity`, or (C) existing session via `session_id`. Exactly one of these three fields must be provided.",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/methodfi-opal-api-openapi.yml#/components/schemas/OpalTokenCreateRequest",
  "type": "object",
  "properties": {
    "entity_id": {
      "type": "string",
      "description": "Pattern A: ID of an existing entity to use for the session."
    },
    "entity": {
      "type": "object",
      "description": "Pattern B: Inline entity creation payload.",
      "properties": {
        "type": {
          "type": "string",
          "description": "Entity type.",
          "enum": [
            "individual"
          ]
        },
        "individual": {
          "type": "object",
          "description": "Individual details for entity creation."
        }
      }
    },
    "session_id": {
      "type": "string",
      "description": "Pattern C: ID of an existing session to create an additional token for."
    },
    "mode": {
      "$ref": "#/$defs/OpalSessionMode"
    },
    "appearance": {
      "type": "string",
      "enum": [
        "light",
        "dark",
        "system"
      ],
      "description": "UI appearance theme for the session."
    },
    "identity_verification": {
      "type": "object",
      "description": "Configuration for the `identity_verification` mode. Required when `mode` is `identity_verification`.",
      "properties": {
        "skip_pii": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "PII fields to skip during identity verification."
        }
      }
    },
    "card_connect": {
      "type": "object",
      "description": "Configuration for the `card_connect` mode. Required when `mode` is `card_connect`.",
      "required": [
        "selection_type"
      ],
      "properties": {
        "selection_type": {
          "type": "string",
          "enum": [
            "single",
            "multiple"
          ],
          "description": "Whether the user can select one or multiple cards."
        },
        "account_filters": {
          "$ref": "#/$defs/OpalCardConnectAccountFilters"
        },
        "skip_pii": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "PII fields to skip during identity verification."
        }
      }
    },
    "connect": {
      "type": "object",
      "description": "Configuration for the `connect` mode. Required when `mode` is `connect`.",
      "required": [
        "selection_type"
      ],
      "properties": {
        "selection_type": {
          "type": "string",
          "enum": [
            "single",
            "multiple",
            "all"
          ],
          "description": "Account selection behavior."
        },
        "account_filters": {
          "$ref": "#/$defs/OpalConnectAccountFilters"
        },
        "skip_pii": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "PII fields to skip during identity verification."
        }
      }
    },
    "account_verification": {
      "type": "object",
      "description": "Configuration for the `account_verification` mode. Required when `mode` is `account_verification`.",
      "required": [
        "account_id"
      ],
      "properties": {
        "account_id": {
          "type": "string",
          "description": "ID of the account to verify."
        },
        "intent": {
          "type": "string",
          "enum": [
            "data",
            "payments",
            "transactions"
          ],
          "description": "The intent for account verification."
        }
      }
    },
    "transactions": {
      "type": "object",
      "description": "Configuration for the `transactions` mode. Required when `mode` is `transactions`."
    }
  },
  "$defs": {
    "OpalCardConnectAccountFilters": {
      "type": "object",
      "description": "Account filters for the card_connect mode.",
      "properties": {
        "exclude": {
          "type": "object",
          "properties": {
            "mch_ids": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Merchant IDs to exclude."
            },
            "unverified_account_numbers": {
              "type": "boolean",
              "description": "Whether to exclude accounts with unverified numbers."
            }
          }
        }
      }
    },
    "OpalConnectAccountFilters": {
      "type": "object",
      "description": "Account filters for the connect mode.",
      "properties": {
        "include": {
          "type": "object",
          "properties": {
            "account_types": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Account liability types to include."
            },
            "products": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string"
              },
              "description": "Required products to filter by."
            }
          }
        },
        "exclude": {
          "type": "object",
          "properties": {
            "account_types": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Account liability types to exclude."
            },
            "mch_ids": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Merchant IDs to exclude."
            },
            "unverified_account_numbers": {
              "type": "boolean",
              "description": "Whether to exclude accounts with unverified numbers."
            }
          }
        }
      }
    },
    "OpalSessionMode": {
      "type": "string",
      "description": "The mode that determines which flows are configured for the session.",
      "enum": [
        "identity_verification",
        "card_connect",
        "connect",
        "account_verification",
        "transactions"
      ]
    }
  }
}