---
updatedAt: 2026-05-29T13:25:42.000Z
agentTools:
  projectIndex: https://developer.eftcorp.com/llms.txt
---

# Register a new Customer

Registers a new customer profile under the tenant and returns the created customer. Optionally accepts a `positions` list to atomically assign the customer one or more Organisation positions as part of the same call — the recommended way to link a new customer to an Organisation without a separate call to the positions API.

# OpenAPI definition

```json
{
  "servers": [
    {
      "url": "https://eclipse-java-sandbox.ukheshe.rocks",
      "description": "Eclipse sandbox environment"
    },
    {
      "url": "https://ukheshe.live",
      "description": "Eclipse production environment"
    },
    {
      "url": "https://eclipse-java-develop.ukheshe.rocks",
      "description": "Eclipse development environment"
    },
    {
      "url": "https://zw.ukheshe.live",
      "description": "Zim Eclipse production environment"
    }
  ],
  "openapi": "3.1.0",
  "components": {
    "schemas": {
      "AddressType": {
        "type": "string",
        "enum": [
          "BRANCH",
          "HEADQUARTERS",
          "OPERATING",
          "PHYSICAL",
          "POSTAL",
          "PRIMARY",
          "REGISTERED"
        ]
      },
      "Avp": {
        "description": "An attribute/value pair for providing weakly typed data on various messages",
        "type": "object",
        "required": [
          "att",
          "val"
        ],
        "properties": {
          "att": {
            "type": "string",
            "pattern": "\\S"
          },
          "val": {
            "type": "string"
          }
        }
      },
      "BusinessType": {
        "type": "string",
        "enum": [
          "CLOSE_CORPORATION",
          "LIMITED_COMPANY",
          "PARTNERSHIP",
          "PERSONAL_LIABILITY_COMPANY",
          "PUBLIC_LISTED_COMPANY",
          "SOLE_PROPRIETOR",
          "STATE_OWNED_COMPANY",
          "TRUST",
          "UNREGISTERED"
        ]
      },
      "EclipseAddress": {
        "description": "A physical, postal or other type of address that can be captured against an organisation or customer",
        "type": "object",
        "properties": {
          "addressId": {
            "type": "integer",
            "format": "int64",
            "description": "Unique system generated identifier for an address",
            "exclusiveMinimum": 0
          },
          "addressType": {
            "$ref": "#/components/schemas/AddressType",
            "description": "Type of address",
            "type": "string"
          },
          "city": {
            "type": "string",
            "minLength": 2,
            "maxLength": 20
          },
          "code": {
            "type": "string",
            "pattern": "^$|^.{3,10}$",
            "minLength": 0,
            "maxLength": 10
          },
          "country": {
            "type": "string",
            "minLength": 2,
            "maxLength": 60
          },
          "customerId": {
            "type": "integer",
            "format": "int64",
            "description": "The customer the address is for"
          },
          "gpsLatitude": {
            "type": "number",
            "description": "GPS latitude of the address in decimal degrees",
            "maximum": 90,
            "minimum": -90
          },
          "gpsLongitude": {
            "type": "number",
            "description": "GPS longitude of the address in decimal degrees",
            "maximum": 180,
            "minimum": -180
          },
          "line1": {
            "type": "string",
            "pattern": "^[A-Za-z0-9À-ÿ][A-Za-z0-9À-ÿ_\\s'.,&:#*()_`/-]*$",
            "minLength": 1,
            "maxLength": 150
          },
          "line2": {
            "type": "string",
            "pattern": "^$|^[A-Za-z0-9À-ÿ][A-Za-z0-9À-ÿ_\\s'.,&:#*()_`/-]*$",
            "minLength": 0,
            "maxLength": 150
          },
          "line3": {
            "type": "string",
            "pattern": "^$|^[A-Za-z0-9À-ÿ][A-Za-z0-9À-ÿ_\\s'.,&:#*()_`/-]*$",
            "minLength": 0,
            "maxLength": 150
          },
          "organisationId": {
            "type": "integer",
            "format": "int64",
            "description": "The organisation the address is for"
          },
          "state": {
            "type": "string",
            "minLength": 3,
            "maxLength": 50
          },
          "tenantId": {
            "type": "integer",
            "format": "int64"
          },
          "version": {
            "type": "integer",
            "format": "int32",
            "description": "A number indicating the version of the record. Updates will only be accepted if the passed in version is the same as the current version on record. This is in order to prevent concurrent modifications by multiple users.",
            "minimum": 0
          }
        },
        "required": [
          "addressType",
          "line1",
          "city",
          "state",
          "country",
          "version"
        ]
      },
      "EclipseCustomer": {
        "description": "A customer of a Tenant. A physical human being with a legal identity. Customers can be grouped into an organisation if needed. Customers can belong to multiple organisations. Customers link to an organisation is through the posiiton they hold in that organisation.",
        "type": "object",
        "properties": {
          "accountableInstitutionCif": {
            "type": "string"
          },
          "additionalIdentityNumber": {
            "type": "string",
            "description": "Additional identity number",
            "pattern": "^[A-Za-z0-9/]*$",
            "minLength": 5,
            "maxLength": 20
          },
          "address": {
            "$ref": "#/components/schemas/EclipseAddress",
            "description": "Optional selected address. Populated for golden customer responses only",
            "type": "object"
          },
          "asylumCountryOfIssuance": {
            "type": "string",
            "description": "ISO Alpha-2 country code for Issue of Asylum",
            "minLength": 2,
            "maxLength": 2
          },
          "asylumDateOfIssuance": {
            "type": "string",
            "description": "Mandatory If the asylum number is provided and must be in form of yyyyMMdd",
            "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "asylumPaperExpiry": {
            "type": "string",
            "description": "Mandatory If the asylum ref number is provided and must be in form of yyyyMMdd",
            "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "asylumRefNumber": {
            "type": "string",
            "description": "Asylum ref number",
            "pattern": "^[A-Za-z0-9]+(?:\\/[A-Za-z0-9]+)*$",
            "minLength": 5,
            "maxLength": 15
          },
          "birthCity": {
            "type": "string",
            "description": "Customer City of birth ",
            "minLength": 0,
            "maxLength": 20
          },
          "birthCountry": {
            "type": "string",
            "description": "Customer Country of birth - Eclipse will support ISO two character, all the existing countries will be replaced by the ISO two character country code. For example if 'South Africa' has added as Birth Country it will be replaced by 'ZA'",
            "minLength": 0,
            "maxLength": 60
          },
          "communicationPreference": {
            "$ref": "#/components/schemas/EclipseNotificationType"
          },
          "countryOfResidence": {
            "type": "string",
            "description": "Customer's resident country"
          },
          "countryOfTaxation": {
            "type": "string",
            "description": "FATCA/CRS: ISO country code of taxation jurisdiction",
            "minLength": 0,
            "maxLength": 3
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "examples": [
              "2022-03-10T12:15:50-04:00"
            ],
            "description": "ISO 8601 date/time of when the record was first created"
          },
          "customerId": {
            "type": "integer",
            "format": "int64",
            "description": "Unique system generated identifier for a customer",
            "exclusiveMinimum": 0
          },
          "dateOfBirth": {
            "type": "string",
            "description": "Customer Date of birth must be in form of yyyyMMdd",
            "pattern": "^(18|19|20)(\\d{2})(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "email": {
            "type": "string",
            "description": "Customers email address",
            "pattern": "^[\\w\\.\\+-]+@([\\w-]+\\.)+[\\w-]{2,10}$",
            "minLength": 10,
            "maxLength": 50
          },
          "externalUniqueId": {
            "type": "string",
            "description": "A globally unique identifier set by the tenant for this customer. Useful for correlating between the tenants systems and Eclipse"
          },
          "firstName": {
            "type": "string",
            "description": "Customer first/given name",
            "pattern": "^\\D*$",
            "minLength": 2,
            "maxLength": 50
          },
          "gender": {
            "$ref": "#/components/schemas/Gender",
            "description": "The gender of the customer",
            "type": "string"
          },
          "industry": {
            "type": "string",
            "description": "Industry customer belongs to"
          },
          "isForeignTaxResident": {
            "type": "boolean",
            "description": "FATCA/CRS: Whether the customer is a foreign tax resident"
          },
          "lastModified": {
            "type": "string",
            "format": "date-time",
            "examples": [
              "2022-03-10T12:15:50-04:00"
            ],
            "description": "ISO 8601 date/time of when the record was last modified"
          },
          "lastName": {
            "type": "string",
            "description": "Customers last/family name",
            "pattern": "^\\D*$",
            "minLength": 2,
            "maxLength": 50
          },
          "locale": {
            "type": "string",
            "description": "ISO 639-1 language code of the customer",
            "minLength": 2,
            "maxLength": 2
          },
          "maidenName": {
            "type": "string",
            "description": "Customers maiden name",
            "minLength": 2,
            "maxLength": 50
          },
          "maritalStatus": {
            "$ref": "#/components/schemas/MaritalStatus",
            "description": "Maritial status of the customer",
            "type": "string"
          },
          "middleName": {
            "type": "string",
            "description": "Customers middle name",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9\\s.\\-'&]*$",
            "minLength": 2,
            "maxLength": 50
          },
          "mobileNumberValidated": {
            "type": "boolean",
            "description": "Whether phone1 has been verified as belonging to the customer, either via Eclipse OTP verification or confirmed by the channel. Defaults to false if not set."
          },
          "monthlyIncome": {
            "type": "integer",
            "format": "int64",
            "description": "Customer's expected income per month"
          },
          "nationalIdentityCountryOfIssuance": {
            "type": "string",
            "description": "ISO Alpha-2 country code for Issue of National Identity",
            "minLength": 2,
            "maxLength": 2
          },
          "nationalIdentityDateOfIssuance": {
            "type": "string",
            "description": "Mandatory If the national identity number is provided and must be in form of yyyyMMdd",
            "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "nationalIdentityExpiry": {
            "type": "string",
            "description": "Mandatory If the national identity number is provided and must be in form of yyyyMMdd",
            "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "nationalIdentityNumber": {
            "type": "string",
            "description": "National identity number",
            "pattern": "^[A-Za-z0-9/-]*$",
            "minLength": 5,
            "maxLength": 20
          },
          "nationalIdentitySerialNumber": {
            "type": "string",
            "description": "national identity serial number of customer",
            "minLength": 0,
            "maxLength": 20
          },
          "nationality": {
            "type": "string",
            "description": "Nationality of Customer",
            "minLength": 0,
            "maxLength": 50
          },
          "nextMandatoryKycDate": {
            "type": "string",
            "format": "date-time",
            "examples": [
              "2022-03-10T12:15:50-04:00"
            ]
          },
          "nextOfKinInfo": {
            "type": "string",
            "description": "Next of kin info as a json",
            "minLength": 0,
            "maxLength": 500
          },
          "other": {
            "type": "string",
            "description": "",
            "minLength": 0,
            "maxLength": 5000
          },
          "passportCountry": {
            "type": "string",
            "description": "ISO Alpha-2 country code",
            "minLength": 2,
            "maxLength": 2
          },
          "passportDateOfIssuance": {
            "type": "string",
            "description": "Mandatory If the passport number is provided and must be in form of yyyyMMdd",
            "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "passportExpiry": {
            "type": "string",
            "description": "Mandatory If the passport number is provided and must be in form of yyyyMMdd",
            "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "passportNumber": {
            "type": "string",
            "description": "National identity number",
            "pattern": "^[A-Za-z0-9]*$",
            "minLength": 5,
            "maxLength": 20
          },
          "passportPlaceOfIssuance": {
            "type": "string",
            "description": "Mandatory If the passport number is provided.",
            "minLength": 2,
            "maxLength": 60
          },
          "permitExpiry": {
            "type": "string",
            "description": "Mandatory If the PERMIT is provided and must be in form of yyyyMMdd.",
            "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "permitNumber": {
            "type": "string",
            "description": "Permit number"
          },
          "phone1": {
            "type": "string",
            "description": "Customers primary phone number",
            "pattern": "^[0-9]{8,16}$"
          },
          "phone2": {
            "type": "string",
            "description": "Customers secondary phone number",
            "pattern": "^[0-9]{8,16}$"
          },
          "positions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EclipseCustomerPosition"
            },
            "description": "Positions the customer has in organisations. Only populated if the fields parameter has positions in it"
          },
          "profession": {
            "type": "string",
            "description": "Customer's profession"
          },
          "profileCompletionStatus": {
            "type": "integer",
            "format": "int32",
            "description": "Determines if the customer can update their own Profile, Adddress,Documents. This int is a bitmask. Least significant bit (bit 1) means the basic profile data like last name is complete and cannot be changed by the customer themselves. Bit 2 indicates Address data cannot be changed. Bit 3 means documents are complete. Bit 4 means attachments are complete. Bit 5 means DOB is complete. But 6 means National Identity number is complete. E.g. To disallow changing attachments, documents, and addresses only, this int would be set as 001110 = 14"
          },
          "purposeOfUse": {
            "type": "string",
            "description": "Purpose of business Relationship"
          },
          "reasonCode": {
            "$ref": "#/components/schemas/StatusChangeReasonCode"
          },
          "riskRating": {
            "type": "string"
          },
          "riskScore": {
            "type": "number",
            "description": "Customers are assigned a risk score based on their KYC information. The score is determined by various factors and helps financial institutions manage risk and prevent fraud or losses."
          },
          "schoolName": {
            "type": "string",
            "description": "School name of customer",
            "minLength": 0,
            "maxLength": 50
          },
          "sourceOfFunds": {
            "type": "string",
            "description": "Customer's source of fund"
          },
          "sourceOfWealth": {
            "type": "string",
            "minLength": 2,
            "maxLength": 500
          },
          "ssn": {
            "type": "string",
            "description": "FATCA/CRS: US Social Security Number",
            "minLength": 0,
            "maxLength": 50
          },
          "status": {
            "$ref": "#/components/schemas/EclipseCustomerStatus",
            "description": "Status of the customer. This is set/updated by the tenant and acts as a flag. It has no associated logic or implications within Eclipse itself",
            "type": "string"
          },
          "taxNumber": {
            "type": "string",
            "description": "Tax number of customer",
            "minLength": 0,
            "maxLength": 20
          },
          "temporaryIdentityExpiry": {
            "type": "string",
            "description": "Mandatory If the temporary Id is provided and must be in form of yyyyMMdd. User should enter temporaryIdentityExpiry = issue date + 2 months",
            "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "tenantId": {
            "type": "integer",
            "format": "int64",
            "description": "The unique identifier of the tenant this customer belongs to"
          },
          "title": {
            "$ref": "#/components/schemas/EclipseTitle",
            "description": "The title/salutation of the customer",
            "type": "string"
          },
          "userTypeId": {
            "type": "integer",
            "format": "int32"
          },
          "version": {
            "type": "integer",
            "format": "int32",
            "description": "A number indicating the version of the record. Updates will only be accepted if the passed in version is the same as the current version on record. This is in order to prevent concurrent modifications by multiple users.",
            "minimum": 0
          },
          "walletRiskScore": {
            "type": "number",
            "description": "Wallet risk score is calculated by multiplying the risk of the wallet type by the risk of the customer profile."
          }
        },
        "required": [
          "version"
        ]
      },
      "EclipseCustomerPosition": {
        "type": "object",
        "description": "The position of a customer within an Organisation. E.g. HEAD, DIRECTOR, MANAGER, OWNER etc",
        "required": [
          "organisationId",
          "position"
        ],
        "properties": {
          "division": {
            "$ref": "#/components/schemas/EclipseDivision"
          },
          "divisionId": {
            "type": "integer",
            "format": "int64"
          },
          "organisation": {
            "$ref": "#/components/schemas/EclipseOrganisation"
          },
          "organisationId": {
            "type": "integer",
            "format": "int64"
          },
          "position": {
            "$ref": "#/components/schemas/OrganisationPosition"
          }
        }
      },
      "EclipseCustomerStatus": {
        "description": "Status of the eclipse customer. ACTIVE:Customer is Active, INACTIVE customer is INACTIVE",
        "type": "string",
        "enum": [
          "ACTIVE",
          "BARRED",
          "INACTIVE"
        ]
      },
      "EclipseDivision": {
        "type": "object",
        "properties": {
          "divisionId": {
            "type": "integer",
            "format": "int64"
          },
          "divisionName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 50
          },
          "organisationId": {
            "type": "integer",
            "format": "int64"
          }
        },
        "required": [
          "divisionName",
          "organisationId"
        ]
      },
      "EclipseNotificationType": {
        "type": "string",
        "enum": [
          "EMAIL",
          "PUSH",
          "SMS",
          "TEMPLATE"
        ]
      },
      "EclipseOrganisation": {
        "type": "object",
        "description": "A company, organisation or grouping of customers which can in turn own a wallet, have an address or have associated documents. Typically known as a Juristic but organisation can also include just a grouping of people like a family, club or association.",
        "properties": {
          "bankDetails": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Avp"
            }
          },
          "businessRegistrationDate": {
            "type": "string",
            "description": "Business registration date must be in form of yyyyMMdd",
            "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "businessType": {
            "$ref": "#/components/schemas/BusinessType",
            "description": "The type of the business. This will be supplementary to organisation type when selected type of business.",
            "type": "string"
          },
          "businessWebsite": {
            "type": "string",
            "pattern": "^http(s)?:\\/\\/.*\\..*$",
            "minLength": 1,
            "maxLength": 512
          },
          "categoryCode": {
            "type": "integer",
            "format": "int64",
            "description": "Four digit Category code for this organisation."
          },
          "companyNumber": {
            "type": "string",
            "description": "Legal company number of the organisation",
            "minLength": 5,
            "maxLength": 20
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "examples": [
              "2022-03-10T12:15:50-04:00"
            ],
            "description": "ISO 8601 date/time of when the record was first created"
          },
          "email": {
            "type": "string",
            "description": "Email address of the organisation",
            "pattern": "^[\\w\\.\\+-]+@([\\w-]+\\.)+[\\w-]{2,10}$"
          },
          "externalUniqueId": {
            "type": "string",
            "description": "A globally unique identifier set by the tenant for this organisation. Useful for correlating between the tenants systems and Eclipse"
          },
          "industrialClassification": {
            "type": "string",
            "minLength": 3,
            "maxLength": 50
          },
          "industrialSector": {
            "type": "string",
            "minLength": 3,
            "maxLength": 50
          },
          "lastModified": {
            "type": "string",
            "format": "date-time",
            "examples": [
              "2022-03-10T12:15:50-04:00"
            ],
            "description": "ISO 8601 date/time of when the record was last modified"
          },
          "merchantId": {
            "type": "string",
            "description": "Merchant Id used for some card payment types to the organisations wallet"
          },
          "name": {
            "type": "string",
            "description": "Name of the organisation",
            "minLength": 3,
            "maxLength": 50
          },
          "organisationId": {
            "type": "integer",
            "format": "int64",
            "description": "Unique system generated identifier for an organisation",
            "exclusiveMinimum": 0
          },
          "phone1": {
            "type": "string",
            "description": "Organisations primary phone number",
            "pattern": "^[0-9]{8,16}$"
          },
          "phone2": {
            "type": "string",
            "description": "Organisations secondary phone number",
            "minLength": 10,
            "maxLength": 20
          },
          "status": {
            "$ref": "#/components/schemas/EclipseOrganisationStatus"
          },
          "taxNumber": {
            "type": "string",
            "description": "Tax number of the organisation",
            "minLength": 3,
            "maxLength": 20
          },
          "tenantId": {
            "type": "integer",
            "format": "int64"
          },
          "tradingName": {
            "type": "string",
            "minLength": 3,
            "maxLength": 50
          },
          "type": {
            "$ref": "#/components/schemas/OrganisationType",
            "description": "The type of the organisation",
            "type": "string"
          },
          "vatNumber": {
            "type": "string",
            "description": "VAT number of organisation"
          },
          "version": {
            "type": "integer",
            "format": "int32",
            "description": "A number indicating the version of the record. Updates will only be accepted if the passed in version is the same as the current version on record. This is in order to prevent concurrent modifications by multiple users.",
            "minimum": 0
          }
        },
        "required": [
          "phone1",
          "version"
        ]
      },
      "EclipseOrganisationStatus": {
        "description": "Status of the eclipse organisation. ACTIVE:Organisation is active, INACTIVE:Organisation is in active, BARRED:Organisation is in barred",
        "type": "string",
        "enum": [
          "ACTIVE",
          "BARRED",
          "INACTIVE"
        ]
      },
      "EclipseTitle": {
        "type": "string",
        "enum": [
          "CHIEF",
          "DR",
          "MISS",
          "MR",
          "MRS",
          "MS",
          "SIR"
        ]
      },
      "ExceptionData": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "environment": {
            "type": "string"
          },
          "info": {
            "type": "object",
            "additionalProperties": {}
          },
          "severity": {
            "$ref": "#/components/schemas/ExceptionSeverity"
          },
          "spanId": {
            "type": "string"
          },
          "stackTrace": {
            "type": "string"
          },
          "traceId": {
            "type": "string"
          },
          "type": {
            "$ref": "#/components/schemas/ExceptionType"
          }
        }
      },
      "ExceptionSeverity": {
        "type": "string",
        "enum": [
          "CRITICAL",
          "HIGH",
          "INFO",
          "LOW",
          "MEDIUM"
        ]
      },
      "ExceptionType": {
        "type": "string",
        "enum": [
          "BUSINESS",
          "SYSTEM"
        ]
      },
      "Gender": {
        "description": "Gender. M:Male, F:Female, O:Other",
        "type": "string",
        "enum": [
          "F",
          "M",
          "O"
        ]
      },
      "MaritalStatus": {
        "description": "Maritial status of the customer. S:Single, M:Married, D:Divorced, W:Widowed",
        "type": "string",
        "enum": [
          "D",
          "M",
          "S",
          "W"
        ]
      },
      "NewEclipseCustomer": {
        "description": "A customer of a Tenant. A physical human being with a legal identity. Customers can be grouped into an organisation if needed. Customers can belong to multiple organisations. Customers link to an organisation is through the posiiton they hold in that organisation.",
        "type": "object",
        "properties": {
          "accountableInstitutionCif": {
            "type": "string"
          },
          "additionalIdentityNumber": {
            "type": "string",
            "description": "Additional identity number",
            "pattern": "^[A-Za-z0-9/]*$",
            "minLength": 5,
            "maxLength": 20
          },
          "asylumCountryOfIssuance": {
            "type": "string",
            "description": "ISO Alpha-2 country code for Issue of Asylum",
            "minLength": 2,
            "maxLength": 2
          },
          "asylumDateOfIssuance": {
            "type": "string",
            "description": "Mandatory If the asylum number is provided and must be in form of yyyyMMdd",
            "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "asylumPaperExpiry": {
            "type": "string",
            "description": "Mandatory If the asylum ref number is provided and must be in form of yyyyMMdd",
            "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "asylumRefNumber": {
            "type": "string",
            "description": "Asylum ref number",
            "pattern": "^[A-Za-z0-9]+(?:\\/[A-Za-z0-9]+)*$",
            "minLength": 5,
            "maxLength": 15
          },
          "birthCity": {
            "type": "string",
            "description": "Customer City of birth ",
            "minLength": 0,
            "maxLength": 20
          },
          "birthCountry": {
            "type": "string",
            "description": "Customer Country of birth. From 1st July 2022 it will only accept the ISO two character country code. for example if 'South Africa' has added as Passport place of issuance it will be replaced by 'ZA'.",
            "minLength": 0,
            "maxLength": 60
          },
          "communicationPreference": {
            "$ref": "#/components/schemas/EclipseNotificationType"
          },
          "countryOfResidence": {
            "type": "string",
            "description": "Customer's resident country"
          },
          "countryOfTaxation": {
            "type": "string",
            "description": "FATCA/CRS: ISO country code of taxation jurisdiction",
            "minLength": 0,
            "maxLength": 3
          },
          "dateOfBirth": {
            "type": "string",
            "description": "Customer Date of birth must be in form of yyyyMMdd",
            "pattern": "^(18|19|20)(\\d{2})(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "email": {
            "type": "string",
            "description": "Customers email address",
            "pattern": "^[\\w\\.\\+-]+@([\\w-]+\\.)+[\\w-]{2,10}$",
            "minLength": 10,
            "maxLength": 50
          },
          "externalUniqueId": {
            "type": "string",
            "description": "A globally unique identifier set by the tenant for this customer. Useful for correlating between the tenants systems and Eclipse",
            "minLength": 6,
            "maxLength": 100
          },
          "firstName": {
            "type": "string",
            "description": "Customer first/given name",
            "pattern": "^\\D*$",
            "minLength": 2,
            "maxLength": 50
          },
          "gender": {
            "$ref": "#/components/schemas/Gender",
            "description": "The gender of the customer",
            "type": "string"
          },
          "industry": {
            "type": "string",
            "description": "Industry customer belongs to"
          },
          "isForeignTaxResident": {
            "type": "boolean",
            "description": "FATCA/CRS: Whether the customer is a foreign tax resident"
          },
          "lastName": {
            "type": "string",
            "description": "Customers last/family name",
            "pattern": "^\\D*$",
            "minLength": 2,
            "maxLength": 50
          },
          "locale": {
            "type": "string",
            "description": "ISO 639-1 language code of the customer",
            "minLength": 2,
            "maxLength": 2
          },
          "maidenName": {
            "type": "string",
            "description": "Customers maiden name",
            "minLength": 2,
            "maxLength": 50
          },
          "maritalStatus": {
            "$ref": "#/components/schemas/MaritalStatus",
            "description": "Maritial status of the customer",
            "type": "string"
          },
          "middleName": {
            "type": "string",
            "description": "Customers middle name",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9\\s.\\-'&]*$",
            "minLength": 2,
            "maxLength": 50
          },
          "mobileNumberValidated": {
            "type": "boolean",
            "description": "Optional. Set only when the channel has already verified phone1 using their own solution. When true, Eclipse trusts it directly and sets mobileNumberValidated to true without an OTP check."
          },
          "monthlyIncome": {
            "type": "integer",
            "format": "int64",
            "description": "Customer's expected income per month"
          },
          "nationalIdentityCountryOfIssuance": {
            "type": "string",
            "description": "ISO Alpha-2 country code for Issue of National Identity",
            "minLength": 2,
            "maxLength": 2
          },
          "nationalIdentityDateOfIssuance": {
            "type": "string",
            "description": "Mandatory If the national identity number is provided and must be in form of yyyyMMdd",
            "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "nationalIdentityExpiry": {
            "type": "string",
            "description": "Mandatory If the national identity number is provided and must be in form of yyyyMMdd",
            "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "nationalIdentityNumber": {
            "type": "string",
            "description": "National identity number",
            "pattern": "^[A-Za-z0-9/-]*$",
            "minLength": 5,
            "maxLength": 20
          },
          "nationalIdentitySerialNumber": {
            "type": "string",
            "description": "national identity serial number of customer",
            "minLength": 0,
            "maxLength": 20
          },
          "nationality": {
            "type": "string",
            "description": "Nationality of Customer",
            "minLength": 0,
            "maxLength": 50
          },
          "nextMandatoryKycDate": {
            "type": "string",
            "format": "date-time",
            "examples": [
              "2022-03-10T12:15:50-04:00"
            ]
          },
          "nextOfKinInfo": {
            "type": "string",
            "description": "Next of kin info as a json",
            "minLength": 0,
            "maxLength": 500
          },
          "other": {
            "type": "string",
            "description": "",
            "minLength": 0,
            "maxLength": 5000
          },
          "passportCountry": {
            "type": "string",
            "description": "ISO Alpha-2 country code",
            "minLength": 2,
            "maxLength": 2
          },
          "passportDateOfIssuance": {
            "type": "string",
            "description": "Mandatory If the passport number is provided and must be in form of yyyyMMdd",
            "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "passportExpiry": {
            "type": "string",
            "description": "Mandatory If the passport number is provided and must be in form of yyyyMMdd",
            "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "passportNumber": {
            "type": "string",
            "description": "National identity number",
            "pattern": "^[A-Za-z0-9]*$",
            "minLength": 5,
            "maxLength": 20
          },
          "passportPlaceOfIssuance": {
            "type": "string",
            "description": "Mandatory If the passport number is provided.",
            "minLength": 2,
            "maxLength": 60
          },
          "permitExpiry": {
            "type": "string",
            "description": "Mandatory If the PERMIT is provided and must be in form of yyyyMMdd.",
            "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "permitNumber": {
            "type": "string",
            "description": "Permit number"
          },
          "phone1": {
            "type": "string",
            "description": "Customers primary phone number",
            "pattern": "^[0-9]{8,16}$"
          },
          "phone2": {
            "type": "string",
            "description": "Customers secondary phone number",
            "pattern": "^[0-9]{8,16}$"
          },
          "positions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NewEclipseCustomerPosition"
            },
            "description": "Optional list of Organisation positions to assign to the customer as part of creation, so the customer and its Organisation position(s) are created together in one atomic call. If a position fails to be created (e.g. an invalid organisationId, or a duplicate position for that Organisation), the entire call fails and no customer is created. This is the recommended way to link a new customer to an Organisation: a customer created without at least one entry here is not linked to any Organisation, and will not be found by Organisation-scoped position lookups (e.g. GET /organisations/{organisationId}/positions) until a position is added via the positions API. Equivalent to separately calling the positions API for each entry, but without the risk of the customer being created without its position if the second call is never made."
          },
          "profession": {
            "type": "string",
            "description": "Customer's profession"
          },
          "profileCompletionStatus": {
            "type": "integer",
            "format": "int32",
            "description": "Determines if the customer can update their own Profile, Adddress,Documents. This int is a bitmask. Least significant bit (bit 1) means the basic profile data like last name is complete and cannot be changed by the customer themselves. Bit 2 indicates Address data cannot be changed. Bit 3 means documents are complete. Bit 4 means attachments are complete. E.g. To disallow changing attachments, documents, and addresses only, this int would be set as 1110 = 14"
          },
          "purposeOfUse": {
            "type": "string",
            "description": "Purpose of business Relationship"
          },
          "riskRating": {
            "type": "string"
          },
          "schoolName": {
            "type": "string",
            "description": "School name of customer",
            "minLength": 0,
            "maxLength": 50
          },
          "sourceOfFunds": {
            "type": "string",
            "description": "Customer's source of fund"
          },
          "sourceOfWealth": {
            "type": "string"
          },
          "ssn": {
            "type": "string",
            "description": "FATCA/CRS: US Social Security Number",
            "minLength": 0,
            "maxLength": 50
          },
          "status": {
            "$ref": "#/components/schemas/EclipseCustomerStatus",
            "description": "Status of the customer. This is set/updated by the tenant and acts as a flag. It has no associated logic or implications within Eclipse itself",
            "type": "string"
          },
          "taxNumber": {
            "type": "string",
            "description": "Tax number of customer",
            "minLength": 0,
            "maxLength": 20
          },
          "temporaryIdentityExpiry": {
            "type": "string",
            "description": "Mandatory If the temporary Id is provided and must be in form of yyyyMMdd. User should enter temporaryIdentityExpiry = issue date + 2 months",
            "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
            "minLength": 8,
            "maxLength": 8
          },
          "title": {
            "$ref": "#/components/schemas/EclipseTitle",
            "description": "The title/salutation of the customer",
            "type": "string"
          },
          "userTypeId": {
            "type": "integer",
            "format": "int32"
          }
        },
        "required": [
          "externalUniqueId"
        ]
      },
      "NewEclipseCustomerPosition": {
        "type": "object",
        "description": "A position linking a customer to an Organisation. Used both to assign a position inline as part of customer creation (see NewEclipseCustomer.positions) and via the standalone positions API. E.g. HEAD, DIRECTOR, MANAGER, OWNER etc",
        "required": [
          "organisationId",
          "position"
        ],
        "properties": {
          "divisionId": {
            "type": "integer",
            "format": "int64",
            "description": "Optional. The id of the Division within the Organisation this position applies to, when the Organisation uses Divisions."
          },
          "organisationId": {
            "type": "integer",
            "format": "int64",
            "description": "The id of the Organisation the position is being assigned in."
          },
          "position": {
            "$ref": "#/components/schemas/OrganisationPosition",
            "description": "The position to assign the customer within the Organisation. See OrganisationPosition for the full list of valid values.",
            "type": "string"
          }
        }
      },
      "OrganisationPosition": {
        "description": "The position held by a customer within an Organisation.",
        "type": "string",
        "enum": [
          "DIRECTOR",
          "EMPLOYEE",
          "HEAD",
          "MANAGER",
          "MEMBER",
          "OWNER",
          "PARTNER",
          "PRIMARY_CONTACT"
        ]
      },
      "OrganisationType": {
        "description": "OrganisationType",
        "type": "string",
        "enum": [
          "BUSINESS",
          "CLUB",
          "FAMILY",
          "MERCHANT",
          "OTHER",
          "PERMISSION_GROUP",
          "RAP"
        ]
      },
      "StatusChangeReasonCode": {
        "type": "string",
        "enum": [
          "DUE_DILIGENCE",
          "EXCON",
          "FRAUD",
          "LEGAL",
          "NONE",
          "REGULATORY",
          "RISK"
        ]
      }
    },
    "securitySchemes": {
      "JWTBearerAuthorisation": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "info": {
    "description": "A RESTful API using JSON as the data transfer model, covering all tenant-facing functionality in the Eclipse payments platform.",
    "title": "Eclipse ReST API",
    "version": "3.0.0"
  },
  "tags": [
    {
      "name": "d) Customer Management",
      "description": "Operations on an individual customer profile including identity management, addresses, documents, wallets, cards, beneficiaries, and KYC ratification."
    }
  ],
  "paths": {
    "/eclipse-conductor/rest/v1/tenants/{tenantId}/customers": {
      "post": {
        "summary": "Register a new Customer",
        "description": "Registers a new customer profile under the tenant and returns the created customer. Optionally accepts a `positions` list to atomically assign the customer one or more Organisation positions as part of the same call — the recommended way to link a new customer to an Organisation without a separate call to the positions API.",
        "tags": [
          "d) Customer Management"
        ],
        "parameters": [
          {
            "name": "tenantId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NewEclipseCustomer"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EclipseCustomer"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ExceptionData"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "JWTBearerAuthorisation": []
          }
        ]
      }
    }
  }
}
```