{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "Customer.json",
  "title": "Customer",
  "description": "Someone the organization bills: an individual or a company.",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "format": "int32",
      "description": "Flux's id for the customer."
    },
    "externalRef": {
      "type": [
        "string",
        "null"
      ],
      "description": "Your id for the customer, such as a workspace id. Unique within the organization."
    },
    "customerType": {
      "type": "string",
      "enum": [
        "individual",
        "company"
      ],
      "description": "individual or company."
    },
    "name": {
      "type": "string",
      "description": "The billing name. For a company, the legal name, else the company name. For an individual, their name."
    },
    "legalName": {
      "type": [
        "string",
        "null"
      ],
      "description": "Registered legal name."
    },
    "companyName": {
      "type": [
        "string",
        "null"
      ],
      "description": "Trading name. Set for companies."
    },
    "firstName": {
      "type": [
        "string",
        "null"
      ],
      "description": "Set for individuals."
    },
    "lastName": {
      "type": [
        "string",
        "null"
      ],
      "description": "Set for individuals."
    },
    "email": {
      "type": "string",
      "description": "The customer's email. Gets invoices when there's no primary contact."
    },
    "phone": {
      "type": [
        "string",
        "null"
      ],
      "description": "In international format."
    },
    "address": {
      "type": [
        "string",
        "null"
      ],
      "description": "Postal address."
    },
    "taxId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Tax identification number (TIN). Unique within the organization."
    },
    "vatNumber": {
      "type": [
        "string",
        "null"
      ],
      "description": "VAT registration number."
    },
    "rcNumber": {
      "type": [
        "string",
        "null"
      ],
      "description": "CAC registration (RC) number."
    },
    "parentCustomerId": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int32",
      "description": "The group company this customer belongs to, in the same organization."
    },
    "regulatedEntityCount": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int32",
      "description": "Number of regulated entities. 0 or more."
    },
    "defaultCurrency": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "NGN",
        "USD",
        "CAD",
        "EUR",
        "GBP",
        null
      ],
      "description": "Pre-fills the currency when someone raises an invoice for this customer in the Flux app."
    },
    "defaultSettlementBankId": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int32",
      "description": "The organization's bank account that this customer's payments settle into. Ids come from the Flux app."
    },
    "contacts": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "CustomerContact.json"
      },
      "description": "Billing contacts. Returned by get, create and update. Always null in list results."
    },
    "createdAt": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?$",
      "description": "When the customer was created. Server time, no offset."
    },
    "updatedAt": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?$",
      "description": "When the customer last changed. null if never."
    }
  },
  "required": [
    "id",
    "externalRef",
    "customerType",
    "name",
    "legalName",
    "companyName",
    "firstName",
    "lastName",
    "email",
    "phone",
    "address",
    "taxId",
    "vatNumber",
    "rcNumber",
    "parentCustomerId",
    "regulatedEntityCount",
    "defaultCurrency",
    "defaultSettlementBankId",
    "contacts",
    "createdAt",
    "updatedAt"
  ],
  "examples": [
    {
      "id": 812,
      "externalRef": "ws_42",
      "customerType": "company",
      "name": "Leadway Group Plc",
      "legalName": "Leadway Group Plc",
      "companyName": "Leadway Group",
      "firstName": null,
      "lastName": null,
      "email": "finance@leadway.example",
      "phone": "+2348012345678",
      "address": "121 Funso Williams Ave, Lagos",
      "taxId": "12345678-0001",
      "vatNumber": "VAT-001",
      "rcNumber": "RC123456",
      "parentCustomerId": null,
      "regulatedEntityCount": 3,
      "defaultCurrency": "NGN",
      "defaultSettlementBankId": null,
      "contacts": [
        {
          "name": "Finance",
          "email": "finance@leadway.example",
          "phone": null,
          "isBillingPrimary": true,
          "ccOnInvoices": false
        },
        {
          "name": "CFO",
          "email": "cfo@leadway.example",
          "phone": null,
          "isBillingPrimary": false,
          "ccOnInvoices": true
        }
      ],
      "createdAt": "2026-11-01T10:20:00",
      "updatedAt": null
    }
  ]
}