Skip to main content
GHL MCP Guide
OBR

Object Records

Custom Objects & Schema · Advanced · Updated March 2026

Create, read, update, delete, and search records within custom objects with field validation and search capabilities.

Object Records is the data layer of custom objects. Once a schema defines the structure through Object Schema CRUD, this tool manages the actual records — creating, reading, updating, deleting, and searching the data that fills those structures.

What This MCP Tool Does

Full CRUD plus search on records within any custom object type. If you defined a “Properties” object, this is where you create individual property records, update their details, search across all properties, and delete records that are no longer relevant.

Endpoint Reference

Create a record: POST /objects/{objectId}/records Create a new record in the custom object with field values.

Get a record: GET /objects/{objectId}/records/{recordId} Retrieve a specific record with all its field values.

Update a record: PUT /objects/{objectId}/records/{recordId} Modify field values on an existing record.

Delete a record: DELETE /objects/{objectId}/records/{recordId} Permanently remove a record.

Search records: GET /objects/{objectId}/records/search Search across records with field-based filters and pagination.

Authentication

Requires a Private Integration Token (PIT) with the custom-objects or equivalent scope enabled.

Key Parameters

When creating or updating records:

  • Field values matching the schema definition
  • Values must conform to the field type and validation rules defined in the schema
  • Required fields must be provided on creation

For searching:

  • Field-based filter criteria
  • Pagination parameters for large result sets

Important Notes

Records are validated against their schema. If a field is defined as a number, you cannot store text in it. If a field is required, you cannot create a record without it. The schema is the contract.

Search capabilities depend on the fields indexed in the schema. Not all field types may be searchable. Plan your schema with search requirements in mind.

For agencies building industry-specific solutions, object records are where the real value lives. A real estate agency’s property records, a fleet management company’s vehicle records, an insurance agency’s policy records — this is the custom data that makes GHL work for specific industries.

Combine with Relations to link records to contacts, opportunities, or other custom objects. A property record linked to a contact record creates the relationship between “this person owns this property.”

Common Questions

How many records can a custom object hold? Check the GHL platform documentation for current record limits per object type. Limits may vary by plan level.

Can I bulk-import records? There is no bulk import endpoint. For large data sets, create records individually with rate limiting. For initial data loads, consider using the GHL UI import tools if available.

How do I associate a record with a contact? First define an association between the custom object and contacts using Associations. Then create a relation linking the specific record to the specific contact using Relations.

Can I export custom object data? Retrieve records through the search endpoint and process them in your export pipeline. The API provides the data; you handle the export format.

Back to GHL MCP Guide