List and Search Objects API

Audience: Developers and Solution Architects

Purpose: Explains how to retrieve and work with a list of Custom Objects programmatically, as well as search for custom 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 Custom 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 Custom 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, pipeline 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 Custom Objects based on their current schema configuration

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

• Objects may represent standard or pipeline schemas

• Only Custom 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

apiKey & businessId & userId

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

get

/api/custom-objects

HTTPcURLJavaScriptPython

GET /api/custom-objects HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
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": "[email protected]",
        "full_name": "text",
        "picture": {
          "id": "text",
          "created": "2026-03-04T00:36:49.505Z",
          "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-03-04T00:36:49.505Z",
      "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

apiKey & businessId & userId

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

application/json

object_idsstring · uuid[]Optional

Responses

200Success

application/json

post

/api/custom-objects/search

HTTPcURLJavaScriptPython

POST /api/custom-objects/search HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
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": "[email protected]",
        "full_name": "text",
        "picture": {
          "id": "text",
          "created": "2026-03-04T00:36:49.505Z",
          "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-03-04T00:36:49.505Z",
      "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 Custom Objects via the API, you can:

• Retrieve full Custom 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 Custom Object identifiers

• Use Custom Object identifiers when configuring integrations, automations, or workflows

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

• Work with related APIs that depend on Custom Object schemas

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

Related Topics

• Objects

• Object APIs

• Object API Names

• Retrieve Object Details by ID API

• Retrieve Object Field Options API