Retrieve Object Details by ID API

Audience: Developers and Solution Architects

Purpose: Explains how to retrieve the full definition of a specific Custom Object by ID so developers can understand its schema, fields, and configuration for use in integrations and workflows.

Overview

Use the Retrieve Custom Object Details by ID endpoint to fetch the complete schema definition for a single Object in your Business. This includes Object-level metadata as well as detailed configuration such as fields, categories, and relationship settings.

This endpoint is designed for schema inspection and integration setup use cases, where an external system needs to understand how a specific Object is structured before interacting with its Records.

The material on this page builds on information covered in the Objects Core Concepts and Object Data Model.

Note: This endpoint returns detailed configuration for one Custom Object only. To retrieve a list of available Custom Objects and their identifiers, use the List Custom Objects endpoint.

Why Would I Use This API?

You can use the Retrieve Custom Object Details by ID API when you need to:

• Inspect the full schema of an Object before querying or writing Records

• Retrieve field definitions and identifiers required for Record-level APIs

• Understand Object configuration, such as categories or relationship capabilities

• Validate Object structure during integration setup or initialization

• Build schema-aware integrations that adapt to different Object configurations

Retrieve Custom Object Details API behavior

Use this endpoint to retrieve the full definition of a Custom Object by providing its identifier. It:

• Returns the full schema definition for a single Custom Object

• Requires a valid Custom Object ID

• Includes Object metadata, field definitions, and relationship configuration

• Returns schema-level data only; no Record data is included

• Fails if the specified Custom Object ID does not exist or is inaccessible

---

Retrieve Custom Object Details Endpoint

Want to try the API out? Visit our Swagger docs.

get

Custom object with fields and categories

Authorizations

apiKey & businessId & userId

X-API-KEYstringRequired

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

Path parameters

object_pkstring · uuidRequired

Responses

200Success

application/json

idstring · uuidRead-onlyRequired

object_typestring · enumOptional

• pipeline - pipeline
• standard - standard

Possible values:

entity_namestring · max: 200Required

object_namestring · max: 200Required

has_commerce_databooleanOptionalDefault: false

default_on_activitiesbooleanRequired

namestringOptional

descriptionstring · max: 500 · nullableOptional

ai_descriptionstring · nullableRead-onlyRequired

is_custombooleanRead-onlyRequired

fetch_urlstringRead-onlyRequired

allow_relationsbooleanRead-onlyRequired

createdstring · date-timeRead-onlyRequired

entity_accessbooleanRead-onlyRequired

rollup_related_leadsourcesboolean · nullableOptional

quick_filtering_enabledboolean · nullableOptional

association_sourcestring · enumOptional

• direct - Direct
• related - Related
• direct_and_related - Direct and Related

Possible values:

get

/api/custom-objects/{object_pk}/detail

HTTPcURLJavaScriptPython

GET /api/custom-objects/{object_pk}/detail HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
Accept: */*

200Success

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "object_type": "pipeline",
  "entity_name": "text",
  "object_name": "text",
  "has_commerce_data": false,
  "default_on_activities": true,
  "owner": {
    "picture_url": "text",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "first_name": "text",
    "last_name": "text",
    "email": "[email protected]",
    "display_name": "text"
  },
  "name": "text",
  "description": "text",
  "ai_description": "text",
  "is_custom": true,
  "fetch_url": "text",
  "allow_relations": true,
  "meta": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "related_objects": [
    {
      "related_object": "123e4567-e89b-12d3-a456-426614174000",
      "relation_type": "one_to_one",
      "rollup_timeline": false,
      "rollup_leadsources": true,
      "object_type": "text",
      "object_name": "text",
      "entity_name": "text",
      "field_id": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "created": "2026-03-04T00:36:44.523Z",
  "access": {
    "view": true,
    "edit": true,
    "remove": true
  },
  "entity_access": true,
  "rollup_related_leadsources": true,
  "quick_filtering_enabled": true,
  "record_layouts": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "config": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "tabs": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "order": 1
    }
  ],
  "association_source": "direct",
  "association_source_fields": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "related_field": "text",
      "related_object": "text"
    }
  ],
  "field_categories": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "order": 1
    }
  ],
  "fields": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "category": "123e4567-e89b-12d3-a456-426614174000",
      "display_name": "text",
      "canonical_display_name": "text",
      "is_default": true,
      "field_type": "checkbox",
      "is_required": true,
      "is_read_only": true,
      "is_hidden": true,
      "is_deletable": true,
      "is_hideable": true,
      "is_suppressed": true,
      "include_in_short_form": "text",
      "allows_nulls": true,
      "allows_empty": true,
      "order": 1,
      "meta": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "description": "text",
      "description_visibility": "all",
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "access": {
        "view": true,
        "edit": true,
        "remove": true
      },
      "options": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "code": "text",
          "name": "text",
          "order": 1,
          "meta": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "percentage_chance_to_close": 1,
          "chance_to_close_percentage": 1,
          "status": "open"
        }
      ],
      "relation": {
        "related_field": "123e4567-e89b-12d3-a456-426614174000",
        "related_object": "123e4567-e89b-12d3-a456-426614174000",
        "related_category": "123e4567-e89b-12d3-a456-426614174000",
        "related_name": "text",
        "related_object_name": "text",
        "related_object_object_name": "text",
        "related_entity_name": "text",
        "relation_type": "one_to_one",
        "cardinality": "one_to_one",
        "fetch_url": "text",
        "rollup_timeline": true,
        "rollup_leadsources": true,
        "inverse_relation_rollup_timeline": true,
        "inverse_relation_rollup_leadsources": true,
        "inverse_relation_suppressed": true,
        "related_object_default_on_activities": "text"
      },
      "allow_on_forms": true
    }
  ],
  "pipeline": {
    "stages": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "status": "open",
        "percentage_chance_to_close": 1,
        "order": 1
      }
    ],
    "track_entity_value": true,
    "include_percentage_to_close": true,
    "use_ai_to_update_percentage": true
  },
  "browser_js_actions": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "api_name": "text",
      "name": "text",
      "script": "text",
      "plugin_app": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "api_name": "text",
        "base_config": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    }
  ],
  "browser_route_scripts": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "api_name": "text",
      "name": "text",
      "routes": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "script": "text",
      "blocking": true,
      "custom_object": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "object_name": "text"
      },
      "plugin_app": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "api_name": "text",
        "base_config": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    }
  ],
  "custom_actions": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "action": "text",
      "automation": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "api_name": "text",
        "name": "text"
      },
      "order": 1
    }
  ]
}

Retrieve Custom Object Details by ID API Schemas

---

What’s Next?

After retrieving Custom Object details by ID, you can:

• Query, create, or update Records for the object using Records APIs

• Reference field identifiers when constructing Record payloads

• Use Object and field metadata to build schema-aware integrations

• Combine Object schemas with automation or workflow configuration

For more information on Objects , check out the following topics below:

Related Topics

• Object APIs

• Object API Names

• List and Search Objects API

• Retrieve Object Field Options API