Address

The Address Service allows you to create address configurations and capture end-user address information.

With the Address Config endpoint, you can define country-specific formats to fetch the address information from your end-users. Address configurations are defined for the Tenant, and you can only define one address configuration for each country per Tenant.

The configurations include setting up different labels for different address attributes, defining required attributes and validations, and specifying the address template.

After you set up the configurations, use the Address Service Create endpoint to create and store the addresses. Apps that have permission to access the addresses can call the xxxx endpoint to retrieve them.

The following topics describe the different components of the Address Service:

• Address Attributes
• Address Attribute Configurations
• Address Creation and data storage

Address Attributes

The address attributes are data fields such as City, Postal Code, Apartment number, etc. that define the geographical location.

To designate these attributes as required or optional, use the Address Config endpoint. If you don’t want a specific attribute to be included in an address template, don’t include it in the address creation request body.

An Address has the following attributes:

Address Attributes Configuration

An Address Attribute Configuration is comprised of the following components:

• Address label: Display sequence
• Attribute label: Customization
• Configure required attributes
• Attribute validations

📘

NOTE

You can configure address labels and their display sequence at the per tenant level per country.

The attribute configuration request body defined in the succeeding topics has the following required members:

Address label: Display sequence

You can use the address-config endpoint to define the sequence of address labels on an address template. The order of the attributes in the input and display array of the request body defines the attribute’s position on the template.

When you use the GET Address endpoint to fetch the created address, it is displayed in the sequence you define in the display array.

The following example request body shows how to use Create Address Config endpoint to define the template with input and display arrays:

{
   "config": {
       "prefix": [
           "Prefix",
           false,
           "/^[a-zA-Z]+$/"
       ],
       "firstName": [
           "First Name",
           false,
           "/^[a-zA-Z]+$/"
       ],
       "lastName": [
           "Last Name",
           false,
           "/^[a-zA-Z]+$/"
       ],      
       "addressLine1": [
           "House number",
           false,
           "/^[a-zA-Z]+$/"
       ],
       "city": [
           "City",
           false,
           "/^[a-zA-Z]+$/"
       ],
       "state": [
           "State",
           false,
           "/^[a-zA-Z]+$/"
       ],
       "zipCode": [
           "Postal Code",
           false,
           "/^[0-9]+$/"
        ],
       "template": {
           "input": "{{addressLine1}}{{N}}{{state}}{{city}}{{N}}{{zipCode}}{{N}}{{country}}",
           "display": "{{addressLine1}}{{N}}{{addressLine2}}{{N}}{{city}}{{state}}{{N}}{{zipCode}}{{N}}{{country}}"
       } } }

Attribute label: Customization

Using the address-config API, you can customize the attribute names/labels. For example, you might want to call 'pincode' as 'zip code' or 'state' as 'province'.

The following example request body shows how you can use Create Address Config endpoint to reconfigure "state" as "province":

"state": [
           "Province",
           false,
           "/^[a-zA-Z]+$/"
       ],

Configure required attributes

You can mark certain address fields as required on the address template. The country standards that you follow might require fields such as zip code to be submitted to mark the address as complete or your business requirements mandate that certain inputs are required.

To set the zipCode attribute as a required field, use the address-config endpoint to set the mandatoryFlag to true.

The following example request body shows how you can set the zip code as required using the Create Address Config endpoint:

"zipCode": [
           "Postal Code",
           true,
           "/^[0-9]+$/"
        ],

The following example request body shows how you can set the zip code as optional using the Create Address Config endpoint:

"zipCode": [
           "Postal Code",
           false,
           "/^[0-9]+$/"
        ],

Attribute validations

You can define validation rules for your attributes. For example, the firstName attribute value must match 'a-z' or 'A-Z' with characters between 2-16. If the value doesn’t validate the defined rules, the end user will get an error message. Similarly, you can define the following validation rules for the attributes:

• The value must be numeric, alphabetic, or alphanumeric.
• Maximum and minimum characters allowed.
• Special characters are allowed.

Using the address-config API, you can set up validations for any defined attribute using regex.

The following sample payload shows how you can define zip code validations using the Create Address Config endpoint. Here, the zip code will only be validated if it contains only numerics and characters equal to or less than 9:

"zipCode": [
           "Postal Code",
           false,
           "/^[0-9]+$/"
       ],

Address Creation and Data Storage

When the address attribute configurations are in place, you can use the create address API to capture address information from end-users. The information that is captured by this endpoint will be validated against the defined configurations.

After successful validation, the captured information is stored in the database, returning an address ID that can be used to fetch the captured data.

The following example request body shows how you can create an address using Create Address endpoint:

{
   "properties": {
       "prefix": "Mr.",
       "firstName": "John", 
       "lastName": "Doe",
       "addressLine1":"407",
       "addressLine2":"Clair Street",
       "addressLine3":"Oak Way",
       "city":"Southfield",
       "state":"Michigan",
       "zipCode":"48075",
       "landmark":"Winding Way Tower"
   }
}

The created address can be fetched using the Get Address endpoint.