Object Records Setup

Create and manage records within your custom object schemas. This guide covers the full CRUD lifecycle plus search, so you can store and retrieve structured data through the API.

Prerequisites

Before working with object records, confirm you have:

• A GoHighLevel sub-account with Custom Objects enabled
• At least one custom object schema already created (see Object Schema CRUD)
• The objectId of the schema you want to add records to
• 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

Object record endpoints require a PIT with the custom-objects scope, the same token used for schema management.

If you already have a token with this scope from the schema setup, reuse it. Otherwise:

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

export GHL_TOKEN="your-private-integration-token"
export OBJECT_ID="your-object-id"

All requests target https://services.leadconnectorhq.com with these headers:

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

Make Your First Call

Create a record by sending a POST to /objects/{objectId}/records:

curl -X POST "https://services.leadconnectorhq.com/objects/$OBJECT_ID/records" \
  -H "Authorization: Bearer $GHL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "properties": {
      "address": "742 Evergreen Terrace",
      "price": 350000,
      "status": "Active"
    },
    "owner": "user-id-optional"
  }'

The properties object maps field keys from your schema to values. Required fields defined in the schema must be included or the call will fail.

Read a record with GET /objects/{objectId}/records/{recordId}. Update with PUT /objects/{objectId}/records/{recordId}, passing only the fields you want to change. Delete with DELETE /objects/{objectId}/records/{recordId}.

Search records using GET /objects/{objectId}/records/search with query parameters for filtering, sorting, and pagination.

Handle the Response

A successful POST returns 200 with the new record:

{
  "record": {
    "id": "rec_xyz789",
    "objectId": "obj_abc123",
    "properties": {
      "address": "742 Evergreen Terrace",
      "price": 350000,
      "status": "Active"
    },
    "owner": "user-id",
    "createdAt": "2026-03-07T12:00:00Z"
  }
}

Store the record.id for subsequent read, update, and delete operations. The search endpoint returns an array of records with pagination metadata including total, limit, and offset.

Common errors: 400 means a required field is missing or a value does not match the expected type. 404 means the objectId or recordId does not exist. 422 indicates validation failure, such as an invalid option value for a dropdown field.

Test Your Setup

Walk through these steps to confirm your integration works end to end:

1. Create a test record with POST /objects/{id}/records and save the returned id
2. Read it back with GET /objects/{id}/records/{recordId} and verify all properties
3. Update one field with PUT /objects/{id}/records/{recordId} and confirm the change
4. Search for the record using GET /objects/{id}/records/search with a filter on a known value
5. Delete the test record with DELETE /objects/{id}/records/{recordId} and verify a follow-up GET returns 404

If creates fail with 400, compare your properties keys against the schema definition. Field keys are case-sensitive.

Next Steps

Read the full Object Records guide for advanced search filters, bulk operations, and owner assignment patterns. Set up Relations to link records to contacts and other objects, or use Custom Fields V2 to extend your schema with additional field types.