{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/qualpay/json-schema/qualpay-add-customer-request-schema.json",
  "title": "AddCustomerRequest",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/qualpay-customer-vault-api-openapi.yml#/components/schemas/AddCustomerRequest",
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>Unique customer ID value established by the merchant. The customer ID can be used to add subscriptions through Recurring Billing API requests or make payments through Payment Gateway API requests. Once established, this ID cannot be updated. This field is case sensitive. Only letters and numbers are allowed in a Customer ID.<br><strong>Conditional Requirement: </strong>Either `customer_id` or `auto_generate_customer_id` is required to add a new customer."
    },
    "auto_generate_customer_id": {
      "type": "boolean",
      "description": "<strong>Description: </strong>Boolean flag that indicates if the customer ID should be auto-generated.  When set to `true`, we generate a unique customer ID, and the generated `customer_id` is returned in the response. Use the returned value to manage the customer profile through Customer Vault API requests. <br><strong>Default: </strong>false<br><strong>Conditional Requirement: </strong>Either `customer_id` or `auto_generate_customer_id` is required to add a new customer."
    },
    "customer_first_name": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>Customer's first name.<br><strong>Conditional Requirement: </strong>Either customer name or `customer_firm_name` is required."
    },
    "customer_last_name": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>Customer's last name.<br><strong>Conditional Requirement: </strong>Either customer name or `customer_firm_name` is required."
    },
    "customer_firm_name": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>Customer business name if applicable. <br><strong>Conditional Requirement: </strong>Either customer name or `customer_firm_name` is required."
    },
    "customer_phone": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 16 AN<br><strong>Description: </strong>Customer's phone number."
    },
    "customer_email": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>Customer's email address. "
    },
    "reference_id": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 128 AN<br><strong>Description: </strong>A merchant-provided value that will be stored with the Customer Vault data for merchant reference."
    },
    "comments": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 128 AN<br><strong>Description: </strong>Comments."
    },
    "developer_id": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>Used to indicate which company developed the integration, or the name of the solution or system that is connected to us. Suggested usage is `softwareABCv1.0` or `companyXYZv2.0`."
    },
    "shipping_addresses": {
      "type": "array",
      "description": "<strong>Description: </strong>An array of shipping addresses. One address should be designated the default shipping address. If it is not, the system selects one address to be the default. ",
      "items": {
        "$ref": "#/$defs/AddShippingAddressRequest"
      }
    },
    "billing_cards": {
      "type": "array",
      "description": "<strong>Description: </strong>An array of billing cards. One of the cards should be designated as the default billing card. If it is not, the system selects one of the cards to be the default. ",
      "items": {
        "$ref": "#/$defs/AddBillingCardRequest"
      }
    },
    "merchant_id": {
      "type": "integer",
      "description": "<strong>Format: </strong>Variable length, up to 16 AN<br><strong>Description: </strong>Identifies the merchant to whom this request applies. Optional field, applicable only if the request is sent on behalf of another merchant.<br><strong>Conditional Requirement: </strong>Required if this request is on behalf of another merchant.",
      "format": "int64"
    }
  },
  "$defs": {
    "AddBillingCardRequest": {
      "required": [
        "billing_zip"
      ],
      "type": "object",
      "properties": {
        "billing_firm_name": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>Business name, if applicable. <br><strong>Conditional Requirement:</strong> When adding an ACH payment method, the following is required:<br> (a) `tr_number`, `dda_number`, `billing_first_name`, and `billing_last_name`, or<br> (b) `tr_number`, `dda_number`, and `billing_firm_name`."
        },
        "billing_first_name": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>Billing first name. <br><strong>Conditional Requirement:</strong> When adding an ACH payment method, the following is required:<br> (a) `tr_number`, `dda_number`, `billing_first_name`, and `billing_last_name`, or<br> (b) `tr_number`, `dda_number`, and `billing_firm_name`."
        },
        "billing_last_name": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>Billing last name. <br><strong>Conditional Requirement:</strong> When adding an ACH payment method, the following is required:<br> (a) `tr_number`, `dda_number`, `billing_first_name`, and `billing_last_name`, or<br> (b) `tr_number`, `dda_number`, and `billing_firm_name`."
        },
        "card_id": {
          "type": "string",
          "description": "<strong>Format: </strong>Fixed length, 32 AN<br><strong>Description: </strong>Card ID received from a tokenization request. `card_id` may be used in place of `card_number` or `card_swipe`. Duplicate cards are not permitted for a customer in the system. The `card_id` should be permanent. If a single-use `card_id` should be used, set the `verify` field to `true`, which makes the `card_id` permanent.<br><strong>Conditional Requirement:</strong> When adding a billing card, the following is required: <br> (a) `card_number`, `exp_date`, and `billing_zip`, or<br> (b) `card_id` and `billing_zip`."
        },
        "card_number": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 16 AN<br><strong>Description: </strong>The full card number.  When a card is added, it is immediately tokenized, and a `card_id` value is generated and stored in Vault.  Duplicate cards are not permitted for a customer in the system.<br><strong>Conditional Requirement:</strong> When adding a billing card, the following is required: <br> (a) `card_number`, `exp_date`, and `billing_zip`, or<br> (b) `card_id` and `billing_zip`."
        },
        "exp_date": {
          "type": "string",
          "description": "<strong>Format: </strong>Fixed length, 4 N, MMYY format<br><strong>Description: </strong>Expiration date of the cardholder's card number.<br><strong>Conditional Requirement:</strong> When adding a billing card, the following is required: <br> (a) `card_number`, `exp_date`, and `billing_zip`, or<br> (b) `card_id` and `billing_zip`."
        },
        "tr_number": {
          "type": "string",
          "description": "<strong>Format: </strong>Fixed length, 9 N<br><strong>Description: </strong>Bank transit/routing number. Applicable for ACH account numbers. <br><strong>Conditional Requirement:</strong> When adding an ACH payment method, the following is required:<br> (a) `tr_number`, `dda_number`, `billing_first_name`, and `billing_last_name`, or<br> (b) `tr_number`, `dda_number`, and `billing_firm_name`."
        },
        "dda_number": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 17 N<br><strong>Description: </strong>Owner's account number at the bank. Applicable for ACH account numbers. <br><strong>Conditional Requirement:</strong> When adding an ACH payment method, the following is required:<br> (a) `tr_number`, `dda_number`, `billing_first_name`, and `billing_last_name`, or<br> (b) `tr_number`, `dda_number`, and `billing_firm_name`."
        },
        "billing_addr1": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 128 AN<br><strong>Description: </strong>Billing street address. This address will also be used for AVS verification if AVS verification is enabled. "
        },
        "billing_addr2": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 128 AN<br><strong>Description: </strong>Billing address line 2."
        },
        "billing_city": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>Billing city."
        },
        "billing_state": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 3 AN<br><strong>Description: </strong>Billing state."
        },
        "billing_zip": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 10 AN<br><strong>Description: </strong>Billing zip code. This field will also be used for AVS verification if AVS verification is enabled. <br><strong>Conditional Requirement:</strong> When adding a billing card, the following is required: <br> (a) `card_number`, `exp_date`, and `billing_zip`, or<br> (b) `card_id` and `billing_zip`."
        },
        "billing_zip4": {
          "type": "string",
          "description": "<strong>Format: </strong>Fixed length, 4 N<br><strong>Description: </strong>Billing zip+4 code if applicable."
        },
        "billing_country": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 128 AN<br><strong>Description: </strong>Billing country."
        },
        "billing_country_code": {
          "type": "string",
          "description": "<strong>Format: </strong>Fixed length, 3 AN<br><strong>Description: </strong>ISO numeric country code for the billing address. Refer to <a href=\"/docs/references\" target=\"_blank\">Country Codes</a> for a list of country codes."
        },
        "billing_email": {
          "type": "array",
          "description": "<strong>Format: </strong>Variable length, up to 128 AN<br><strong>Description: </strong>An array of billing email addresses.",
          "items": {
            "type": "string"
          }
        },
        "cvv2": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 4 N<br><strong>Description: </strong>CVV2 or CID value from the signature panel on the back of the cardholder's card. If present during a request where `verify` is set to `true`, the value will be sent to the issuer for validation. This field is not stored in Customer Vault."
        },
        "merchant_id": {
          "type": "integer",
          "description": "<strong>Format: </strong>Variable length, up to 16 AN<br><strong>Description: </strong>Identifies the merchant to whom this request applies. Optional field, applicable only if the request is sent on behalf of another merchant.<br><strong>Conditional Requirement: </strong>Required if this request is on behalf of another merchant.",
          "format": "int64"
        },
        "primary": {
          "type": "boolean",
          "description": "<strong>Description: </strong>Set this field to `true` if this should be the default card. The default card will be used in recurring billing payments.<br><strong>Default: </strong>false"
        },
        "type_id": {
          "type": "string",
          "description": "<strong>Format: </strong>Fixed length, 1 AN<br><strong>Description: </strong>Bank account type. Applicable for ACH account numbers. Possible values: <ul><li>`C` = Personal checking account</li><li>`S` = Personal savings account</li><li>`K` = Business checking account</li><li>`V` = Business savings account</li></ul><p><strong>Default: </strong>C</p>"
        },
        "verify": {
          "type": "boolean",
          "description": "<strong>Description: </strong>Set this field to `true` if `card_number` or `card_id` should be verified by the issuer before adding to Customer Vault. When this field is set to `true`, the customer is added to Customer Vault regardless of whether verification succeeds.<br><strong>Default: </strong>false"
        }
      }
    },
    "AddShippingAddressRequest": {
      "required": [
        "shipping_first_name",
        "shipping_last_name"
      ],
      "type": "object",
      "properties": {
        "shipping_first_name": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>Shipping first name."
        },
        "shipping_last_name": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>Shipping last name."
        },
        "shipping_firm_name": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>Business name of the shipping address, if applicable. "
        },
        "merchant_id": {
          "type": "integer",
          "description": "<strong>Format: </strong>Variable length, up to 16 AN<br><strong>Description: </strong>Identifies the merchant to whom this request applies. Optional field, applicable only if the request is sent on behalf of another merchant.<br><strong>Conditional Requirement: </strong>Required if this request is on behalf of another merchant.",
          "format": "int64"
        },
        "primary": {
          "type": "boolean",
          "description": "<strong>Description: </strong>Set this field to true if this should be the primary address. <br><strong>Default: </strong>false"
        },
        "shipping_addr1": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 128 AN<br><strong>Description: </strong>Shipping address line 1."
        },
        "shipping_addr2": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 128 AN<br><strong>Description: </strong>Shipping address line 2."
        },
        "shipping_city": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>Shipping city."
        },
        "shipping_state": {
          "type": "string",
          "description": "<strong>Format: </strong>Fixed length, 3 AN<br><strong>Description: </strong>Shipping state."
        },
        "shipping_country": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 128 AN<br><strong>Description: </strong>Shipping country."
        },
        "shipping_country_code": {
          "type": "string",
          "description": "<strong>Format: </strong>Fixed length, 3 AN<br><strong>Description: </strong>ISO numeric country code for the shipping address. Refer to <a href=\"/docs/references\" target=\"_blank\">Country Codes</a> for a list of country codes."
        },
        "shipping_zip": {
          "type": "string",
          "description": "<strong>Format: </strong>Fixed length, 10 AN<br><strong>Description: </strong>Shipping zip code."
        },
        "shipping_zip4": {
          "type": "string",
          "description": "<strong>Format: </strong>Fixed length, 4 N<br><strong>Description: </strong>Shipping zip+4 code, if applicable."
        }
      }
    }
  }
}