# Get Object Schema by key / id

GET https://services.leadconnectorhq.com/objects/{key}

Retrieve Object Schema by key or ID. This will return the schema of the custom object, including all its fields and properties. Supported objects include contact, opportunity, business and custom objects.To understand objects and records, please have a look the documentation here : https://doc.clickup.com/8631005/d/h/87cpx-277156/93bf0c2e23177b0

## Authentication

Send `Authorization: Bearer <token>` using:

- **Sub-Account token: OAuth access token or Private Integration Token.** Scopes: `objects/schema.readonly`

## Parameters

### Header Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Version` | string | Yes | API Version |

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `key` | string | Yes | key of the custom or standard object. For custom objects, the key must include the prefix “custom_objects.”. This key can be found on the Object Details page under Settings in the UI. |

### Query Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `locationId` | string | Yes | location id of the sub account |
| `fetchProperties` | string | No | Fetch Properties , Fetches all the standard / custom fields of the object when set to true |

## OpenAPI Specification

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "HighLevel API",
    "version": "2021-07-28"
  },
  "servers": [
    {
      "url": "https://services.leadconnectorhq.com"
    }
  ],
  "paths": {
    "/objects/{key}": {
      "get": {
        "summary": "Get Object Schema by key / id",
        "operationId": "getObjectSchemaByKeyId",
        "description": "Retrieve Object Schema by key or ID. This will return the schema of the custom object, including all its fields and properties. Supported objects include contact, opportunity, business and custom objects.To understand objects and records, please have a look the documentation here : https://doc.clickup.com/8631005/d/h/87cpx-277156/93bf0c2e23177b0",
        "parameters": [
          {
            "name": "Version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "2021-07-28"
              ]
            }
          },
          {
            "name": "key",
            "required": true,
            "in": "path",
            "description": "key of the custom or standard object. For custom objects, the key must include the prefix “custom_objects.”. This key can be found on the Object Details page under Settings in the UI.",
            "schema": {
              "example": "custom_objects.pet",
              "type": "string"
            }
          },
          {
            "name": "locationId",
            "required": true,
            "in": "query",
            "description": "location id of the sub account",
            "schema": {
              "example": "632c34b4c9b7da3358ac9891",
              "type": "string"
            }
          },
          {
            "name": "fetchProperties",
            "required": false,
            "in": "query",
            "description": "Fetch Properties , Fetches all the standard / custom fields of the object when set to true",
            "schema": {
              "example": "true",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomObjectByIdResponseDTO"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestDTO"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedDTO"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Entity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnprocessableDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": [
              "objects/schema.readonly"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.",
        "type": "http"
      },
      "Location-Access": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.",
        "type": "http"
      },
      "Location-Access-Only": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Sub-Account.",
        "type": "http"
      },
      "Agency-Access": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Agency (OR) Private Integration Token of Agency.",
        "type": "http"
      }
    },
    "schemas": {
      "CustomObjectByIdResponseDTO": {
        "type": "object",
        "properties": {
          "object": {
            "description": "The custom or standard object schema",
            "example": {
              "id": "661c06b4ffde146bdb469442",
              "standard": false,
              "key": "custom_objects.pet",
              "labels": {
                "singular": "Pet",
                "plural": "Pets"
              },
              "description": "These are non vaccinated pets",
              "locationId": "ve9EPM428h8vShlRW1KT",
              "primaryDisplayProperty": "custom_objects.pet.name",
              "type": "USER_DEFINED",
              "dateAdded": "2025-01-02T09:35:39.032Z",
              "dateUpdated": "2025-01-02T09:35:39.032Z"
            },
            "allOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "example": "661c06b4ffde146bdb469442",
                    "description": "id of the custom / standard object schema"
                  },
                  "standard": {
                    "type": "boolean",
                    "example": false,
                    "description": "false in case of custom objects and true in case of standard objects like contacts and opportunities "
                  },
                  "key": {
                    "type": "string",
                    "example": "custom_objects.pet",
                    "description": "key that would be used to refer the custom / standard Object internally (lowercase + underscore_separated). For custom objects, 'custom_objects.' would be added as prefix by default"
                  },
                  "labels": {
                    "example": {
                      "singular": "Pet",
                      "plural": "Pets"
                    },
                    "description": "This is what your custom / standard  object will be called. These labels will be used to display your custom object on the UI",
                    "allOf": [
                      {
                        "type": "object",
                        "properties": {
                          "singular": {
                            "type": "string",
                            "example": "Pet",
                            "description": "Singular name of the custom object"
                          },
                          "plural": {
                            "type": "string",
                            "example": "Pets",
                            "description": "Plural name of the custom object"
                          }
                        },
                        "required": [
                          "singular",
                          "plural"
                        ],
                        "title": "CustomObjectLabelDto"
                      }
                    ]
                  },
                  "description": {
                    "type": "string",
                    "example": "These are non vaccinated pets",
                    "description": "Custom / Standard  Object Descriptions for example , Pet Object`s description"
                  },
                  "locationId": {
                    "type": "string",
                    "description": "location's id",
                    "example": "Q9DT3OAqEXDLYuob1G32"
                  },
                  "primaryDisplayProperty": {
                    "type": "string",
                    "description": "Primary property for the custom / standard  Object. This would be used as primary data when rendering the UI. 'custom_objects.{{object_key}} or business.{{object_key}} (for company)' would be added as prefix by default for all the custom / standard objects",
                    "example": "custom_objects.pet.name"
                  },
                  "dateAdded": {
                    "type": "string",
                    "description": "Date and time when the object was added",
                    "format": "date-time",
                    "example": "2025-01-02T09:35:39.032Z"
                  },
                  "dateUpdated": {
                    "type": "string",
                    "description": "Date and time when the object was last updated",
                    "format": "date-time",
                    "example": "2025-01-02T09:35:39.032Z"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "SYSTEM_DEFINED",
                      "USER_DEFINED"
                    ],
                    "example": "USER_DEFINED",
                    "description": "Object`s Type — USER_DEFINED for custom objects, SYSTEM_DEFINED for standard objects"
                  }
                },
                "required": [
                  "id",
                  "standard",
                  "key",
                  "labels",
                  "locationId",
                  "primaryDisplayProperty",
                  "dateAdded",
                  "dateUpdated"
                ],
                "title": "ICustomObjectSchema"
              }
            ]
          },
          "cache": {
            "type": "boolean",
            "description": "Is the response served from cache",
            "example": true
          },
          "fields": {
            "description": "Custom fields associated with the object schema",
            "example": [
              {
                "id": "661c06b4ffde146bdb469442",
                "locationId": "ve9EPM428h8vShlRW1KT",
                "name": "Pet Name",
                "description": "Pet name field",
                "placeholder": "Enter pet name",
                "fieldKey": "custom_object.pet.name",
                "objectKey": "custom_object.pet",
                "originId": "661c06b4ffde146bdb469442",
                "dataType": "TEXT",
                "parentId": "3v34PM428h8vShlRW1KT",
                "showInForms": true,
                "allowCustomOption": true,
                "maxFileLimit": 2,
                "acceptedFormats": [
                  ".pdf",
                  ".jpg"
                ],
                "optionDisplayType": "TEXT_ONLY",
                "options": [
                  {
                    "key": "option_a",
                    "label": "Option A",
                    "url": "https://example.com"
                  }
                ],
                "urlValidation": {
                  "mode": "allow_all",
                  "allowedDomains": [
                    "example.com"
                  ],
                  "blockedDomains": []
                },
                "dateTimeValidation": {
                  "mode": "range",
                  "rangeMin": "2025-01-02",
                  "rangeMax": "2025-12-31"
                },
                "userFieldConfig": {
                  "multiSelect": false
                },
                "scopes": [
                  {
                    "scopeType": "list",
                    "scopeId": "661c06b4ffde146bdb469442"
                  }
                ],
                "dateAdded": "2025-01-02T09:35:39.032Z",
                "dateUpdated": "2025-01-02T09:35:39.032Z"
              }
            ],
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "locationId": {
                  "type": "string",
                  "description": "Location Id",
                  "example": "ve9EPM428h8vShlRW1KT"
                },
                "name": {
                  "type": "string",
                  "description": "Field name",
                  "example": "Name"
                },
                "description": {
                  "type": "string",
                  "description": "Description of the field",
                  "example": "Pet name field"
                },
                "placeholder": {
                  "type": "string",
                  "description": "Placeholder text for the field",
                  "example": "Enter pet name"
                },
                "showInForms": {
                  "type": "boolean",
                  "description": "Whether the field should be shown in forms",
                  "example": true
                },
                "options": {
                  "description": "Options for the field (Optional, valid only for SINGLE_OPTIONS, MULTIPLE_OPTIONS, RADIO, CHECKBOX, TEXTBOX_LIST type)",
                  "example": [
                    {
                      "key": "option_a",
                      "label": "Option A"
                    }
                  ],
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "key": {
                        "type": "string",
                        "description": "Key of the option (Included in Create and Response, excluded in Update)",
                        "example": "option_a"
                      },
                      "label": {
                        "type": "string",
                        "description": "Value of the option",
                        "example": "Option A"
                      },
                      "url": {
                        "type": "string",
                        "description": "Option external hyperlink (RADIO). For image picklists the image is carried in `src` / `thumbnailUrl` — on write the image source is read from `src`, not `url`. Responses mirror `src` into `url` for backward-compatible readers.",
                        "example": "https://example.com"
                      },
                      "src": {
                        "type": "string",
                        "description": "Public image URL for the option (Optional, valid only for RADIO / CHECKBOX with optionDisplayType TEXT_WITH_IMAGE or TEXT_WITH_ICON)."
                      },
                      "thumbnailUrl": {
                        "type": "string",
                        "description": "Public URL of an optional smaller image variant for thumbnails (Optional, valid only for RADIO / CHECKBOX)."
                      },
                      "fileName": {
                        "type": "string",
                        "description": "Original file name of the uploaded image (Optional, valid only for RADIO / CHECKBOX)."
                      },
                      "description": {
                        "type": "string",
                        "description": "Alt-text / description for the image (Optional, valid only for RADIO / CHECKBOX)."
                      }
                    },
                    "required": [
                      "key",
                      "label"
                    ],
                    "title": "OptionDTO"
                  }
                },
                "acceptedFormats": {
                  "type": "string",
                  "enum": [
                    ".pdf",
                    ".docx",
                    ".doc",
                    ".jpg",
                    ".jpeg",
                    ".png",
                    ".gif",
                    ".csv",
                    ".xlsx",
                    ".xls",
                    "all"
                  ],
                  "description": "Allowed file formats for uploads. Options include: .pdf, .docx, .doc, .jpg, .jpeg, .png, .gif, .csv, .xlsx, .xls, all",
                  "example": [
                    ".pdf",
                    ".jpg"
                  ]
                },
                "id": {
                  "type": "string",
                  "description": "Unique identifier of the object",
                  "example": "661c06b4ffde146bdb469442"
                },
                "objectKey": {
                  "type": "string",
                  "description": "The key for your custom / standard object. This key uniquely identifies the custom object. Example: \"custom_object.pet\" for a custom object related to pets.",
                  "example": "custom_object.pet"
                },
                "originId": {
                  "type": "string",
                  "description": "Origin ID of the object",
                  "example": "661c06b4ffde146bdb469442"
                },
                "dataType": {
                  "type": "string",
                  "enum": [
                    "TEXT",
                    "LARGE_TEXT",
                    "NUMERICAL",
                    "PHONE",
                    "MONETORY",
                    "CHECKBOX",
                    "SINGLE_OPTIONS",
                    "MULTIPLE_OPTIONS",
                    "DATE",
                    "TEXTBOX_LIST",
                    "FILE_UPLOAD",
                    "RADIO",
                    "EMAIL",
                    "URL",
                    "TIME",
                    "DATE_TIME",
                    "USER",
                    "RICH_TEXT"
                  ],
                  "description": "Type of field that you are trying to create",
                  "example": "TEXT"
                },
                "parentId": {
                  "type": "string",
                  "description": "ID of the parent folder",
                  "example": "3v34PM428h8vShlRW1KT"
                },
                "fieldKey": {
                  "type": "string",
                  "description": "Field key. For Custom Object it's formatted as \"custom_object.{objectKey}.{fieldKey}\". \"custom_object\" is a fixed prefix, \"{objectKey}\" is your custom object's identifier, and \"{fieldName}\" is the unique field name within that object. Example: \"custom_object.pet.name\" for a \"name\" field in a \"pet\" custom object.",
                  "example": "custom_object.pet.name"
                },
                "allowCustomOption": {
                  "type": "boolean",
                  "description": "Determines if users can add a custom option value different from the predefined options in records for RADIO type fields. A custom value added in one record does not automatically become an option and will not appear as an option for other records.",
                  "example": true
                },
                "maxFileLimit": {
                  "type": "number",
                  "description": "Maximum file limit for uploads",
                  "example": 2
                },
                "urlValidation": {
                  "description": "URL validation (URL fields)",
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "mode": {
                          "type": "string",
                          "enum": [
                            "allow_all",
                            "allow_only",
                            "block"
                          ],
                          "example": "allow_all"
                        },
                        "allowedDomains": {
                          "example": [
                            "example.com"
                          ],
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "blockedDomains": {
                          "example": [],
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "title": "UrlValidationDto"
                    }
                  ]
                },
                "dateTimeValidation": {
                  "description": "Date/time validation (DATE, TIME, DATE_TIME)",
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "mode": {
                          "type": "string",
                          "enum": [
                            "any",
                            "future_only",
                            "past_only",
                            "range"
                          ],
                          "example": "any",
                          "description": "any: no restriction. future_only: value must be in future. past_only: value must be in past. range: value within rangeMin-rangeMax."
                        },
                        "bufferDays": {
                          "type": "number",
                          "description": "For future_only: minimum days from today before a date is selectable"
                        },
                        "rollingDays": {
                          "type": "number",
                          "description": "For future_only: rolling window in days from today (e.g. 30 = next 30 days). Mutually exclusive with bufferDays."
                        },
                        "rangeMin": {
                          "type": "string",
                          "description": "Required when mode is range. ISO date or datetime string"
                        },
                        "rangeMax": {
                          "type": "string",
                          "description": "Required when mode is range. ISO date or datetime string"
                        },
                        "daysAllowed": {
                          "description": "Days of week 0=Sunday..6=Saturday. Works alongside future_only, past_only, or range modes.",
                          "type": "array",
                          "items": {
                            "type": "number"
                          }
                        },
                        "inputType": {
                          "type": "string",
                          "enum": [
                            "date_only",
                            "time_only",
                            "date_and_time"
                          ],
                          "description": "For DATE_TIME fields: collect date only, time only, or both (defaults per product if omitted)."
                        }
                      },
                      "title": "DateTimeValidationDto"
                    }
                  ]
                },
                "userFieldConfig": {
                  "description": "User field config (USER fields)",
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "multiSelect": {
                          "type": "boolean",
                          "example": false,
                          "description": "Single or multi-select; cannot change after create"
                        }
                      },
                      "title": "UserFieldConfigDto"
                    }
                  ]
                },
                "optionDisplayType": {
                  "type": "string",
                  "enum": [
                    "TEXT_ONLY",
                    "TEXT_WITH_ICON",
                    "TEXT_WITH_IMAGE"
                  ],
                  "description": "Option rendering mode for RADIO / CHECKBOX. One of TEXT_ONLY, TEXT_WITH_ICON, TEXT_WITH_IMAGE."
                },
                "scopes": {
                  "type": "array",
                  "description": "Scopes that this field is restricted to",
                  "items": {
                    "type": "object",
                    "properties": {
                      "scopeType": {
                        "type": "string",
                        "enum": [
                          "workspace",
                          "space",
                          "folder",
                          "list"
                        ]
                      },
                      "scopeId": {
                        "type": "string"
                      }
                    }
                  }
                },
                "dateAdded": {
                  "type": "string",
                  "description": "Date and time when the object was added",
                  "format": "date-time",
                  "example": "2025-01-02T09:35:39.032Z"
                },
                "dateUpdated": {
                  "type": "string",
                  "description": "Date and time when the object was last updated",
                  "format": "date-time",
                  "example": "2025-01-02T09:35:39.032Z"
                }
              },
              "required": [
                "locationId",
                "id",
                "objectKey",
                "originId",
                "dataType",
                "parentId",
                "fieldKey",
                "dateAdded",
                "dateUpdated"
              ],
              "title": "ICustomField"
            }
          }
        },
        "required": [
          "cache"
        ],
        "title": "CustomObjectByIdResponseDTO"
      },
      "BadRequestDTO": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "example": 400
          },
          "message": {
            "type": "string",
            "example": "Bad Request"
          }
        },
        "title": "BadRequestDTO"
      },
      "UnauthorizedDTO": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "example": 401
          },
          "message": {
            "type": "string",
            "example": "Invalid token: access token is invalid"
          },
          "error": {
            "type": "string",
            "example": "Unauthorized"
          }
        },
        "title": "UnauthorizedDTO"
      },
      "UnprocessableDTO": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "example": 422
          },
          "message": {
            "example": [
              "Unprocessable Entity"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "error": {
            "type": "string",
            "example": "Unprocessable Entity"
          }
        },
        "title": "UnprocessableDTO"
      }
    }
  }
}
```

## HighLevel SDK Examples

**Node.js** (`@gohighlevel/api-client`)

```javascript
import HighLevel from '@gohighlevel/api-client';

const ghl = new HighLevel({
  privateIntegrationToken: '<PRIVATE_INTEGRATION_TOKEN>'
});

const response = await ghl.objects.getObjectSchemaByKeyId('<KEY>', { locationId: '<LOCATIONID>' });
console.log(response);
```

**Python** (`gohighlevel-api-client`)

```python
from highlevel import HighLevel

client = HighLevel(
    private_integration_token='<PRIVATE_INTEGRATION_TOKEN>'
)

response = await client.objects.get_object_schema_by_key_id('<KEY>', locationId='<LOCATIONID>')
print(response)
```

**PHP** (`gohighlevel/api-client`)

```php
<?php
require_once 'vendor/autoload.php';

use HighLevel\HighLevel;
use HighLevel\HighLevelConfig;

$config = new HighLevelConfig([
    'privateIntegrationToken' => '<PRIVATE_INTEGRATION_TOKEN>'
]);
$ghl = new HighLevel($config);

$response = $ghl->objects->getObjectSchemaByKeyId('<KEY>', ['locationId' => '<LOCATIONID>']);
echo json_encode($response, JSON_PRETTY_PRINT);
```

## Code Examples

**cURL**

```bash
curl -L -X GET 'https://services.leadconnectorhq.com/objects/<key>?locationId=<LOCATIONID>' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Version: 2021-07-28'
```

**Node.js**

```javascript
const options = {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <TOKEN>',
    Version: '2021-07-28'
  }
};

try {
  const response = await fetch('https://services.leadconnectorhq.com/objects/<key>?locationId=<LOCATIONID>', options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**Python**

```python
import requests

url = "https://services.leadconnectorhq.com/objects/{key}"

headers = {
    "Authorization": "Bearer <TOKEN>",
    "Version": "2021-07-28"
}

params = {
    "locationId": "<LOCATIONID>"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())
```

**PHP**

```php
<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://services.leadconnectorhq.com/objects/<key>?locationId=<LOCATIONID>',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <TOKEN>',
    'Version: 2021-07-28',
  ],
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;
```

**Java**

```java
HttpResponse<String> response = Unirest
  .get("https://services.leadconnectorhq.com/objects/<key>?locationId=<LOCATIONID>")
  .header("Authorization", "Bearer <TOKEN>")
  .header("Version", "2021-07-28")
  .asString();
```

**Go**

```go
package main

import (
  "fmt"
  "net/http"
  "io"
)

func main() {
  url := "https://services.leadconnectorhq.com/objects/<key>?locationId=<LOCATIONID>"
  req, _ := http.NewRequest("GET", url, nil)
  req.Header.Add("Authorization", "Bearer <TOKEN>")
  req.Header.Add("Version", "2021-07-28")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  fmt.Println(string(body))
}
```

**Ruby**

```ruby
require 'uri'
require 'net/http'

url = URI("https://services.leadconnectorhq.com/objects/<key>?locationId=<LOCATIONID>")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = "Bearer <TOKEN>"
request["Version"] = "2021-07-28"

response = http.request(request)
puts response.read_body
```

**PowerShell**

```powershell
$headers = @{
  "Authorization" = "Bearer <TOKEN>"
  "Version" = "2021-07-28"
}

$response = Invoke-RestMethod -Uri 'https://services.leadconnectorhq.com/objects/<key>?locationId=<LOCATIONID>' -Method 'GET' -Headers $headers
$response | ConvertTo-Json
```