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:
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:
The title of the person’s name.
The first name of the person to which the address belongs.
The middle name of the person.
The last name of the person.
Address line 1.
Address line 2.
Address line 3.
Address line 4.
The city of the address.
The state of the address.
The postal code of the address.
The country of the address.
The landmark of the address. A landmark is a known feature (could be a shop, mall, company, etc.) around the area that can help you identify the address easily.
An Address Attribute Configuration is comprised of the following components:
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:
Name of the attribute.
Configured label of the attribute.
Specifies whether the attribute is required or optional. The default value is false (optional).
Defines regular expression to use to validate the attribute.
The input and display arrays defining the sequence of attributes in a template.
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:
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":
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:
The following example request body shows how you can set the zip code as optional using the Create Address Config endpoint:
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:
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:
The created address can be fetched using the Get Address endpoint.