Contact CRUD Setup

Get up and running with core contact operations in minutes. This quick-start walks you through authentication, your first API call, and verifying everything works.

Prerequisites

Before making your first Contact CRUD call, confirm you have:

• A GoHighLevel sub-account with at least one contact (or permission to create one)
• Access to Settings > Integrations > Private Integrations in your sub-account
• A REST client such as Postman, Insomnia, or curl in your terminal
• Your sub-account’s locationId (found in Settings > Business Profile)

Set Up Authentication

All Contact CRUD endpoints require a Private Integration Token (PIT) with the contacts scope.

Navigate to Settings > Integrations > Private Integrations in your sub-account. Click Create New Integration and give it a descriptive name like “Contact API Access.”

Under Scopes, enable the contacts scope. This grants read and write access to contact records, tags, notes, tasks, and related data.

Click Save and copy the generated token. Store it securely. You will pass this token in the Authorization header of every request as a Bearer token.

Set your base URL to https://services.leadconnectorhq.com. All endpoints in this guide are relative to that base.

Make Your First Call

The most common starting point is creating a contact. Send a POST request to /contacts with the following body:

POST /contacts
Authorization: Bearer {your-pit-token}
Content-Type: application/json

{
  "locationId": "your-location-id",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "phone": "+15551234567",
  "tags": ["api-test"],
  "source": "API"
}

Key parameters include firstName, lastName, email, phone, tags, customFields, source, and companyName. Only locationId is strictly required, but always include at least one identifier (email or phone) for deduplication.

To upsert instead of create, use POST /contacts/upsert. This creates the contact if no match exists, or updates the existing record matched by email or phone.

Handle the Response

A successful POST /contacts call returns a 201 status with the full contact object:

{
  "contact": {
    "id": "abc123",
    "locationId": "your-location-id",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "[email protected]",
    "phone": "+15551234567",
    "tags": ["api-test"],
    "dateAdded": "2026-03-07T12:00:00Z"
  }
}

Save the contact.id value. You need it for all subsequent operations: GET /contacts/{id} to read, PUT /contacts/{id} to update, and DELETE /contacts/{id} to remove.

Common error codes: 400 means a required field is missing or malformed. 401 means your token is invalid or expired. 422 means validation failed, often due to a duplicate email or phone when not using upsert.

Test Your Setup

Run through this checklist to confirm everything is wired up:

1. Create a test contact with POST /contacts and verify the 201 response
2. Read it back with GET /contacts/{id} using the returned ID
3. Update a field with PUT /contacts/{id}, changing lastName to “Updated”
4. Search for the contact with GET /contacts?locationId={id}&[email protected]
5. Delete the test contact with DELETE /contacts/{id} and confirm the 200 response

If any call returns 401, regenerate your PIT and confirm the contacts scope is enabled. If you get 422 on create, switch to the upsert endpoint to handle duplicates gracefully.

Next Steps

Read the full Contact CRUD Guide for advanced patterns including bulk operations, custom field mapping, and search filters. From here, explore Contact Tags for segmentation and Contact Tasks for assigning follow-ups to your team.