Skip to main content

​
Module Detail

Whenever your agent needs to look up a prospect, add new details, or create an entirely new record inside GoHighLevel, this is the module to reach for.

​
Setup

​
Add the Module

  1. In the agent editor click Add Tool → Module Library
  2. Under Contact choose Find or Create Contact
  3. No extra settings needed - once connected to GoHighLevel it’s ready to use

​
What the Module Can Do

​
Fetch an Existing Contact

Supply no variables and it will pull the contact linked to the phone number (voice) or chat thread, returning every custom field and upcoming appointment.

​
Update a Contact

Pass any combination of fields (name, email, custom fields) and it overwrites the record if one is found.

​
Create a Contact

If no record matches the phone or email, the module creates a brand-new contact using the fields you provide. Note: The full list of accepted fields matches GoHighLevel’s API. Custom fields work too—just send them as normal keys. Reference: GoHighLevel API “Create Contact” endpoint

​
Typical Variable Set

Standard Fields:
  • name: Full name of the prospect
  • email: Email address
  • phone: Mobile or landline in international format (+1234567890)
  • company_name: Business name (optional)
  • time_zone: IANA timezone (optional, useful for booking)
Custom Fields:
  • Any custom field from your GHL account
  • Pass as customField.field_key: "value"
Tips:
  • Flag fields as required only when the agent must supply the value
  • Optional fields allow flexibility for incomplete data

​
Prompt Examples

​
Create or Update on Website Chatbot

Ask the visitor for name, email, and phone number.

Run find_or_create_contact with those values.

Store the returned contact ID for later booking tasks.
Example conversation: 
Bot: What's your name?
User: Sarah Johnson

Bot: Thanks Sarah! What's your email?
User: [email protected]

Bot: And your phone number?
User: 555-123-4567

Bot: [runs find_or_create_contact]
     Perfect! I've got you in our system.

​
Fetch Data on Inbound Call

Immediately run find_or_create_contact (no variables).

Use the returned custom fields during the conversation.
Example: 
Agent: [runs module when call connects]
Agent: "Hi {{firstName}}! I see you last spoke with us about 
        {{service_interest}}. Is that still what you're looking for?"

​
Update Missing Details After Voice Call

If the caller provides an email during the conversation, 
run find_or_create_contact with:
  email = the address they gave

This updates their record with the new information.
Example: 
Agent: "What's the best email to send the details to?"
Caller: "[email protected]"
Agent: [runs module with email]
       "Perfect, I've added that to your profile."

​
Common Use Cases

​
1. Inbound Call - Fetch Existing Data

When call connects, immediately run find_or_create_contact 
with no variables.

This retrieves:
- Full name
- Email
- Previous appointments
- Custom fields (lead source, interests, etc.)

Use this info to personalize the conversation.

​
2. Web Chat - Create New Lead

During chat, collect:
1. Name
2. Email
3. Phone number
4. Interest area

Run find_or_create_contact with all fields.

Return value includes contact_id - save this for booking.

​
3. Update Contact After Qualification

After qualifying the lead, run find_or_create_contact with:
  customField.qualification_status = "qualified"
  customField.budget = "{{budget_range}}"
  customField.timeline = "{{timeline}}"

This enriches their profile for sales team follow-up.

​
4. Add Tags Based on Conversation

If prospect shows interest in solar panels, run 
find_or_create_contact with:
  tags = ["solar-interested", "residential"]

If they mention commercial property:
  tags = ["solar-interested", "commercial"]

​
Best-Practice Tips

​
Run Before Booking

Run this module before the Book Appointment tool so GoHighLevel recognizes the lead and attaches the booking to their profile.

​
Use in First Turn (Chatbots)

For chatbots, include it in the first turn—then every message knows the contact’s name and timezone. 
When conversation starts, immediately run find_or_create_contact.

Use {{firstName}} in all subsequent messages.

​
Confirmation Line (Voice)

When gathering extra info on a voice call, add a confirmation: 
After running find_or_create_contact:
"Perfect, I've added that to your profile."
This reassures the caller their information is saved.

​
Handle Missing Data Gracefully

If find_or_create_contact returns no email:
"I don't have an email on file. What's the best one to use?"

[Collect email, run module again to update]

​
Returned Data

The module returns a JSON object with: 
{
  "contact_id": "abc123xyz",
  "firstName": "Sarah",
  "lastName": "Johnson",
  "email": "[email protected]",
  "phone": "+15551234567",
  "timezone": "America/New_York",
  "customField": {
    "lead_source": "Website Chat",
    "interest": "Solar Panels"
  },
  "appointments": [...]
}
Access this data in subsequent steps of your conversation.

​
Advanced: Multi-Step Workflows

​
Lead Enrichment Flow

1. Agent asks qualification questions
2. Runs find_or_create_contact with answers
3. GHL tags contact based on responses
4. Triggers separate workflow:
   - Qualified → Book appointment workflow
   - Unqualified → Nurture sequence

​
Progressive Profiling

First interaction:
- Collect name, email, phone
- Create contact with basic info

Second interaction:
- Fetch existing contact
- Add company, budget, timeline
- Update without creating duplicate

Third interaction:
- Fetch contact
- Show previous conversation history
- Book appointment with full context

​
Troubleshooting

​
Duplicate Contacts Created

  • Ensure phone numbers are in consistent format (+1234567890)
  • Use email as the unique identifier where possible
  • Check for typos in phone number entry

​
Custom Fields Not Saving

  • Verify custom field exists in GHL account
  • Use exact field key from GHL (case-sensitive)
  • Check field type matches value (text, number, date, etc.)

​
Contact Not Found

  • Verify phone number format matches GHL
  • Check that contact exists in correct GHL location/subaccount
  • Try using email instead of phone for lookup

​
Permissions Error

  • Verify GHL API permissions are enabled
  • Check Callgency integration is connected
  • Re-authenticate GHL connection if needed

​
Next Steps

Master the Find or Create Contact module and your agents will keep GoHighLevel perfectly up-to-date while chatting, calling, and booking—all without human data entry.