Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

List and Search Objects API

Audience: Developers and Solution Architects

Purpose: Explains how to retrieve and work with a list of Objects programmatically, as well as search for Objects and Object identifiers.

Overview

Use the List and Search Objects endpoints allows you to retrieve and query Objects in your Business. You can use them to enumerate all available Objects or to search for specific Objects based on defined criteria, such as name, type, or behavior.

These endpoints are designed for overview and discovery use cases. They enable external systems to identify which Objects exist, retrieve Object identifiers and metadata, and support schema-aware integrations, admin tooling, and dynamic configuration flows—without relying on hard-coded Object IDs.

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

Note: To retrieve full details for a specific Object, such as fields, relationships, layouts, and configuration, use the Retrieve Object Details by ID API endpoint.

Why Would I Use These APIs

Use these endpoints when your integration needs to discover or validate Objects programmatically.

Common scenarios include:

  • Discovering which Objects exist before querying or syncing Records

  • Initializing integrations across multiple businesses with different schemas

  • Populating Object selectors in external tools or admin interfaces

  • Retrieving Object identifiers (custom_object_id, object_name) for downstream API calls

  • Supporting dynamic, schema-aware integrations

  • Filtering or sorting Objects by type, usage, or system behavior (for example, workflow vs standard Objects)

  • Validating Object availability before performing operations

Because Object configurations can vary between environments, listing and searching Objects programmatically helps ensure integrations remain portable, resilient, and scalable.

List and Search Objects API Behavior

Understanding how these endpoints behave helps prevent common integration mistakes:

  • Returns Objects based on their current schema configuration

  • Results include high-level Object metadata only, not field or relationship definitions

  • Objects may represent standard or workflow schemas

  • Only Objects are returned by default

    • To include default objects (such as Contacts), set custom_only=false

  • Results are paginated and support filtering, searching, and ordering

  • Returned objects can be used immediately as inputs to other APIs (Records, fields, relationships)

  • Each result corresponds to a single Object definition and includes identifiers and flags that describe how the Object behaves across the platform

  • Does not return Record data stored within Objects

These endpoints are commonly used early in the integration lifecycle to establish schema context before performing data operations.

List Objects API Endpoint

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

get

Custom objects

Authorizations
X-API-KEYstringRequired
X-BUSINESS-IDstringRequired
X-USER-IDstringRequired
Query parameters
allow_relationsbooleanOptional
custom_onlybooleanOptional

Filter Custom Objects for the Client object (is_custom field)

Default: true
default_on_activitiesbooleanOptional
is_custombooleanOptional
namestringOptional
object_namestringOptional
object_typestring · enumOptional
  • pipeline - pipeline
  • standard - standard
Possible values:
orderingstring · enumOptional

Which field to use when ordering the results. Prepend with '-' for descending order.

Possible values:
pageintegerOptional

A page number within the paginated result set.

page_sizeintegerOptional

Number of results to return per page.

searchstringOptional

A search term.

Responses
200Success
application/json
countintegerRequiredExample: 123
nextstring · uri · nullableOptionalExample: http://api.example.org/accounts/?page=4
previousstring · uri · nullableOptionalExample: http://api.example.org/accounts/?page=2
errorsstring[] · nullableOptionalExample: ["error message"]
get/api/custom-objects
GET /api/custom-objects HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_BUSINESS_ID
X-USER-ID: YOUR_USER_ID
Accept: */*
200Success
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "fetch_url": "text",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "object_type": "pipeline",
      "object_name": "text",
      "entity_name": "text",
      "rollup_related_leadsources": true,
      "association_source": "direct",
      "has_commerce_data": true,
      "default_on_activities": true,
      "owner": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "first_name": "text",
        "last_name": "text",
        "email": "name@gmail.com",
        "full_name": "text",
        "picture": {
          "id": "text",
          "created": "2026-01-01T00:00:00.000Z",
          "key": "text",
          "name": "text",
          "url": "text",
          "thumbnail_url": "text",
          "size_bytes": "text",
          "content_type": "text",
          "size_formatted": "text",
          "is_public": true
        }
      },
      "description": "text",
      "is_custom": true,
      "allow_relations": true,
      "created": "2026-01-01T00:00:00.000Z",
      "access": {
        "view": true,
        "edit": true,
        "remove": true
      },
      "track_entity_value": true,
      "include_percentage_to_close": true,
      "use_ai_to_update_percentage": true,
      "ai_confidence_threshold": "text",
      "allow_on_forms": true,
      "default_color": "text",
      "default_icon": "text"
    }
  ],
  "errors": [
    "error message"
  ]
}

List Objects API Schemas

Search Objects API Endpoint

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

post

Search custom objects

Authorizations
X-API-KEYstringRequired
X-BUSINESS-IDstringRequired
X-USER-IDstringRequired
Query parameters
allow_relationsbooleanOptional
custom_onlybooleanOptional

Filter Custom Objects for the Client object (is_custom field)

Default: true
default_on_activitiesbooleanOptional
is_custombooleanOptional
namestringOptional
object_namestringOptional
object_typestring · enumOptional
  • pipeline - pipeline
  • standard - standard
Possible values:
orderingstring · enumOptional

Which field to use when ordering the results. Prepend with '-' for descending order.

Possible values:
pageintegerOptional

A page number within the paginated result set.

page_sizeintegerOptional

Number of results to return per page.

searchstringOptional

A search term.

Body
object_idsstring · uuid[]Optional
Responses
200Success
application/json
countintegerRequiredExample: 123
nextstring · uri · nullableOptionalExample: http://api.example.org/accounts/?page=4
previousstring · uri · nullableOptionalExample: http://api.example.org/accounts/?page=2
errorsstring[] · nullableOptionalExample: ["error message"]
post/api/custom-objects/search
POST /api/custom-objects/search HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_BUSINESS_ID
X-USER-ID: YOUR_USER_ID
Content-Type: application/json
Accept: */*
Content-Length: 55

{
  "object_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}
200Success
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "fetch_url": "text",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "object_type": "pipeline",
      "object_name": "text",
      "entity_name": "text",
      "rollup_related_leadsources": true,
      "association_source": "direct",
      "has_commerce_data": true,
      "default_on_activities": true,
      "owner": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "first_name": "text",
        "last_name": "text",
        "email": "name@gmail.com",
        "full_name": "text",
        "picture": {
          "id": "text",
          "created": "2026-01-01T00:00:00.000Z",
          "key": "text",
          "name": "text",
          "url": "text",
          "thumbnail_url": "text",
          "size_bytes": "text",
          "content_type": "text",
          "size_formatted": "text",
          "is_public": true
        }
      },
      "description": "text",
      "is_custom": true,
      "allow_relations": true,
      "created": "2026-01-01T00:00:00.000Z",
      "access": {
        "view": true,
        "edit": true,
        "remove": true
      },
      "track_entity_value": true,
      "include_percentage_to_close": true,
      "use_ai_to_update_percentage": true,
      "ai_confidence_threshold": "text",
      "allow_on_forms": true,
      "default_color": "text",
      "default_icon": "text"
    }
  ],
  "errors": [
    "error message"
  ]
}

Search Objects API Schemas

What's Next?

After retrieving Objects via the API, you can:

  • Retrieve full Object details to inspect schema configuration, including fields and relationships

  • Retrieve Object fields to understand available data structures and validation rules

  • Query, create, or update Records using validated Object identifiers

  • Use Object identifiers when configuring integrations, Agentic Workflows

  • Combine Object metadata with field and option APIs to build dynamic, schema-aware integrations

  • Work with related APIs that depend on Object schemas

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

Related Topics
PreviousObject API Names
NextRetrieve Object Details by ID API

Last updated

Was this helpful?