{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/canopyservicing-com/json-schema/canopyservicing-com-customer-schema.json",
  "title": "Customer",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/canopyservicing-com-borrowers-api-openapi.yml#/components/schemas/Customer",
  "properties": {
    "passport": {
      "$ref": "#/$defs/PassportDetails"
    },
    "name_prefix": {
      "type": "string",
      "title": "Name Prefix",
      "description": "Prefix to the customer's name."
    },
    "name_first": {
      "type": "string",
      "title": "Name First",
      "description": "Customer's first name."
    },
    "name_middle": {
      "type": "string",
      "title": "Name Middle",
      "description": "Customer's middle name."
    },
    "name_last": {
      "type": "string",
      "title": "Name Last",
      "description": "Customer's last name."
    },
    "name_suffix": {
      "type": "string",
      "title": "Name Suffix",
      "description": "Suffix to the customer's name."
    },
    "address_line_one": {
      "type": "string",
      "title": "Address Line One",
      "description": "Address line one."
    },
    "address_line_two": {
      "type": "string",
      "title": "Address Line Two",
      "description": "Address line two."
    },
    "address_city": {
      "type": "string",
      "title": "Address City",
      "description": "Address city."
    },
    "address_state": {
      "type": "string",
      "title": "Address State",
      "description": "Address state."
    },
    "address_zip": {
      "type": "string",
      "title": "Address Zip",
      "description": "Five digit zipcode or nine digit 'ZIP+4'."
    },
    "address_country_code": {
      "$ref": "#/$defs/AddressCountryCode",
      "description": "ISO 3166-1 alpha-2 country code for the customer."
    },
    "customer_id": {
      "type": "string",
      "title": "Customer Id",
      "description": "An ID for the customer."
    },
    "customer_parent_id": {
      "type": "string",
      "title": "Customer Parent Id",
      "description": "An ID for the customer's parent."
    },
    "organization_id": {
      "type": "integer",
      "title": "Organization Id",
      "description": "The ID of the organization that this customer belongs to."
    },
    "created_at": {
      "type": "string",
      "title": "Created At",
      "description": "The `Date-Time` which the customer was created in the API."
    },
    "updated_at": {
      "type": "string",
      "title": "Updated At",
      "description": "The `Date-Time` which the customer was updated in the API."
    },
    "customer_type": {
      "$ref": "#/$defs/CustomerType",
      "description": "The customer can be either a person or a business. This is used to explicitly set that and adjust behavior such as validation."
    },
    "is_active": {
      "type": "boolean",
      "title": "Is Active",
      "description": "Value manually maintained - defaults to true.\"False\" generally indicates no additional credit should be granted to this customer"
    },
    "verification_status": {
      "$ref": "#/$defs/VerificationStatus-Output",
      "description": "The verification status of this customer. The default is 'unverified'. Depending on the system's configuration verification with third parties will happen and the status will be updated based on the result."
    },
    "title": {
      "type": "string",
      "title": "Title",
      "description": "Title of the customer if a person OR title of the admin if a business"
    },
    "phone_number": {
      "type": "string",
      "title": "Phone Number",
      "description": "Customer's phone number in E.164 format"
    },
    "ssn": {
      "type": "string",
      "title": "Ssn",
      "description": "Social security number of the customer."
    },
    "international_customer_id": {
      "type": "string",
      "title": "International Customer Id",
      "description": "Any country-specific unique identifier for the customer."
    },
    "email": {
      "type": "string",
      "title": "Email",
      "description": "The email address of this Customer"
    },
    "date_of_birth": {
      "type": "string",
      "title": "Date Of Birth",
      "description": "Customer's date of birth in ISO 8601 format"
    },
    "customer_balances": {
      "$ref": "#/$defs/CustomerBalances"
    },
    "customer_entity_counts": {
      "$ref": "#/$defs/CustomerEntityCounts"
    },
    "business_details": {
      "$ref": "#/$defs/BusinessDetails-Output"
    },
    "metro2_config": {
      "$ref": "#/$defs/CustomerMetro2Config-Output"
    },
    "attributes": {
      "additionalProperties": {},
      "type": "object",
      "title": "Attributes",
      "description": "Arbitrary customer attributes"
    }
  },
  "type": "object",
  "required": [
    "address_line_one",
    "address_city",
    "address_state",
    "address_zip",
    "customer_id"
  ],
  "$defs": {
    "AccountDesignation": {
      "properties": {
        "account_id": {
          "type": "string",
          "title": "Account Id",
          "description": "the ID of the account associated with the customer"
        },
        "designation": {
          "$ref": "#/$defs/Designation",
          "description": "The designation of the customer for the account."
        }
      },
      "type": "object",
      "title": "AccountDesignation"
    },
    "AddressCountryCode": {
      "type": "string",
      "enum": [
        "US",
        "GB",
        "CA",
        "AF",
        "AX",
        "AL",
        "DZ",
        "AS",
        "AD",
        "AO",
        "AI",
        "AQ",
        "AG",
        "AR",
        "AM",
        "AN",
        "AW",
        "AU",
        "AT",
        "AZ",
        "BS",
        "BH",
        "BD",
        "BB",
        "BY",
        "BE",
        "BZ",
        "BJ",
        "BM",
        "BT",
        "BO",
        "BA",
        "BW",
        "BV",
        "BR",
        "IO",
        "BN",
        "BG",
        "BF",
        "BI",
        "KH",
        "CM",
        "CV",
        "KY",
        "CF",
        "TD",
        "CL",
        "CN",
        "CX",
        "CC",
        "CO",
        "KM",
        "CG",
        "CD",
        "CK",
        "CR",
        "CI",
        "HR",
        "CU",
        "CY",
        "CZ",
        "DK",
        "DJ",
        "DM",
        "DO",
        "EC",
        "EG",
        "SV",
        "GQ",
        "ER",
        "EE",
        "ET",
        "FK",
        "FO",
        "FJ",
        "FI",
        "FR",
        "GF",
        "PF",
        "TF",
        "GA",
        "GM",
        "GE",
        "DE",
        "GH",
        "GI",
        "GR",
        "GL",
        "GD",
        "GP",
        "GU",
        "GT",
        "GG",
        "GN",
        "GW",
        "GY",
        "HT",
        "HM",
        "VA",
        "HN",
        "HK",
        "HU",
        "IS",
        "IN",
        "ID",
        "IR",
        "IQ",
        "IE",
        "IM",
        "IL",
        "IT",
        "JM",
        "JP",
        "JE",
        "JO",
        "KZ",
        "KE",
        "KI",
        "KR",
        "KW",
        "KG",
        "LA",
        "LV",
        "LB",
        "LS",
        "LR",
        "LY",
        "LI",
        "LT",
        "LU",
        "MO",
        "MK",
        "MG",
        "MW",
        "MY",
        "MV",
        "ML",
        "MT",
        "MH",
        "MQ",
        "MR",
        "MU",
        "YT",
        "MX",
        "FM",
        "MD",
        "MC",
        "MN",
        "ME",
        "MS",
        "MA",
        "MZ",
        "MM",
        "NA",
        "NR",
        "NP",
        "NL",
        "NC",
        "NZ",
        "NI",
        "NE",
        "NG",
        "NU",
        "NF",
        "MP",
        "NO",
        "OM",
        "PK",
        "PW",
        "PS",
        "PA",
        "PG",
        "PY",
        "PE",
        "PH",
        "PN",
        "PL",
        "PT",
        "PR",
        "QA",
        "RE",
        "RO",
        "RU",
        "RW",
        "BL",
        "SH",
        "KN",
        "LC",
        "MF",
        "PM",
        "VC",
        "WS",
        "SM",
        "ST",
        "SA",
        "SN",
        "RS",
        "SC",
        "SL",
        "SG",
        "SK",
        "SI",
        "SB",
        "SO",
        "ZA",
        "GS",
        "ES",
        "LK",
        "SD",
        "SR",
        "SJ",
        "SZ",
        "SE",
        "CH",
        "SY",
        "TW",
        "TJ",
        "TZ",
        "TH",
        "TL",
        "TG",
        "TK",
        "TO",
        "TT",
        "TN",
        "TR",
        "TM",
        "TC",
        "TV",
        "UG",
        "UA",
        "AE",
        "UM",
        "UY",
        "UZ",
        "VU",
        "VE",
        "VN",
        "VG",
        "VI",
        "WF",
        "EH",
        "YE",
        "ZM",
        "ZW"
      ],
      "title": "AddressCountryCode"
    },
    "AddressType": {
      "type": "string",
      "enum": [
        "CONFIRMED",
        "KNOWN",
        "NOT_CONFIRMED",
        "MILITARY",
        "SECONDARY",
        "BUSINESS",
        "UNDELIVERABLE",
        "DEFAULT",
        "BILL_PAYER_SERVICE"
      ],
      "title": "AddressType"
    },
    "BloomMetadata-Output": {
      "properties": {
        "address_type": {
          "$ref": "#/$defs/AddressType",
          "description": "Status of the reported address."
        },
        "residence_type": {
          "$ref": "#/$defs/ResidenceType",
          "description": "Optional, if not available or unknown, do not report."
        },
        "account_designations": {
          "items": {
            "$ref": "#/$defs/AccountDesignation"
          },
          "type": "array",
          "title": "Account Designations",
          "description": "A list of accounts associated with the customer."
        }
      },
      "type": "object",
      "title": "BloomMetadata"
    },
    "BusinessDetails-Output": {
      "properties": {
        "business_legal_name": {
          "type": "string",
          "title": "Business Legal Name",
          "description": "The legal name of the Business."
        },
        "doing_business_as": {
          "type": "string",
          "title": "Doing Business As",
          "description": "The DBA name of the Business."
        },
        "business_ein": {
          "type": "string",
          "title": "Business Ein",
          "description": "EIN of the business, expected format in NN-NNNNNNN."
        },
        "business_type": {
          "$ref": "#/$defs/BusinessType",
          "description": "Type of business is used in determining the appropriate validation."
        },
        "business_classification_id": {
          "type": "string",
          "title": "Business Classification Id",
          "description": "UUID that references the business classification. This will eventually be supported by a reference api, however, for now refer to dwolla's specific UUID."
        },
        "website": {
          "type": "string",
          "title": "Website",
          "description": "URL for the business's website. This should be publicly resolvable"
        },
        "controller": {
          "$ref": "#/$defs/Controller"
        }
      },
      "type": "object",
      "title": "BusinessDetails"
    },
    "BusinessType": {
      "type": "string",
      "enum": [
        "sole_proprietorship",
        "llc",
        "unincorporated_association",
        "trust",
        "corporation",
        "corporation_public",
        "non_profile",
        "partnership"
      ],
      "title": "BusinessType"
    },
    "Controller": {
      "properties": {
        "passport": {
          "$ref": "#/$defs/PassportDetails"
        },
        "name_prefix": {
          "type": "string",
          "title": "Name Prefix",
          "description": "Prefix to the customer's name."
        },
        "name_first": {
          "type": "string",
          "title": "Name First",
          "description": "Customer's first name."
        },
        "name_middle": {
          "type": "string",
          "title": "Name Middle",
          "description": "Customer's middle name."
        },
        "name_last": {
          "type": "string",
          "title": "Name Last",
          "description": "Customer's last name."
        },
        "name_suffix": {
          "type": "string",
          "title": "Name Suffix",
          "description": "Suffix to the customer's name."
        },
        "address_line_one": {
          "type": "string",
          "title": "Address Line One",
          "description": "Address line one."
        },
        "address_line_two": {
          "type": "string",
          "title": "Address Line Two",
          "description": "Address line two."
        },
        "address_city": {
          "type": "string",
          "title": "Address City",
          "description": "Address city."
        },
        "address_state": {
          "type": "string",
          "title": "Address State",
          "description": "Address state."
        },
        "address_zip": {
          "type": "string",
          "title": "Address Zip",
          "description": "Five digit zipcode or nine digit 'ZIP+4'."
        },
        "address_country_code": {
          "$ref": "#/$defs/AddressCountryCode",
          "description": "ISO 3166-1 alpha-2 country code for the customer."
        },
        "date_of_birth": {
          "type": "string",
          "format": "date",
          "title": "Date Of Birth",
          "description": "Customer's date of birth in ISO 8601 format"
        },
        "email": {
          "type": "string",
          "title": "Email",
          "description": "The email address of this Customer"
        },
        "title": {
          "type": "string",
          "title": "Title",
          "description": "Title of the customer if a person OR title of the admin if a business"
        },
        "phone_number": {
          "type": "string",
          "title": "Phone Number",
          "description": "Customer's phone number in E.164 format."
        },
        "ssn": {
          "type": "string",
          "title": "Ssn",
          "description": "Social security number of the customer."
        }
      },
      "type": "object",
      "required": [
        "address_line_one",
        "address_city",
        "address_state",
        "address_zip"
      ],
      "title": "Controller"
    },
    "CustomerBalances": {
      "properties": {
        "num_active_accounts": {
          "type": "integer",
          "title": "Num Active Accounts",
          "description": "The number of active accounts for this customer."
        },
        "total_balance_cents": {
          "type": "integer",
          "title": "Total Balance Cents",
          "description": "The total outstanding balance (in cents) associated with all active accounts for this customer. This balance is comprised of the sum of the following six balance items."
        },
        "principal_cents": {
          "type": "integer",
          "title": "Principal Cents",
          "description": "The total principal balance (in cents) associated with all active accounts for this customer."
        },
        "interest_balance_cents": {
          "type": "integer",
          "title": "Interest Balance Cents",
          "description": "The total interest balance (in cents) associated with all active accounts for this customer."
        },
        "am_interest_balance_cents": {
          "type": "integer",
          "title": "Am Interest Balance Cents",
          "description": "The total AM interest balance (in cents) associated with all active accounts for this customer.",
          "default": 0
        },
        "deferred_interest_balance_cents": {
          "type": "integer",
          "title": "Deferred Interest Balance Cents",
          "description": "The total deferred interest balance (in cents) associated with all active accounts for this customer.",
          "default": 0
        },
        "am_deferred_interest_balance_cents": {
          "type": "integer",
          "title": "Am Deferred Interest Balance Cents",
          "description": "The total AM deferred interest balance (in cents) associated with all active accounts for this customer.",
          "default": 0
        },
        "fees_balance_cents": {
          "type": "integer",
          "title": "Fees Balance Cents",
          "description": "The total fees balance (in cents) associated with all active accounts for this customer.",
          "default": 0
        }
      },
      "type": "object",
      "title": "CustomerBalances"
    },
    "CustomerEntityCounts": {
      "properties": {
        "financing_requests_pending_count": {
          "type": "integer",
          "title": "Financing Requests Pending Count",
          "description": "The number of financing requests in the pending state for this customer.",
          "default": 0
        },
        "financing_requests_approved_count": {
          "type": "integer",
          "title": "Financing Requests Approved Count",
          "description": "The number of financing requests in the approved state for this customer.",
          "default": 0
        },
        "financing_requests_rejected_count": {
          "type": "integer",
          "title": "Financing Requests Rejected Count",
          "description": "The number of financing requests in the rejected state for this customer.",
          "default": 0
        },
        "financing_requests_converted_count": {
          "type": "integer",
          "title": "Financing Requests Converted Count",
          "description": "The number of financing requests in the converted state for this customer.",
          "default": 0
        },
        "financing_requests_in_review_count": {
          "type": "integer",
          "title": "Financing Requests In Review Count",
          "description": "The number of financing requests in the in_review state for this customer.",
          "default": 0
        }
      },
      "type": "object",
      "title": "CustomerEntityCounts"
    },
    "CustomerMetro2Config-Output": {
      "properties": {
        "bloom_metadata": {
          "$ref": "#/$defs/BloomMetadata-Output",
          "description": "Bloom API fields for customers: https://docs.bloom.dev/docs/furnishment-api/b3A6MjA1NTM1MQ-create-consumer"
        }
      },
      "type": "object",
      "title": "CustomerMetro2Config"
    },
    "CustomerType": {
      "type": "string",
      "enum": [
        "person",
        "business"
      ],
      "title": "CustomerType"
    },
    "Designation": {
      "type": "string",
      "enum": [
        "INDIVIDUAL",
        "JOINT_CONTRACTUAL_LIABILITY",
        "AUTHORIZED_USER",
        "COMAKER_OR_GUARANTOR",
        "MAKER",
        "BUSINESS_COMMERCIAL",
        "DECEASED"
      ],
      "title": "Designation"
    },
    "PassportDetails": {
      "properties": {
        "number": {
          "type": "string",
          "title": "Number",
          "description": "Number on the passport"
        },
        "country": {
          "type": "string",
          "title": "Country",
          "description": "ISO 3166-1 Two letter code for the issuing country"
        }
      },
      "type": "object",
      "title": "PassportDetails"
    },
    "ResidenceType": {
      "type": "string",
      "enum": [
        "OWNS",
        "RENTS"
      ],
      "title": "ResidenceType"
    },
    "VerificationStatus-Output": {
      "type": "string",
      "enum": [
        "unverified",
        "verified",
        "retry",
        "document"
      ],
      "title": "VerificationStatus"
    }
  }
}