Associations Setup

Define associations to establish relationships between custom objects and built-in GHL objects like contacts and opportunities. This guide covers creating, listing, and deleting association definitions through the API.

Prerequisites

Before setting up associations, confirm you have:

• A GoHighLevel sub-account with Custom Objects enabled
• At least one custom object schema created (see Object Schema CRUD)
• The key values for both objects you want to associate (e.g., property and contact)
• A Private Integration Token (PIT) with the custom-objects scope
• Your locationId from Settings > Business Profile
• A REST client such as Postman, Insomnia, or curl

Set Up Authentication

Association endpoints use the same custom-objects scope as other custom object operations.

If you already have a PIT with this scope, reuse it. Otherwise, create one:

1. Go to Settings > Integrations > Private Integrations
2. Create or edit an integration and enable the custom-objects scope
3. Copy the token and store it securely

export GHL_TOKEN="your-private-integration-token"
export LOCATION_ID="your-location-id"

Base URL: https://services.leadconnectorhq.com. Include these headers on every request:

Authorization: Bearer $GHL_TOKEN
Content-Type: application/json
Version: 2021-07-28

Make Your First Call

Create an association between two objects by sending a POST to /objects-association:

curl -X POST "https://services.leadconnectorhq.com/objects-association" \
  -H "Authorization: Bearer $GHL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "locationId": "'"$LOCATION_ID"'",
    "key": "property_contact",
    "firstObjectKey": "property",
    "secondObjectKey": "contact",
    "description": "Links properties to interested contacts"
  }'

The key must be unique within your location and serves as a human-readable identifier. The firstObjectKey and secondObjectKey reference the keys of the objects you are linking. Built-in object keys include contact, opportunity, and company.

List all associations with GET /objects-association?locationId={locationId}. Look up by key with GET /objects-association/key/{key}. Find by object with GET /objects-association/object/{objectKey} to see all associations involving a specific object.

Handle the Response

A successful POST /objects-association returns the association definition:

{
  "association": {
    "id": "assoc_abc123",
    "locationId": "your-location-id",
    "key": "property_contact",
    "firstObjectKey": "property",
    "secondObjectKey": "contact",
    "description": "Links properties to interested contacts",
    "createdAt": "2026-03-07T12:00:00Z"
  }
}

Save the association.id. You need it to create relations between specific records and to delete the association definition. The association is bidirectional, so you can query it from either object.

Common errors: 400 means a required field like key or an object key is missing. 404 means one of the referenced object keys does not exist. 409 means an association with that key already exists. 401 indicates an invalid token or missing scope.

Test Your Setup

Confirm your associations are working correctly:

1. Create an association between your custom object and contact with POST /objects-association
2. List all associations with GET /objects-association and verify yours appears
3. Look up by key with GET /objects-association/key/{your-key} to retrieve the definition
4. Query by object with GET /objects-association/object/{objectKey} to see all relationships for one object
5. Delete a test association with DELETE /objects-association/{id} and verify it no longer appears in listings

If 404 errors appear, double-check that both object keys exist in your location. Use GET /objects to list available schemas.

Next Steps

Read the full Associations guide for advanced patterns including naming conventions and multi-object relationship strategies. Once your association is defined, set up Relations to link specific records together, or explore Object Records to populate your custom objects with data.