Search 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 Object Fields endpoint to retrieve field definitions for a specific 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 Object Fields API when you need to:

Dynamically retrieve field metadata for a specific Object
Identify fields by type (For Example: 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, workflows, related Objects, or other Object-level configuration details.

Search for Custom Object Fields API Behavior

The Search for 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, workflows, 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 Object Detail endpoint, but filtered to include only the fields that match your search criteria.

Search for Object Fields Endpoint

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

post

Search fields

Authorizations

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

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

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

PreviousCustom Field APIs NextRetrieve Object Field Options API

Last updated 3 months ago

Was this helpful?