Contact Tasks Setup

Assign and manage follow-up tasks on contact records through the API. This quick-start covers creating tasks, marking them complete, and verifying your setup end to end.

Prerequisites

Before working with Contact Tasks, confirm you have:

• A GoHighLevel sub-account with at least one existing contact
• A Private Integration Token with the contacts scope configured
• The contactId of the contact you want to assign tasks to
• A REST client such as Postman, Insomnia, or curl

Set Up Authentication

Contact Tasks share the same authentication as all contact endpoints. You need a Private Integration Token (PIT) with the contacts scope.

Navigate to Settings > Integrations > Private Integrations in your sub-account. If you already have a PIT with the contacts scope, reuse it. Otherwise, create a new integration, enable the contacts scope, save, and copy the token.

Set your Authorization header to Bearer {your-pit-token} for every request. Your base URL is https://services.leadconnectorhq.com.

Make Your First Call

The most common operation is creating a task on a contact. Send a POST request to /contacts/{contactId}/tasks:

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

{
  "title": "Follow up on proposal",
  "body": "Call Jane to discuss the revised pricing.",
  "dueDate": "2026-03-10T14:00:00Z",
  "completed": false,
  "assignedTo": "user-id-here"
}

Key parameters: title is required and describes the task. body provides additional detail. dueDate sets the deadline in ISO 8601 format. assignedTo accepts a user ID from your sub-account team. completed defaults to false.

To list all tasks on a contact, use GET /contacts/{contactId}/tasks. This returns every task regardless of completion status.

Handle the Response

A successful task creation returns a 201 status with the full task object:

{
  "task": {
    "id": "task-abc123",
    "title": "Follow up on proposal",
    "body": "Call Jane to discuss the revised pricing.",
    "dueDate": "2026-03-10T14:00:00Z",
    "completed": false,
    "assignedTo": "user-id-here",
    "contactId": "contact-xyz789"
  }
}

Save the task.id value. You need it to update the task with PUT /contacts/{contactId}/tasks/{taskId}, mark it complete with PATCH /contacts/{contactId}/tasks/{taskId}/completed, or delete it with DELETE /contacts/{contactId}/tasks/{taskId}.

Common errors: 400 means a required field like title is missing. 404 means either the contactId or taskId does not exist. 401 means your token is invalid or lacks the contacts scope.

Test Your Setup

Run through this checklist to confirm task management is working:

1. Create a task on a test contact with POST /contacts/{id}/tasks and verify the 201 response
2. List all tasks with GET /contacts/{id}/tasks and confirm your new task appears
3. Update the task title with PUT /contacts/{id}/tasks/{taskId}
4. Mark complete with PATCH /contacts/{id}/tasks/{taskId}/completed and set completed to true
5. Delete the task with DELETE /contacts/{id}/tasks/{taskId} and confirm it no longer appears in the list

Verify tasks also show up in the GoHighLevel UI. Open the contact record in the browser and check the Tasks tab. The task you created via API should appear there with the correct title, due date, and assignee.

Next Steps

Read the full Contact Tasks Guide for patterns like bulk task assignment and overdue task monitoring. Pair tasks with Contact Notes to log meeting summaries alongside follow-up actions, or use Campaign & Workflow to create tasks automatically when contacts enter specific workflow stages.