Producing Clarity’s Object APIs

Liferay simplifies API creation with automatically generated APIs for objects. Clarity's distributor management app requires integration with a third-party partner’s APIs for Know-Your-Customer (KYC) reporting. Upon successful validation of a business entity, the third party service sends a PATCH request with the following sample payload:

{
  "businessLegalName": "Iris Optical",
  "businessType":"S Corporation",
  "submittedBusinessEIN":"64-3428951",  
  "validatedBusinessEIN":"64-3428951",
  "customerId": "cus_0YV7DDSDD1C8DA64KHH2W33CPF",
  "verificationStatus": "verified",
  "creditScore:": 79,
  "creditRiskLevel": "Low to Medium"
}

With this payload documentation, Clarity's developers designed a Liferay Object aligning with the required KYC structure to leverage the produced APIs.

In these exercises, you’ll learn how to create APIs through Liferay Objects and leverage those APIs to interact with incoming webhook calls.

Exercise: Producing Clarity’s Distributor Validation APIs

Here, you’ll produce distributor validation APIs by creating an object aligning with Clarity’s KYC partner’s payloads.

1. Sign in as the Clarity Admin user.

   • Username: admin@clarityvisionsolutions.com

   • Password: learn

2. Open the Global Menu ([INSERT ICON]), go to the Control Panel tab, and click Objects.

3. Click on the Distributor Management folder and select View in Model Builder.

4. Click Create New Object.

5. Enter these details

   Field	Value
   Label	Distributor Validation
   Plural Name	Distributor Validations
   Object Name	DistributorValidation

6. From the Model Builder UI, select the Distributor Validation object.

7. Click Actions () and select Edit ERC.
   

8. Enter D4B8_DISTRIBUTOR_VALIDATION and click Save.

9. In the right side panel, configure these settings:

   Field	Value
   Scope	Company
   Panel Link	Applications > Content
   Show Widget in Page Builder	No
   Enable Comments in Page Builder	Yes
   Enable Indexed Search	No

   
   

   Now that you’ve created and configured the distributor validation object, you’ll create fields conforming to the third-party’s PATCH request structure

10. For the Distributor Validation object, click Add Field or Relationship, and select Add Field.

11. Enter these values and click Save.

    Field	Value
    Label	Business Legal Name
    Field Name	businessLegalName
    Type	Text
    Enable Entry Translation	No
    Mandatory	No
    Accept Unique Values Only	No

12. Click Add Field or Relationship, and select Add Field.

13. Enter these values and click Save.

    Field	Value
    Label	Validated Tax ID
    Field Name	validatedBusinessEIN
    Type	Text
    Enable Entry Translation	No
    Mandatory	No
    Accept Unique Values Only	No

    
    This esures the headless API schema can ingest validatedBusinessEIN data sent by the third party service, while the field’s label remains consistent with Liferay’s applications UI and broad support of a variety of different tax id formats.

    It's a best practice to finalize fields and configurations before publishing objects. To expedite these exercises, you'll automate populating the remaining fields in a later step.

14. From the Model Builder UI, click Publish.

15. Check Distributor Validation and click Publish Objects.

16. Navigate to the API Explorer at http://localhost:8080/o/api

17. In the upper right, select REST Applications > c/distributorvalidations
    
    This displays the list of APIs generated when publishing the object, including its batch endpoints.

18. Scroll to the bottom of the page and expand the DistributorValidation schema to verify that the businessLegalName and validatedBusinessEIN fields are represented.
    

19. Open a terminal and navigate to the /client-extensions/distributor-validator-batch folder in your course workspace.

20. Run this command to build and deploy the batch client extension:

    blade gw clean deploy

    Copy

    This finishes configuring the object definition, defines its relationships, and populates initial data.

21. Verify it deploys successfully.

    INFO [fileinstall-directory-watcher][BundleStartStopLogger:68] STARTED distributorvalidatorbatch_7.4.13 [1468]

    Copy

22. In your Liferay instance, open the Global Menu ([INSERT ICON]), go to the Control Panel tab, and click Objects.

23. Click on the Distributor Management folder and select Distributor Application.

24. Within the Relationships tab, verify that the Application to Validations one to many relationship (one Distributor Application to many Distributor Validations) was created.

25. Navigate back to the Distributor Management folder and select Distributor Validation.

26. Within the Fields tab, verify that the following fields were created:

    • Business Type

    • Verification Status

    • Credit Score

    • Credit Risk Level

27. Navigate to the API Explorer at http://localhost:8080/o/api

28. In the upper right, select REST Applications > c/distributorapplications

29. Expand the getDistributorApplicationApplicationToValidationsDistributorValidationPage endpoint.
    

30. Enter 63247 within the distributorApplicationId field.

31. Click Execute.
    ​This returns information about existing distributor validations tied to an application for the applicant ID of 63247, including verification statuses, ERCs, and other related fields.

Great! You’ve set up Clarity’s Distributor Validation object to leverage the third-party PATCH request’s payload and reviewed the object’s automatically generated APIs.

Exercise: Updating Clarity’s Application Layout

Clarity’s Distributor Application object has a custom object layout defined, but it does not yet include the newly created relationship. Here, you’ll modify this layout to include distributor validations.

1. Open the Global Menu (), go to the Control Panel tab, and click Objects.

2. Click on the Distributor Management folder and select Distributor Application.

3. On the Layouts tab, select Basic Layout.

4. On the Layout tab, select Add Tab.
   

5. Enter these values and click Save.

   Field	Value
   Label	Validations
   Type	Relationships
   Relationship	Application to Validations

   
   

Great! You can now view and edit Distributor Validation records while viewing their corresponding Distributor Application.

Exercise: Simulating Clarity’s Application Validations

With the Distributor Validation APIs populated, the system is ready to handle incoming validations. For each request, Clarity sends data to the third-party solution in the following format:

{
"businessName": "Iris Optical",
"businessTaxIDNumber": "43-2453958",
"businessPhoneNumber": "(414) 787-6902",
"businessAddress" : {
    "city": "Chicago",
    "countryCode": "US",
    "name": "EyeSpy Optical Corporate",
    "phoneNumber": "(773) 734-9834",
    "regionCode": "IL",
    "street1": "123 Main St.",
    "street2": "",
    "street3": "",
    "zip": "60640"
},
"callbackURL", "https://clarityvisionsolutions.com/o/c/distributorverifications/"
}

When received, the third party system replies with a response similar to the following:

{
    "requestType": "Business Validation",
    "executeStatus": "submitted",
    "trace": "j8p8he2a-e7a4-4919-b003-957b39b14f65"
    "status": "submitted",
    "startTime": "2025-03-05T22:18:10Z"
}

As submission validations take an indeterminate amount of time, the third party assigns a “trace” number for each submission. Clarity sets this trace as the ERC of the submitted validation’s object entry, which associates incoming API calls from the third party with the appropriate distributor information.

In this exercise, you’ll simulate incoming PATCH requests from the third party service to the callbackURL from the original request.

1. Navigate to the API Explorer at http://localhost:8080/o/api

2. In the upper right, select REST Applications > c/distributorvalidations

3. Expand the patchByExternalReferenceCode endpoint.
   

4. Set j8p8he2a-e7a4-4919-b003-957b39b14f65 for the externalReferenceCode parameter.

5. Remove the existing sample content from the Request body field.
   

6. Copy and paste the following JSON payload into the Request body field.

7. Click Execute.

8. Validate that a 200 response code and request URL are displayed under Responses.
   
   For non-simulated distributor validations, API calls with a similar JSON payload will be submitted directly to Clarity. This is made using request URLs with the same structure displayed on this page with the appropriate ERC for the submitted validation.

9. Expand the getByExternalReferenceCode endpoint.

10. Set j8p8he2a-e7a4-4919-b003-957b39b14f65 for the externalReferenceCode parameter.

11. Review the server response contents to verify that the payload information from step 6 is now reflected within the sample user’s distributor validation.
    

Conclusion

Congratulations! You’ve created no-code APIs through Clarity’s Distributor Validations object and explored receiving webhook responses from third parties using its mapped field values and associated APIs.

Next, you’ll learn about producing custom APIs with fine-grained control over endpoints and business logic.