Overview
Contacts represent individuals who interact with the helpdesk. Contacts are linked to tickets and can be associated with customers (organizations).
The Contact DocType is a standard Frappe DocType, not specific to Helpdesk. It’s used across multiple Frappe apps.
Unique identifier for the contact
Organization the contact belongs to
This endpoint is defined in helpdesk/api/contact.py:6
@frappe.whitelist(methods=["GET"])
def search_contacts(
txt: str,
) -> list[dict[Literal["full_name", "name", "email_id"], str]]:
"""Search contacts by text
Searches across full_name, email_id, and name fields.
Only returns contacts with email addresses set.
"""
Search query text. Searches in full_name, email_id, and name fields using LIKE matching
HTTP Method
This endpoint only accepts GET requests.
Response
Returns an array of contact objects, limited to 10 results:
Contact’s unique identifier
Search Behavior
- Searches across three fields:
full_name, email_id, and name
- Uses LIKE matching with wildcards (
%txt%)
- Only returns contacts where
email_id is set
- Limited to 10 results
- Results are ordered by:
email_id, full_name, name
Example Request
import frappe
# Search for contacts
results = frappe.call(
"helpdesk.api.contact.search_contacts",
txt="john"
)
for contact in results:
print(f"{contact.full_name} - {contact.email_id}")
# HTTP GET request
curl -X GET "https://your-site.com/api/method/helpdesk.api.contact.search_contacts?txt=john" \
-H "Authorization: token api_key:api_secret"
Example Response
[
{
"full_name": "John Doe",
"name": "CONT-0001",
"email_id": "[email protected]"
},
{
"full_name": "John Smith",
"name": "CONT-0023",
"email_id": "[email protected]"
}
]
import frappe
# Get single contact
contact = frappe.get_doc("Contact", "CONT-0001")
print(f"Name: {contact.full_name}")
print(f"Email: {contact.email_id}")
print(f"Phone: {contact.phone}")
import frappe
# Create a new contact
contact = frappe.get_doc({
"doctype": "Contact",
"full_name": "Jane Doe",
"email_id": "[email protected]",
"phone": "+1-555-0123",
"company_name": "Acme Corp"
})
contact.insert()
print(f"Created contact: {contact.name}")
import frappe
# Update contact email
contact = frappe.get_doc("Contact", "CONT-0001")
contact.email_id = "[email protected]"
contact.save()
import frappe
# Link contact to customer
contact = frappe.get_doc("Contact", "CONT-0001")
contact.append("links", {
"link_doctype": "HD Customer",
"link_name": "Customer Name"
})
contact.save()
import frappe
# Get all contacts for a customer
contacts = frappe.get_all(
"Dynamic Link",
filters={
"link_doctype": "HD Customer",
"link_name": "Acme Corp",
"parenttype": "Contact"
},
fields=["parent"],
pluck="parent"
)
# Get contact details
for contact_id in contacts:
contact = frappe.get_doc("Contact", contact_id)
print(f"{contact.full_name} - {contact.email_id}")
import frappe
contact = frappe.get_doc("Contact", "CONT-0001")
# Add additional email
contact.append("email_ids", {
"email_id": "[email protected]",
"is_primary": 0
})
contact.save()
# List all emails
for email in contact.email_ids:
primary = "(Primary)" if email.is_primary else ""
print(f"{email.email_id} {primary}")
- Name
- Email ID
- Creation date
These are defined in helpdesk.utils.contact_default_columns.
Standard Frappe API Methods
Since Contact is a standard DocType, all Frappe document APIs are available:
frappe.get_doc("Contact", contact_id) - Get single contactfrappe.get_list("Contact", filters={...}) - Query contactsfrappe.db.get_value("Contact", contact_id, field) - Get specific fieldfrappe.delete_doc("Contact", contact_id) - Delete contact
import frappe
# Find or create contact
contact = frappe.db.get_value(
"Contact",
{"email_id": "[email protected]"},
"name"
)
if not contact:
contact_doc = frappe.get_doc({
"doctype": "Contact",
"full_name": "Customer Name",
"email_id": "[email protected]"
})
contact_doc.insert()
contact = contact_doc.name
# Create ticket with contact
ticket = frappe.get_doc({
"doctype": "HD Ticket",
"subject": "Support Request",
"raised_by": "[email protected]",
"contact": contact
})
ticket.insert()