EntityIDRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/citi/main/json-schema/citi-entity-id-request-schema.json",
  "title": "EntityIDRequest",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/citi-addonservices-api-openapi.yml#/components/schemas/Entity-Id-Request",
  "required": [
    "entity"
  ],
  "type": "object",
  "properties": {
    "entity_id": {
      "title": "EntityId",
      "description": "Entity ID that was assigned during the 'CREATE' action under POST endpoint. Mandatory input for PATCH endpoint",
      "type": "string",
      "maxLength": 20,
      "minLength": 20
    },
    "entity": {
      "$ref": "#/$defs/Entity"
    },
    "beneficial_owner": {
      "title": "BeneficialOwner",
      "description": "Parameters are applicable for both 'POST' and 'PATCH' endpoints. <br> <br> Up to 4 beneficial owner information can be given. <br> Maintain the beneficial owner details order as per their ownership with the entity. <br> <br> - Not applicable for sole trader (`entity.type`='S')",
      "type": "array",
      "minItems": 1,
      "maxItems": 4,
      "items": {
        "$ref": "#/$defs/Beneficial-Owner"
      }
    }
  },
  "$defs": {
    "Beneficial-Owner": {
      "title": "BeneficialOwner",
      "allOf": [
        {
          "$ref": "#/$defs/Contact-Name-BO"
        },
        {
          "type": "object"
        },
        {
          "required": [
            "date_of_birth",
            "address"
          ],
          "properties": {
            "date_of_birth": {
              "title": "date_of_birth",
              "type": "string",
              "minLength": 10,
              "maxLength": 10,
              "pattern": "^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$",
              "description": "Mandatory parameter under 'Beneficial Owner' object if the object is used. <br> Populates the date of birth date pertaining to the Beneficial owner of the entity. It is in fixed 10 digit format(YYYY-MM-DD) as per ISO format. <br> <br> - Non-Modifiable parameter under 'PATCH' endpoint."
            },
            "address": {
              "$ref": "#/$defs/Ncle-Address"
            }
          }
        }
      ]
    },
    "Contact-Name-BO": {
      "title": "Contact-Name-BO",
      "type": "object",
      "required": [
        "first_name",
        "last_name"
      ],
      "properties": {
        "first_name": {
          "title": "first_name",
          "type": "string",
          "minLength": 1,
          "maxLength": 105,
          "description": "First name of Beneficial Owner linked to the merchant. <br> <br> - Modifiable parameter under 'PATCH' endpoint."
        },
        "last_name": {
          "title": "last_name",
          "type": "string",
          "minLength": 1,
          "maxLength": 105,
          "description": "Last name of Beneficial Owner linked to the merchant. <br> <br> - Modifiable parameter under 'PATCH' endpoint."
        }
      }
    },
    "Contact-Name-Entity": {
      "title": "Contact-Name-Entity",
      "type": "object",
      "required": [
        "last_name"
      ],
      "properties": {
        "first_name": {
          "title": "first_name",
          "type": "string",
          "minLength": 1,
          "maxLength": 105,
          "description": "First name of entity linked to the merchant. <br> Further `entity.type` level applicability is mentioned below, <br> <br> - Conditionally mandatory for Sole Trader (`entity.type`='S') <br> - Not applicable for Company (`entity.type`='C'). <br> <br> - Modifiable parameter under 'PATCH' endpoint."
        },
        "last_name": {
          "title": "last_name",
          "type": "string",
          "minLength": 1,
          "maxLength": 105,
          "description": "Last name of entity linked to the merchant. <br> <br> - For Sole Trader (`entity.type`='S') - include the last name <br> - For Company (`entity.type`='C') - include the Legal Entity Name. <br> <br> - Modifiable parameter under 'PATCH' endpoint."
        }
      }
    },
    "Entity": {
      "title": "Entity",
      "description": "Mandatory object for both 'CREATE' (POST) and 'UPDATE' (PATCH) action values.",
      "allOf": [
        {
          "$ref": "#/$defs/Contact-Name-Entity"
        },
        {
          "type": "object"
        },
        {
          "required": [
            "country_of_operation",
            "address",
            "org_prvt_identification",
            "date_of_birth",
            "type"
          ],
          "properties": {
            "type": {
              "title": "type",
              "type": "string",
              "enum": [
                "C",
                "S"
              ],
              "description": "Mandatory parameter for POST endpoint. <br> Populate the entity type applicable for the entity / merchant. <br><br> C = COMPANY  <br><br> S = SOLE TRADER - enterprise owned and run by one person and in which there is no legal distinction between the owner and the business entity. <br> <br> - Non-Modifiable parameter under 'PATCH' endpoint."
            },
            "date_of_birth": {
              "title": "date_of_birth",
              "type": "string",
              "minLength": 10,
              "maxLength": 10,
              "pattern": "^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$",
              "description": "Mandatory parameter for POST endpoint. <br> Populates the date of birth or incorporation date pertaining to the entity that is being activated under this Entity. It is in fixed 10 digit format(YYYY-MM-DD) as per ISO format. <br> <br> - Non-Modifiable parameter under 'PATCH' endpoint."
            },
            "website": {
              "title": "website",
              "type": "string",
              "minLength": 0,
              "maxLength": 200,
              "description": "Populate the website of entity. <br> <br> - Modifiable parameter under 'PATCH' endpoint."
            },
            "store_name": {
              "title": "store_name",
              "type": "string",
              "minLength": 0,
              "maxLength": 105,
              "description": "Populate the store name of entity. <br> <br> - Modifiable parameter under 'PATCH' endpoint."
            },
            "business_purpose": {
              "title": "business_purpose",
              "type": "string",
              "minLength": 0,
              "maxLength": 105,
              "description": "Populate the business purpose applicable. <br> <br> - Modifiable parameter under 'PATCH' endpoint."
            },
            "acronym": {
              "title": "acronym",
              "type": "string",
              "minLength": 0,
              "maxLength": 105,
              "description": "Populate the acronym for the Entity. <br> <br> - Modifiable parameter under 'PATCH' endpoint."
            },
            "country_of_operation": {
              "title": "country_of_operation",
              "type": "string",
              "minLength": 2,
              "maxLength": 2,
              "pattern": "^[A-Z]{2}$",
              "description": "Enter the 'Country code' on which the entity is operated. <br> <br> - Non-Modifiable parameter under 'PATCH' endpoint."
            },
            "org_prvt_identification": {
              "$ref": "#/$defs/Organisation-Private-Identification"
            },
            "address": {
              "$ref": "#/$defs/Ncle-Address"
            }
          }
        }
      ]
    },
    "Ncle-Address": {
      "title": "Address",
      "type": "object",
      "required": [
        "street_name",
        "building_number",
        "postal_code",
        "town_name",
        "country_sub_division",
        "country"
      ],
      "description": "<b> Address object is mandatory if `entity` object is used. </b>",
      "properties": {
        "street_name": {
          "title": "street_name",
          "type": "string",
          "minLength": 1,
          "maxLength": 70,
          "description": "Address details of entity (or) Beneficial owner of entity. Mandatory parameter under `Address` object. <br> <br> - Modifiable parameter under 'PATCH' endpoint."
        },
        "building_number": {
          "title": "building_number",
          "type": "string",
          "minLength": 1,
          "maxLength": 16,
          "description": "Address details of entity (or) Beneficial owner of entity. <br> <br> - Modifiable parameter under 'PATCH' endpoint."
        },
        "postal_code": {
          "title": "postal_code",
          "type": "string",
          "minLength": 1,
          "maxLength": 16,
          "description": "Address details of entity (or) Beneficial owner of entity. Mandatory parameter under `Address` object. <br> <br> - Modifiable parameter under 'PATCH' endpoint."
        },
        "town_name": {
          "title": "town_name",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "Address details of entity (or) Beneficial owner of entity. Mandatory parameter under `Address` object. <br> <br> - Modifiable parameter under 'PATCH' endpoint."
        },
        "country_sub_division": {
          "title": "country_sub_division",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "Address details of Entity (or) Beneficial owner of entity. Mandatory parameter under `Address` object. <br> <br> - Modifiable parameter under 'PATCH' endpoint."
        },
        "country": {
          "title": "country",
          "type": "string",
          "minLength": 2,
          "maxLength": 2,
          "pattern": "^[A-Z]{2}$",
          "description": "Address details of Entity (or) Beneficial owner of Entity. Mandatory parameter under `Address` object. <br> <br> - Modifiable parameter under 'PATCH' endpoint."
        }
      }
    },
    "Organisation-Private-Identification": {
      "title": "OrganisationPrivateIdentification",
      "type": "object",
      "required": [
        "type",
        "id",
        "country_of_issuance"
      ],
      "description": "Non-Modifiable parameter under 'PATCH' endpoint.",
      "properties": {
        "type": {
          "title": "type",
          "type": "string",
          "enum": [
            "TAX_ID"
          ],
          "description": "Type of the identification that is provided below in this object. Type maximum length can be up to 200 characters. - 'TAX_ID' Tax Identification <br> <br> - Non-Modifiable parameter under 'PATCH' endpoint."
        },
        "id": {
          "title": "id",
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Identification pertaining to the entity. <br> <br> - Non-Modifiable parameter under 'PATCH' endpoint."
        },
        "country_of_issuance": {
          "title": "country_of_issuance",
          "type": "string",
          "minLength": 2,
          "maxLength": 2,
          "pattern": "^[A-Z]{2}$",
          "description": "Country code where the provided identification has been issued. <br> <br> - Non-Modifiable parameter under 'PATCH' endpoint."
        }
      }
    }
  }
}