Skip to main content
GHL MCP Guide
CCR

Contact CRUD

Contacts & CRM · Basic · Updated March 2026

Core contact operations for creating, reading, updating, deleting, and searching contacts via the GHL MCP server. The foundation of every CRM automation.

Contact CRUD is the foundation of everything you do with GoHighLevel’s MCP server. Every automation, every integration, every workflow that touches a human being starts here. If you can create, read, update, and delete contacts programmatically, you can build anything.

What This MCP Tool Does

This tool gives you full control over contact records in any GHL sub-account. You can create new contacts with all their data in a single call, look up existing contacts by ID, update any field on a contact record, delete contacts you no longer need, search across your entire contact database with filters, and use the upsert pattern to create-or-update in one operation.

The upsert capability is particularly valuable. Instead of checking whether a contact exists and then deciding to create or update, you make one call. If the contact exists (matched by email or phone), it updates. If not, it creates. This eliminates race conditions and simplifies every integration you build.

Endpoint Reference

Create a contact: POST /contacts Send contact data (name, email, phone, custom fields, tags) and receive the created contact record with its new ID.

Get a contact by ID: GET /contacts/{contactId} Retrieve the full contact record including all fields, tags, and metadata.

Update a contact: PUT /contacts/{contactId} Send any fields you want to change. Only the fields you include get updated; everything else stays the same.

Delete a contact: DELETE /contacts/{contactId} Permanently removes the contact record. This cannot be undone.

Search contacts: GET /contacts Search with filters including name, email, phone, tags, custom field values, and date ranges. Supports pagination for large result sets.

Upsert (create or update): POST /contacts/upsert Matches on email or phone. If found, updates the existing record. If not found, creates a new one. Returns the contact either way.

Authentication

Requires a Private Integration Token (PIT) with the contacts scope enabled. All contact operations use sub-account level access, meaning the PIT must have access to the specific location where the contacts live.

Key Parameters

When creating or updating contacts, the most commonly used fields are:

  • firstName, lastName — contact name
  • email — primary email address (also used for upsert matching)
  • phone — primary phone number (also used for upsert matching)
  • address1, city, state, postalCode, country — physical address
  • tags — array of tag strings to apply
  • customFields — array of objects with id (custom field ID) and value
  • source — where the contact came from (useful for attribution)
  • companyName — associated business name

For search operations, key filters include query (searches across name, email, phone), tags, and date range parameters.

Important Notes

The upsert endpoint matches on email first, then phone. If a contact has the same email but different phone, it updates rather than creating a duplicate. Plan your data flow accordingly.

Bulk operations are not available through a single endpoint. To process many contacts, you need to make individual calls. Rate limiting applies, so build in appropriate delays for large batch operations.

Custom field values require the custom field ID (not the field name). You can retrieve field IDs using the Location Custom Fields tool.

Common Questions

Can I create a contact with tags in a single call? Yes. Include a tags array in the create or upsert request body. The tags are applied as part of the contact creation.

What happens if I upsert with an email that already exists? The existing contact is updated with whatever fields you include in the request. Fields you omit remain unchanged on the existing record.

Is there a limit to how many contacts I can search for at once? Search results are paginated. The default page size varies, but you can use the limit and offset parameters to page through large result sets.

Can I update custom fields through the contact update endpoint? Yes. Include the customFields array with the field ID and new value. You need the custom field ID, not the display name.

Back to GHL MCP Guide