What Is Card Lookup?
The Card Lookup capability lets your AI Agent reference information from records related to the matched contact, within the boards and fields you configure.
This means your agent can:
- Look up the status of a work order
- Provide updates on a rental application
- Share details like balances, stages, or custom field data
- Optionally add comments from the caller directly to the card comments
The agent first matches the contact. It can reference an object when that object is related to the contact’s record. Selecting a board or filter does not make unrelated records available for arbitrary lookup.
Review the fields that the agent may disclose, particularly for balances, applications, and other sensitive records. Contact matching and record relationships describe the lookup scope; they should not be treated as a separate identity-verification guarantee.
When Should You Use Card Lookup?
Card Lookup is helpful when you want your AI Agent to:
- Provide residents with updates on work orders
- Let applicants check their application status
- Share information from a custom board (like balances, onboarding status, etc.)
- Add internal notes to cards after conversations
Aptly includes pre-configured lookup rules for:
- Work Orders
- Applications
You can also create custom lookup scenarios for any board.
How to Add the Card Lookup Capability
- Go to your AI Agent
- Select Configuration
- Scroll to the bottom to Capabilities
- Click Add Capability
- Choose Card - Lookup
You can add multiple Card Lookup rules under one capability. Use Title to name a rule and Lookup Boards to select its board and card scope.
Card Lookup Options
When adding a rule, you’ll choose from three types:
- Work Orders
- Application Status
- Custom Scenario
Let’s break each one down.
Option 1: Work Orders Lookup
Select Work Orders if you want the agent to provide updates on maintenance requests.
Board Selection
- The Work Orders board will automatically populate.
- By default, it pulls from all active cards.
- You may select a different Work Orders board if needed.
- You can optionally apply a filter segment (for example, only open or in-progress work orders).
If no filter is selected, all active cards are in the configured board scope. The contact match and related-record requirement still apply.
Data the Agent Can Disclose
You can control exactly what information the agent shares.
Standard Fields includes:
- Aptly Card UUID
- Created At
- Last Updated
- Stage
- Title
You can also:
- Select All Fields
- Choose Specific Fields by clicking the + icon
- Toggle on only the fields you want the agent to reference
This gives you full control over what the agent is allowed to say.
Conversation Model
Select your Work Orders conversation model so the agent speaks appropriately about maintenance-related topics.
Conversation Actions
Enable Allow Commenting under Conversation Actions to allow the agent to:
- Add comments to the card during or after the conversation
This is useful for logging updates or notes directly on the work order.
Option 2: Application Status Lookup
Select Application Status if you want applicants to check on their rental application.
Board Selection
- The Applicants board will populate automatically.
- Defaults to all active cards.
- You may apply a filter (for example, only in-progress applications).
Data the Agent Can Disclose
Standard application fields include:
- Animals
- Approval status
- Application location
- Member count
- Vehicle count
- Primary applicant
- Stage
- Title
Just like Work Orders, you can:
- Select all fields
- Choose only specific fields to disclose
Conversation Model
This will default to your Applications conversation model, so the agent responds appropriately to applicants.
Conversation Actions
Enable Allow Commenting under Conversation Actions to allow the agent to:
- Add comments to the application card
Option 3: Custom Scenario
Choose Custom Scenario when you want the agent to look up data from a different board.
You will configure this manually.
Step 1: Select the Board
- Choose one board per lookup rule.
- Select whether to include all active cards or apply a specific filter (note: the filter must be created on the board first).
Example:
If you want residents to check their balance:
- Select your Accounts Receivable board.
- Optionally filter to only cards in the “Delinquent” stage.
Step 2: Choose the Data to Disclose
Select the specific fields the agent can share.
For example:
- Current balance
- Stage
- Due date
You control exactly what information is available to the agent.
Step 3: Configure the Conversation Model
Custom scenarios use a Custom conversation model.
You’ll define:
- When the agent should retrieve the data
(Example: “When a current resident asks about their balance.”)
- How the agent should discuss the data
(Example: “Be direct. Only provide information shown on the card.”)
These instructions guide the tone and boundaries of the response.
Step 4: Conversation Actions (Optional)
Enable Allow Commenting under Conversation Actions to allow the agent to:
- Add comments from the caller to the card
Important Notes
- You can add multiple Card Lookup rules within the same capability.
- Each rule connects to one board.
- Filters are optional but recommended if you want to limit what cards can be searched.
- Select only fields appropriate to share for the intended workflow. Review All Fields carefully before enabling it.
- Test with a contact that has a related record and one that does not. Check that responses stay within the intended record and field scope before using sensitive data.
Final Step
Once your rule is configured:
- Review your settings
- Click Save
Test the saved lookup configuration and review the responses against the matched contact’s related records.