Producing Clarity’s Object APIs

Liferay automatically generates APIs for custom objects. Clarity's distributor management app requires integration with a third-party partner’s APIs for Know-Your-Customer (KYC) reporting. Upon successful verification of business entities, the third party service sends PATCH requests with a consistent payload structure. To leverage this data, Clarity's developers have designed a Liferay object that mirrors the third-party's payload so they can leverage the object’s APIs.

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

Exercise: Adding a Distributor Verification Object Definition

Here, you’ll create an object that aligns with the payload used by Clarity’s KYC partner.

1. Sign in as the Clarity Admin user.

   • Username: admin@clarityvisionsolutions.com
   • Password: learn

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

   NOTE
   If the Application Evaluation object is in the default folder, manually move it to the Distributor Management folder before proceeding.

3. Go to the Distributor Management folder and select View in Model Builder.

4. Click Create New Object.

5. Enter these details:

   Field	Value
   Label	Distributor KYC Verification
   Plural Name	Distributor KYC Verifications
   Object Name	DistributorKYCVerification

6. From the Model Builder UI, select the Distributor KYC Verification object.

7. Click Actions () and select Edit ERC.
   

8. Enter D4B8_DISTRIBUTOR_KYC_VERIFICATION 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 Categorization of Object entries	Yes
   Enable Comments in Page Builder	Yes
   Enable Indexed Search	No

   
   

Now that you’ve created and configured the distributor verification object, you can create fields that correspond to the third-party’s PATCH request structure.

Exercise: Adding Fields to the Object

Here you’ll add three text fields to the Distributor KYC Verification object as the Clarity Admin user.

1. For the Distributor KYC Verification object, click Add Field or Relationship, and select Add Field.

2. Enter these values and click Save.

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

3. Repeat the above steps to add two more fields:

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

   
   The submittedBusinessEIN field stores the data Clarity wants to validate using their third-party service, while validatedBusinessEIN receives and stores the validated tax ID number from the service. Field labels are user-friendly values that appear in the Liferay UI.

   NOTE
   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.

4. Click the Distributor KYC Verification object’s title to begin editing it.

5. In the right side panel, configure this setting:

   Field	Value
   Entry Title Field	Business Name

   
   By default, object definitions use the ID field for identifying entries in the Liferay UI. Selecting Business Name ensures the entry identifier is more user-friendly.

6. From the Model Builder UI, click Publish.

7. Check Distributor KYC Verification and click Publish Objects.
   During this process, Liferay automatically generates dedicated APIs, which include the object’s custom fields and relationships.

Great! You’ve added three custom fields to the Distributor KYC Verification object and generated its APIs. Next, you’ll finish setting up the object definition using a batch client extension.

Exercise: Completing the KYC Verification Object Setup

Here, you’ll use a batch client extension to finish setting up the Distributor KYC Verification object by adding a relationship, creating additional fields, and populating it with test data.

1. Open a terminal window and navigate to the client-extensions/distributor-verifier-batch/ folder in your course workspace.

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

   blade gw clean deploy

   This finishes setting up the object definition (e.g., fields, relationship, etc.) and populates test data.

3. Verify it deploys successfully:

   2025-05-16 14:15:53.715 INFO [fileinstall-directory-watcher][BundleStartStopLogger:68] STARTED distributorverifierbatch_7.4.13 [1468]

4. In your Liferay instance, open the Global Menu (), go to the Control Panel tab, and click Objects.

5. Go to the Distributor Management folder and click View in Model Builder.

   NOTE
   If the Distributor KYC Verification object is located in the default folder, manually move it to the Distributor Management folder before proceeding.

6. Verify the Application to KYC relationship connects the Distributor Application object to the Distributor KYC Verification objects.

   NOTE
   Adding this relationship automatically generated GET, PUT, and DELETE applicationToKYC endpoints within the Distributor Application’s object APIs.
   
   

7. Click Show All Fields for the Distributor KYC Verification object and verify these fields appear:

   • KYC Status
   • Business Address
   • Business Type
   • KYC Verification State
   • KYC Response
   NOTE
   If the relationship or fields do not appear, ensure both objects have the correct ERCs and redeploy the client extension.

   • Distributor Application ERC: D4B8_DISTRIBUTOR_APPLICATION
   • Distributor KYC Verification ERC: D4B8_DISTRIBUTOR_KYC_VERIFICATION

8. Open the Global Menu (), go to the Applications tab, and click Distributor Applications.

9. Verify the Distributor Application object includes new test entries.
   

Great! You’ve successfully established a one-to-many relationship between Application and KYC objects. Next, you’ll use this relationship to retrieve relevant distributor verification details tied to each application.

Exercise: Retrieving Existing Distributor Verification Data

Here, you'll use the Application to KYC one-to-many relationship endpoint to retrieve existing distributor verification records tied to an application.

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

2. Click the REST Applications drop-down menu and select c/distributorkycverifications.
   
   
   This displays the custom object’s REST APIs, which include batch endpoints.

3. Scroll to the bottom of the page and expand the DistributorKYCVerification schema to view its fields.
   
   
   Notice that it includes the businessName, submittedBusinessEIN and validatedBusinessEIN fields.

4. Open the Global Menu (), go to the Applications tab, and click Distributor Applications.

5. Copy the ID of Robert Green’s application for use in a future step.
   

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

7. Click the REST Applications drop-down menu and select c/distributorapplications.

8. Expand the getDistributorApplicationApplicationToKYCDistributorKYCVerificationPage endpoint.

9. Enter the previously copied entry ID into the distributorApplicationId field.

10. Click Execute.
    This returns information about existing distributor verifications related to Robert’s application, including verification statuses, ERCs, and other related fields.

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

Exercise: Simulating Clarity’s Application Verifications

With the Distributor KYC Verification object completed, the system is ready to handle incoming verifications. For each request, Clarity sends data to the third-party solution in this format:

{
  "businessName": "Neu Vue Optical",
  "businessPhoneNumber": "904-432-4355",
  "submittedBusinessEIN": "98-3423419",
  "externalReferenceCode": "APPLICATION_NEU_VEU",
  "callbackURL": "https://clarityvisionsolutions.com/o/c/distributorkycverifications/by-external-reference-code/"
}

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

{
    "requestType": "Business KYC Verification",
    "executeStatus": "submitted",
    "trace": "eced9c29-7e9a-465b-a010-9bce57b16caa"
    "status": "submitted",
    "startTime": "2025-03-05T22:18:10Z"
} 

As verifications take an indeterminate amount of time, the third party assigns a trace id for each submission. This id uses the entry’s ERC, which associates incoming API calls with the appropriate distributor information.

Here, you’ll simulate incoming PATCH requests from Clarity’s third-party KYC service.

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

2. Click the REST Applications drop-down menu and select c/distributorkycverifications.

3. Expand the patchByExternalReferenceCode endpoint.

4. For the externalReferenceCode parameter, enter eced9c29-7e9a-465b-a010-9bce57b16caa.

5. For Request body, delete the sample JSON content.

6. In your course workspace, open the exercises/exercise-02/01-request-body.txt file and review the file's contents. It includes these changes:

   • Adds the validatedBusinessEIN field
   • Adds tags
   • Adds the trace field
   • Updates kYCStatus to Verified
   • Updates kYCVerificationState to Approved

7. Copy its contents into the Request body field.

8. Click Execute.

9. Under Responses, verify a request URL and 200 response code appear.
   
   For non-simulated verifications, 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.

10. Expand the getDistributorKYCVerificationsPage endpoint.
    The previous PATCH request included tags that you’ll use to filter object entries by type and classification.

    "keywords" : [
       "specialty", "online_retailer", "wholesale_supplier"
    ]

11. Copy and paste this into the filter parameter:

    keywords in ('specialty','online_retailer')
    

    

12. Click Execute.
    The server response should return a single record associated with the externalReferenceCode eced9c29-7e9a-465b-a010-9bce57b16caa.

13. Verify the server response accurately reflects the payload information from step 6.

Great! You’ve used the Distributor KYC Verification object’s APIs to simulate a PATCH response from an external source.

Conclusion

Congratulations! You’ve created no-code APIs through Clarity’s Distributor KYC Verification 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.