Relations Setup

Create relations to link specific records together using your association definitions. While associations define the relationship type between objects, relations connect individual records. This guide covers creating, reading, and deleting record-level links.

Prerequisites

Before creating relations between records, confirm you have:

• A GoHighLevel sub-account with Custom Objects enabled
• At least one association already defined (see Associations)
• The associationId of the association you want to use
• Record IDs from both objects you want to link (e.g., a property record ID and a contact ID)
• A Private Integration Token (PIT) with the custom-objects scope
• A REST client such as Postman, Insomnia, or curl

Set Up Authentication

Relation endpoints require the same custom-objects scope used for associations and records.

Reuse your existing PIT if it already has this scope. If not:

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 ASSOCIATION_ID="your-association-id"

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

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

Make Your First Call

Create a relation between two records by sending a POST to /objects-association/{associationId}/relations:

curl -X POST "https://services.leadconnectorhq.com/objects-association/$ASSOCIATION_ID/relations" \
  -H "Authorization: Bearer $GHL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "firstRecordId": "rec_property_123",
    "secondRecordId": "contact_abc456"
  }'

The firstRecordId corresponds to the first object in the association definition, and secondRecordId corresponds to the second. The order must match how the association was created.

List relations for a record with GET /objects-association/relations/{recordId}. This returns all relations involving that record across all associations, letting you see every linked record from a single query.

Delete a relation with DELETE /objects-association/relations/{relationId} to unlink two records without deleting either record.

Handle the Response

A successful POST returns the new relation:

{
  "relation": {
    "id": "rel_def456",
    "associationId": "assoc_abc123",
    "firstRecordId": "rec_property_123",
    "secondRecordId": "contact_abc456",
    "createdAt": "2026-03-07T12:00:00Z"
  }
}

Save the relation.id for deletion operations. When querying relations for a record, the response includes an array of relation objects with both record IDs and the association details.

Common errors: 400 means a required field is missing. 404 means the association ID or one of the record IDs does not exist. 409 means this exact relation already exists. Duplicate relations between the same two records are not allowed.

Test Your Setup

Walk through these steps to verify relations work correctly:

1. Create a relation linking a custom object record to a contact with POST /objects-association/{id}/relations
2. Query from one side using GET /objects-association/relations/{recordId} with the custom object record ID
3. Query from the other side using the same endpoint with the contact ID to confirm bidirectional lookup works
4. Delete the test relation with DELETE /objects-association/relations/{relationId}
5. Verify deletion by querying the record again and confirming the relation no longer appears

If 404 errors occur, verify the association ID is correct and that both records exist in their respective objects.

Next Steps

Read the full Relations guide for advanced patterns including bulk relation creation and querying across multiple association types. Explore Associations to define new relationship types, or use Object Records to manage the data within your custom objects.