{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/wordline/main/json-schema/wordline-api-response-entity-address-versions-schema.json",
  "title": "ApiResponseEntityAddressVersions",
  "description": "Retrieve address versions response entity",
  "x-generated": "2026-10-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/wordline-customer-address-api-openapi.yml#/components/schemas/ApiResponseEntityAddressVersions",
  "x-wl-api-response": true,
  "type": "object",
  "required": [
    "responseMetadata"
  ],
  "properties": {
    "responseMetadata": {
      "description": "Response metadata",
      "allOf": [
        {
          "$ref": "#/$defs/ResponseMetadata"
        }
      ]
    },
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Address"
      },
      "description": "Response data"
    }
  },
  "$defs": {
    "Address": {
      "type": "object",
      "required": [
        "addressLabel",
        "addressType"
      ],
      "properties": {
        "issuerId": {
          "type": "string",
          "description": "Issuer identifier (unique per platform)"
        },
        "addressIdentifier": {
          "description": "Unique identifier of the address. See the AddressIdentifier's datatype for a detail description",
          "allOf": [
            {
              "$ref": "#/$defs/AddressIdentifier"
            }
          ]
        },
        "addressVersionIdentifier": {
          "allOf": [
            {
              "$ref": "#/$defs/AddressVersionIdentifier"
            }
          ]
        },
        "addressLabel": {
          "type": "string",
          "description": "example: MAIN_POSTAL_ADDRESS Indicate the class of the address amongst a list of possible values such as MAIN_POSTAL_ADDRESS, SECOND_POSTAL_ADDRESS, HOME_PHONE_NUMBER, PRIVATE_MOBILE_PHONE, PERSONAL_EMAIL. This list of values is shared between WL and the issuer during issuer configuration. \n Every label corresponds to a unique type of address. A customer (person) has at least one MAIN_POSTAL_ADDRESS (mandatory) and a company has at least one HEAD_OFFICE."
        },
        "addressType": {
          "type": "string",
          "description": "The type of an address is POSTAL_MAIL, PHONE or E_MAIL",
          "enum": [
            "PHONE",
            "POSTAL_MAIL",
            "E_MAIL"
          ]
        },
        "postalAddress": {
          "description": "Customer Postal Address. This field is mandatory only if AddressType is POSTAL_MAIL. \n Depending on countries, the address format (mainly for line1, line 2, line3, line4 and line5) can have specific conditions such as length restriction. The customer should contact WL to check the address format and have more information.",
          "allOf": [
            {
              "$ref": "#/$defs/MailAddress"
            }
          ]
        },
        "emailAddress": {
          "description": "Customer Email. This field is mandatory only if AddressType is E_MAIL. See the EmailAddress' datatype for the detail list of the attributes.",
          "allOf": [
            {
              "$ref": "#/$defs/EmailAddress"
            }
          ]
        },
        "phone": {
          "description": "Customer Phone details. This field is mandatory only if AddressType is PHONE. See the PhoneNumber's datatype for the detail list of the attributes.",
          "allOf": [
            {
              "$ref": "#/$defs/PhoneNumber"
            }
          ]
        },
        "addressUsages": {
          "type": "array",
          "description": "List of the usages linked to the address if any exists. See the AddressUsage's datatype for the detail list of the attributes (optional)\n_Embedded property, only filled when available for the endpoint and explicitly requested in the 'embed' query parameter._",
          "items": {
            "$ref": "#/$defs/AddressUsage"
          }
        },
        "status": {
          "type": "string",
          "description": "Status of the address (ACTIVE or INACTIVE). If value is not provided, by default 'ACTIVE'"
        },
        "statusDate": {
          "type": "string",
          "description": "If the address is INACTIVE, the date corresponds to the inactivation date.\nIf the address is ACTIVE, the date corresponds to the last activation date.",
          "format": "date-time"
        },
        "startDate": {
          "type": "string",
          "description": "Date when the address starts to be active",
          "format": "date-time"
        },
        "endDate": {
          "type": "string",
          "description": "This attribute represents :\n• in case of a permanent address : the last date the address has been active. This information is computed based on the next future address start date if any exists else this attribute is empty.\n• in case of a temporary address : the end date where this address is active. This end date is mandatory when a temporary address is created.",
          "format": "date-time"
        },
        "invalid": {
          "type": "boolean",
          "description": "Indicates if an address is invalid (by default false).\nThis feature is currently only accurate for the mail address and apply only on the current permanent address.\nIn case a postal address is invalid, this address cannot be used anymore for letters, cards, pin mailers, statement sending. \nThis feature is active only depending on an issuer configuration. ",
          "default": false
        },
        "temporary": {
          "type": "boolean",
          "description": "indicates if the address is a temporary one (by default 'false').\nIn case of a temporary address, the end date is mandatory.",
          "default": false
        }
      },
      "title": "Address"
    },
    "AddressIdentifier": {
      "type": "object",
      "properties": {
        "addressReference": {
          "type": "string",
          "description": "Unique internal identifier computed with a specific algorithm (mandatory)"
        },
        "issuerAddressExternalReference": {
          "type": "string",
          "description": "Unique external identifier provided by the issuer (optional)"
        }
      },
      "title": "AddressIdentifier"
    },
    "AddressUsage": {
      "type": "object",
      "required": [
        "addressUsageName",
        "serviceCode"
      ],
      "properties": {
        "addressUsageName": {
          "type": "string",
          "description": "The business process for which the address usage is defined such as CARD_DELIVERY, PIN_MAILER_DELIVERY, STATEMENT_DELIVERY."
        },
        "entityReference": {
          "type": "string",
          "description": "This corresponds to the application domain of the address. It can be eg a card contract reference, card account reference. It is an optional field.\nIt enables to have the same usage address for the same customer applied to different addresses (one cardholder with 2 card contracts: card delivery address usage is assigned to main postal address for contract A and card delivery address usage is also assigned to office postal address for contract B."
        },
        "serviceCode": {
          "type": "string",
          "description": "The Service for which the address usage is defined : CARD_SERVICE, ACCOUNT_SERVICE, …"
        }
      },
      "title": "AddressUsage"
    },
    "AddressVersionIdentifier": {
      "type": "object",
      "properties": {
        "addressVersionReference": {
          "type": "string",
          "description": "Identifies the version of the address\nA new version of the address is created when a change is done on the address."
        }
      },
      "title": "AddressVersionIdentifier"
    },
    "EmailAddress": {
      "type": "object",
      "required": [
        "email"
      ],
      "properties": {
        "email": {
          "type": "string",
          "description": "Email address of the Customer (mandatory). The email address should have the following format: aaa@bbb.ccc\naaa, bbb, ccc are character string."
        }
      },
      "title": "EmailAddress"
    },
    "Links": {
      "type": "object",
      "required": [
        "self"
      ],
      "properties": {
        "self": {
          "type": "string",
          "description": "Service method URL"
        },
        "next": {
          "type": "string",
          "description": "URL pagination query parameter next page"
        }
      },
      "title": "Links"
    },
    "MailAddress": {
      "type": "object",
      "required": [
        "country"
      ],
      "properties": {
        "typeCode": {
          "type": "string",
          "description": "Deprecated field"
        },
        "line1": {
          "type": "string",
          "description": "Address line 1 (conditional). Free text. A specific issuer algorithm can be activated to e.g. build the line, apply controls (e.g. length restriction)."
        },
        "line2": {
          "type": "string",
          "description": "Address line 2 (optional). Free text. A specific issuer algorithm can be activated to e.g. build the line, apply controls (e.g. length restriction)."
        },
        "line3": {
          "type": "string",
          "description": "Address line 3 (optional). Free text. A specific issuer algorithm can be activated to e.g. build the line, apply controls (e.g. length restriction)."
        },
        "line4": {
          "type": "string",
          "description": "Address line 4 (optional). Free text. A specific issuer algorithm can be activated to e.g. build the line, apply controls (e.g. length restriction)."
        },
        "line5": {
          "type": "string",
          "description": "Address line 5 (optional). Free text. A specific issuer algorithm can be activated to e.g. build the line, apply controls (e.g. length restriction)."
        },
        "buildingNumber": {
          "type": "string",
          "description": "Building number of the address (optional)"
        },
        "boxNumber": {
          "type": "string",
          "description": "Box number of the address (optional)"
        },
        "streetName": {
          "type": "string",
          "description": "Street name of the address (optional)"
        },
        "postCode": {
          "type": "string",
          "description": "Zip Code of the address (optional)"
        },
        "townName": {
          "type": "string",
          "description": "City corresponding to the address "
        },
        "countrySubdivision": {
          "type": "string",
          "description": "Subdivision of the country (optional)"
        },
        "country": {
          "type": "string",
          "description": "Code of the country (mandatory). Free text. The value can be subject to a validation process if a specific rule has been configured at issuer level. The value can be optional if a specific rule has been configured."
        },
        "countryName": {
          "type": "string",
          "description": "Country Name of the address. Free text"
        },
        "courtesyTitle": {
          "type": "string",
          "description": "Courtesy title of the address. Free text"
        }
      },
      "title": "MailAddress"
    },
    "PhoneNumber": {
      "type": "object",
      "required": [
        "localPhoneNumber"
      ],
      "properties": {
        "countryCode": {
          "type": "string",
          "description": "Country dialing code (optional). Free text. It is recommended to provide a region dialing code (e.g. +33, +49)."
        },
        "localPhoneNumber": {
          "type": "string",
          "description": "Free text (mandatory). It’s recommended to provide an international phone number in accordance with the value provided in the country code.\nEx : \n- country code = ‘+’33’ and localPhoneNumber = ‘0622334455’ \n- country code = empty and localPhoneNumber = ‘+33622334455’\nThe value can be subject to a validation process if a specific rule has been configured at issuer level."
        },
        "internationalPhoneNumber": {
          "type": "string",
          "description": "Free text (mandatory). It’s recommended to provide an international phone number in accordance with the value provided in the country code.\nEx : \n- country code = ‘+’33’ and localPhoneNumber = ‘0622334455’ \n- country code = empty and localPhoneNumber = ‘+33622334455’\nThe value can be subject to a validation process if a specific rule has been configured at issuer level."
        }
      },
      "title": "PhoneNumber"
    },
    "ResponseMetadata": {
      "type": "object",
      "required": [
        "correlationId",
        "responseDateTime",
        "statusCode",
        "statusMessage"
      ],
      "properties": {
        "correlationId": {
          "type": "string",
          "description": "Correlation Identifier"
        },
        "links": {
          "description": "Metadata Links",
          "allOf": [
            {
              "$ref": "#/$defs/Links"
            }
          ]
        },
        "statusMessage": {
          "type": "string",
          "description": "Executed REST API status message"
        },
        "statusCode": {
          "type": "integer",
          "format": "int32",
          "description": "HTTP status code"
        },
        "responseDateTime": {
          "type": "string",
          "description": "Timestamp when response date was generated"
        },
        "timeTakenMs": {
          "type": "integer",
          "format": "int64",
          "description": "Wall clock time required from service to generate the response"
        }
      },
      "title": "ResponseMetadata"
    }
  }
}