CreateAddressRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/wordline/main/json-schema/wordline-create-address-request-schema.json",
  "title": "CreateAddressRequest",
  "x-generated": "2026-10-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/wordline-company-address-api-openapi.yml#/components/schemas/CreateAddressRequest",
  "type": "object",
  "required": [
    "addressLabel",
    "addressType"
  ],
  "properties": {
    "issuerAddressExternalReference": {
      "type": "string",
      "description": "Unique external identifier provided by the issuer"
    },
    "addressLabel": {
      "type": "string",
      "description": "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.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.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/CreateAddressRequestMailAddress"
        }
      ]
    },
    "emailAddress": {
      "description": "Customer Email. This field is mandatory only if AddressType is E_MAIL.",
      "allOf": [
        {
          "$ref": "#/$defs/EmailAddress"
        }
      ]
    },
    "phone": {
      "description": "Customer Phone details. This field is mandatory only if AddressType is PHONE.",
      "allOf": [
        {
          "$ref": "#/$defs/CreateAddressRequestPhoneNumber"
        }
      ]
    },
    "addressUsages": {
      "type": "array",
      "description": "List of the usages linked to the address if any exists",
      "items": {
        "$ref": "#/$defs/AddressUsage"
      }
    },
    "startDate": {
      "type": "string",
      "description": "If the date is not provided, the current date and time of the user’s request is used.\nIf the provided date corresponds to the current date, the provided time is ignored and replaced by the current time of the system.\nIf the provided date is in the future (at least current date +1), provided date and time are used only if the LABEL of the address is already existing for the customer. In case the time is not provided, the time is set up to the start of the day (e.g. ‘T00:00:00’)\nIn all cases, if the address is created for the first time for a given LABEL, both date and time of the system are used and the address is immediately active. \nFor generic definition, refer to Address.startDate.",
      "format": "date-time"
    },
    "endDate": {
      "type": "string",
      "description": "This date is conditional to the kind of address :\n- if the address is a permanent one (temporary flag = false or empty), the field must be empty\n- if the address is a temporary one (temporary flag = true), the field must be filled with the date corresponding to the end date of the active period of the temporary address",
      "format": "date-time"
    },
    "temporary": {
      "type": "boolean",
      "default": false,
      "description": "The flag indicates if the address is permanent (by default, false) or temporary (flag = true)",
      "format": "date-time"
    }
  },
  "$defs": {
    "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"
    },
    "CreateAddressRequestMailAddress": {
      "type": "object",
      "required": [
        "country"
      ],
      "properties": {
        "typeCode": {
          "type": "string",
          "description": "DEPRECATED"
        },
        "courtesyTitle": {
          "type": "string",
          "description": "Courtesy title of the address. Free text"
        },
        "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 (conditional). 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 (conditional). 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 (conditional). 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 (conditional). 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."
        }
      },
      "title": "CreateAddressRequest.MailAddress"
    },
    "CreateAddressRequestPhoneNumber": {
      "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 Ex : - country code = ‘+’33’ and localPhoneNumber = ‘0622334455’ - country code = empty and localPhoneNumber = ‘+33622334455’             The value can be subject to a validation process if a specific rule has been configured at issuer level."
        }
      },
      "title": "CreateAddressRequest.PhoneNumber"
    },
    "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"
    }
  }
}