Search Custom Object Fields API

Audience: Developers and Integration Engineers

Purpose: Explains how to retrieve filtered field metadata for a specific Object without requesting full Object configuration details

Overview

Use the Search for Custom Object Fields endpoint to retrieve field definitions for a specific custom Object using structured query criteria.

This endpoint supports schema discovery and schema-aware integrations by enabling external systems to locate fields by type or configuration, validate field availability, and retrieve field-level metadata without loading full Object details. Because field configurations may vary across Objects or environments, searching fields dynamically helps integrations remain adaptable and efficient.

Unlike the Retrieve Object Details by ID API, this endpoint focuses exclusively on field-level metadata and supports filtering to reduce response size and improve performance.

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

Why Use This API?

You can use the Search Custom Object Fields API when you need to:

• Dynamically retrieve field metadata for a specific Object

• Identify fields by type (e.g., dropdown, relationship, money, date)

• Validate that required fields exist before sending record updates

• Confirm whether fields allow null or empty values

• Retrieve only numeric fields for reporting or calculations

• Filter fields by category for UI rendering or form generation

• Reduce payload size when full Object configuration is unnecessary

• Build schema-aware integrations that adapt to configuration changes

This endpoint is especially useful when your integration needs precise field-level metadata without loading layouts, pipelines, related Objects, or other Object-level configuration details.

Search for Custom Object Fields API Behavior

The Search for Custom Object Fields endpoint searches for fields within a single custom Object and returns only the matching field definitions. The search is limited to the specified object_pk. It does not return object-level details such as layouts, pipelines, related Objects, or actions.

Results are returned as a simple array of field Objects (not paginated). You can use query parameters to filter by:

• Field type

• Category

• Default status

• Numeric fields

• Text search

The response format is the same field metadata structure returned by the Custom Object Detail endpoint, but filtered to include only the fields that match your search criteria.

---

Search for Custom Object Fields Endpoint

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

post

Search fields

Authorizations

apiKey & businessId & userId

X-API-KEYstringRequired

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

Path parameters

object_pkstringRequired

Query parameters

categorystring · uuidOptional

field_typestring · enumOptional

• checkbox - Checkbox
• checkboxes - Checkboxes
• choices - Choices
• date - Date
• datetime - Datetime
• decimal - Decimal Number
• dropdown - Dropdown
• dynamictags - Dynamic Tags
• email - Email
• files - Files
• integer - Whole Number
• longtext - Long Text
• money - Money
• phonenumber - Phone Number
• radio - Radio
• rating - Rating
• relationship - Relationship
• selector - Selector
• status - Status
• team_selector - Team Selector
• text - Text
• timezone - Timezone
• wysiwyg - Wysiwyg
• yesnomaybe - Yes / No / Maybe Question

Possible values:

field_type__instring[]Optional

Multiple values may be separated by commas.

is_defaultbooleanOptional

numericbooleanOptional

orderingstring · enumOptional

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

Possible values:

searchstringOptional

A search term.

Body

application/json

idstring · uuidRequired

namestring · min: 1Required

categorystring · uuidRequired

display_namestring · min: 1Required

canonical_display_namestring · min: 1Required

is_defaultbooleanRequired

field_typestring · enumRequired

• checkbox - Checkbox
• checkboxes - Checkboxes
• choices - Choices
• date - Date
• datetime - Datetime
• decimal - Decimal Number
• dropdown - Dropdown
• dynamictags - Dynamic Tags
• email - Email
• files - Files
• integer - Whole Number
• longtext - Long Text
• money - Money
• phonenumber - Phone Number
• radio - Radio
• rating - Rating
• relationship - Relationship
• selector - Selector
• status - Status
• team_selector - Team Selector
• text - Text
• timezone - Timezone
• wysiwyg - Wysiwyg
• yesnomaybe - Yes / No / Maybe Question

Possible values:

is_requiredbooleanRequired

is_read_onlybooleanRequired

is_hiddenbooleanRequired

is_deletablebooleanRequired

is_hideablebooleanRequired

is_suppressedbooleanRequired

include_in_short_formstring · min: 1Required

allows_nullsbooleanRequired

allows_emptybooleanRequired

orderintegerRequired

descriptionstring · min: 1Required

description_visibilitystring · enumRequired

• all - All Labels
• create_only - Only on Create
• settings_only - Only in Settings

Possible values:

allow_on_formsbooleanRequired

Responses

200Success

application/json

idstring · uuidRequired

namestringRequired

categorystring · uuidRequired

display_namestringRequired

canonical_display_namestringRequired

is_defaultbooleanRequired

field_typestring · enumRequired

• checkbox - Checkbox
• checkboxes - Checkboxes
• choices - Choices
• date - Date
• datetime - Datetime
• decimal - Decimal Number
• dropdown - Dropdown
• dynamictags - Dynamic Tags
• email - Email
• files - Files
• integer - Whole Number
• longtext - Long Text
• money - Money
• phonenumber - Phone Number
• radio - Radio
• rating - Rating
• relationship - Relationship
• selector - Selector
• status - Status
• team_selector - Team Selector
• text - Text
• timezone - Timezone
• wysiwyg - Wysiwyg
• yesnomaybe - Yes / No / Maybe Question

Possible values:

is_requiredbooleanRequired

is_read_onlybooleanRequired

is_hiddenbooleanRequired

is_deletablebooleanRequired

is_hideablebooleanRequired

is_suppressedbooleanRequired

include_in_short_formstringRequired

allows_nullsbooleanRequired

allows_emptybooleanRequired

orderintegerRequired

descriptionstringRequired

description_visibilitystring · enumRequired

• all - All Labels
• create_only - Only on Create
• settings_only - Only in Settings

Possible values:

allow_on_formsbooleanRequired

post

/api/custom-objects/{object_pk}/fields/search

HTTPcURLJavaScriptPython

POST /api/custom-objects/{object_pk}/fields/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: 1188

{
  "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_object": "123e4567-e89b-12d3-a456-426614174000",
    "related_category": "123e4567-e89b-12d3-a456-426614174000",
    "related_name": "text",
    "relation_type": "one_to_one",
    "rollup_timeline": true,
    "rollup_leadsources": true,
    "inverse_relation_rollup_timeline": true,
    "inverse_relation_rollup_leadsources": true,
    "inverse_relation_suppressed": true
  },
  "allow_on_forms": true
}

200Success

[
  {
    "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
  }
]

Search for Custom Object Fields Schema

---

What's Next?

After retrieving field metadata with this API, you can:

• Retrieve full object configuration (including categories and all fields) when you need broader schema context.

• Retrieve selectable field option values (for dropdowns, dynamic tags, radio buttons, and checkboxes) so your integration can validate allowed values.

• Use field IDs and names to safely read or write field values on records.

• Explore the Custom Fields and schema metadata docs to understand field behaviors, constraints, and mapping best practices.

Continue learning about field types with the following resources:

Related Topics

• Object APIs

• Object API Names

• Retrieve Object Details API

• Retrieve Object Field Options API

---