# List and Search Objects API {% hint style="success" %} **Audience:** Developers and Solution Architects **Purpose:** Explains how to retrieve and work with a list of space.vars.objects programmatically, as well as search for space.vars.objects and space.vars.object identifiers. {% endhint %} ## Overview Use the **List and Search Objects** endpoints allows you to retrieve and query space.vars.objects in your Business. You can use them to enumerate all available space.vars.objects or to search for specific space.vars.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 space.vars.objects exist, retrieve space.vars.object identifiers and metadata, and support schema-aware integrations, admin tooling, and dynamic configuration flows—without relying on hard-coded space.vars.object IDs. The material on this page builds on information covered in [Objects Core Concepts](/docs/concepts/objects/object-core-concepts.md) and the [Object Data Model](/docs/concepts/objects/object-data-model.md). {% hint style="info" %} **Note:** To retrieve full details for a specific space.vars.object, such as fields, relationships, layouts, and configuration, use the [Retrieve Object Details by ID API](/docs/concepts/objects/object-apis/retrieve-object-details-by-id-api.md) endpoint. {% endhint %} ### Why Would I Use These APIs Use these endpoints when your integration needs to discover or validate space.vars.objects programmatically. Common scenarios include: * Discovering which space.vars.objects exist before querying or syncing space.vars.entities * Initializing integrations across multiple businesses with different schemas * Populating space.vars.object selectors in external tools or admin interfaces * Retrieving space.vars.object identifiers (`custom_object_id`, `object_name`) for downstream API calls * Supporting dynamic, schema-aware integrations * Filtering or sorting space.vars.objects by type, usage, or system behavior (for example, workflow vs standard space.vars.objects) * Validating space.vars.object availability before performing operations Because space.vars.object configurations can vary between environments, listing and searching space.vars.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 space.vars.objects based on their current schema configuration * Results include high-level space.vars.object metadata only, not field or relationship definitions * space.vars.objects may represent standard or workflow schemas * Only space.vars.objects are returned by default * To include default objects (such as space.vars.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 (space.vars.entities, fields, relationships) * Each result corresponds to a single space.vars.object definition and includes identifiers and flags that describe how the space.vars.object behaves across the platform * Does not return space.vars.entity data stored within space.vars.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](https://app.go.kizen.com/api/docs/public/swagger#/custom-objects/custom_objects_list) docs. ## GET /api/custom-objects > Custom objects ```json {"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"security":[{"businessId":[],"userId":[],"apiKey":[]}],"components":{"securitySchemes":{"businessId":{"type":"apiKey","in":"header","name":"X-BUSINESS-ID"}},"schemas":{"PaginatedCustomMinimalObjectsListList":{"type":"object","required":["count","results"],"properties":{"count":{"type":"integer"},"next":{"type":"string","nullable":true,"format":"uri"},"previous":{"type":"string","nullable":true,"format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/CustomMinimalObjectsList"}},"errors":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"string"}}]}}},"CustomMinimalObjectsList":{"type":"object","properties":{"fetch_url":{"type":"string"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"object_type":{"$ref":"#/components/schemas/ObjectTypeEnum"},"object_name":{"type":"string"},"entity_name":{"type":"string"},"rollup_related_leadsources":{"type":"boolean"},"association_source":{"$ref":"#/components/schemas/AssociationSourceEnum"},"has_commerce_data":{"type":"boolean"},"default_on_activities":{"type":"boolean"},"owner":{"$ref":"#/components/schemas/OwnerRead"},"description":{"type":"string"},"is_custom":{"type":"boolean"},"allow_relations":{"type":"boolean"},"created":{"type":"string","format":"date-time"},"access":{"$ref":"#/components/schemas/AccessSerpy"},"track_entity_value":{"type":"boolean"},"include_percentage_to_close":{"type":"boolean"},"use_ai_to_update_percentage":{"type":"boolean"},"ai_confidence_threshold":{"type":"string","format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$"},"allow_on_forms":{"type":"boolean"},"default_color":{"type":"string"},"default_icon":{"type":"string"}},"required":["access","ai_confidence_threshold","allow_on_forms","allow_relations","association_source","created","default_color","default_icon","default_on_activities","description","entity_name","fetch_url","has_commerce_data","id","include_percentage_to_close","is_custom","name","object_name","object_type","owner","rollup_related_leadsources","track_entity_value","use_ai_to_update_percentage"]},"ObjectTypeEnum":{"enum":["pipeline","standard"],"type":"string","description":"* `pipeline` - pipeline\n* `standard` - standard"},"AssociationSourceEnum":{"enum":["direct","related","direct_and_related"],"type":"string","description":"* `direct` - Direct\n* `related` - Related\n* `direct_and_related` - Direct and Related"},"OwnerRead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"full_name":{"type":"string"},"picture":{"$ref":"#/components/schemas/S3ObjectRead"}},"required":["email","first_name","full_name","id","last_name","picture"]},"S3ObjectRead":{"type":"object","properties":{"id":{"type":"string"},"created":{"type":"string","format":"date-time"},"key":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"thumbnail_url":{"type":"string"},"size_bytes":{"type":"string"},"content_type":{"type":"string"},"size_formatted":{"type":"string"},"is_public":{"type":"boolean"}},"required":["content_type","created","id","is_public","key","name","size_bytes","size_formatted","thumbnail_url","url"]},"AccessSerpy":{"type":"object","properties":{"view":{"type":"boolean"},"edit":{"type":"boolean"},"remove":{"type":"boolean"}},"required":["edit","remove","view"]}}},"paths":{"/api/custom-objects":{"get":{"operationId":"custom_objects_list","description":"Custom objects","parameters":[{"in":"query","name":"allow_relations","schema":{"type":"boolean"}},{"in":"query","name":"custom_only","schema":{"type":"boolean","default":true},"description":"Filter Custom Objects for the Client object (is_custom field)"},{"in":"query","name":"default_on_activities","schema":{"type":"boolean"}},{"in":"query","name":"is_custom","schema":{"type":"boolean"}},{"in":"query","name":"name","schema":{"type":"string"}},{"in":"query","name":"object_name","schema":{"type":"string"}},{"in":"query","name":"object_type","schema":{"type":"string","enum":["pipeline","standard"]},"description":"* `pipeline` - pipeline\n* `standard` - standard"},{"in":"query","name":"ordering","schema":{"type":"string","enum":["created","entity_name","number_of_records","object_name","object_type","total_commerce_value","total_pipeline_value","updated"]},"description":"Which field to use when ordering the results. Prepend with '-' for descending order."},{"name":"page","required":false,"in":"query","description":"A page number within the paginated result set.","schema":{"type":"integer"}},{"name":"page_size","required":false,"in":"query","description":"Number of results to return per page.","schema":{"type":"integer"}},{"name":"search","required":false,"in":"query","description":"A search term.","schema":{"type":"string"}}],"tags":["custom-objects"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCustomMinimalObjectsListList"}}},"description":""}}}}}} ``` ### List Objects API Schemas ## The PaginatedCustomMinimalObjectsListList object ```json {"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"PaginatedCustomMinimalObjectsListList":{"type":"object","required":["count","results"],"properties":{"count":{"type":"integer"},"next":{"type":"string","nullable":true,"format":"uri"},"previous":{"type":"string","nullable":true,"format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/CustomMinimalObjectsList"}},"errors":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"string"}}]}}},"CustomMinimalObjectsList":{"type":"object","properties":{"fetch_url":{"type":"string"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"object_type":{"$ref":"#/components/schemas/ObjectTypeEnum"},"object_name":{"type":"string"},"entity_name":{"type":"string"},"rollup_related_leadsources":{"type":"boolean"},"association_source":{"$ref":"#/components/schemas/AssociationSourceEnum"},"has_commerce_data":{"type":"boolean"},"default_on_activities":{"type":"boolean"},"owner":{"$ref":"#/components/schemas/OwnerRead"},"description":{"type":"string"},"is_custom":{"type":"boolean"},"allow_relations":{"type":"boolean"},"created":{"type":"string","format":"date-time"},"access":{"$ref":"#/components/schemas/AccessSerpy"},"track_entity_value":{"type":"boolean"},"include_percentage_to_close":{"type":"boolean"},"use_ai_to_update_percentage":{"type":"boolean"},"ai_confidence_threshold":{"type":"string","format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$"},"allow_on_forms":{"type":"boolean"},"default_color":{"type":"string"},"default_icon":{"type":"string"}},"required":["access","ai_confidence_threshold","allow_on_forms","allow_relations","association_source","created","default_color","default_icon","default_on_activities","description","entity_name","fetch_url","has_commerce_data","id","include_percentage_to_close","is_custom","name","object_name","object_type","owner","rollup_related_leadsources","track_entity_value","use_ai_to_update_percentage"]},"ObjectTypeEnum":{"enum":["pipeline","standard"],"type":"string","description":"* `pipeline` - pipeline\n* `standard` - standard"},"AssociationSourceEnum":{"enum":["direct","related","direct_and_related"],"type":"string","description":"* `direct` - Direct\n* `related` - Related\n* `direct_and_related` - Direct and Related"},"OwnerRead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"full_name":{"type":"string"},"picture":{"$ref":"#/components/schemas/S3ObjectRead"}},"required":["email","first_name","full_name","id","last_name","picture"]},"S3ObjectRead":{"type":"object","properties":{"id":{"type":"string"},"created":{"type":"string","format":"date-time"},"key":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"thumbnail_url":{"type":"string"},"size_bytes":{"type":"string"},"content_type":{"type":"string"},"size_formatted":{"type":"string"},"is_public":{"type":"boolean"}},"required":["content_type","created","id","is_public","key","name","size_bytes","size_formatted","thumbnail_url","url"]},"AccessSerpy":{"type":"object","properties":{"view":{"type":"boolean"},"edit":{"type":"boolean"},"remove":{"type":"boolean"}},"required":["edit","remove","view"]}}}} ``` ## The CustomMinimalObjectsList object ```json {"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"CustomMinimalObjectsList":{"type":"object","properties":{"fetch_url":{"type":"string"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"object_type":{"$ref":"#/components/schemas/ObjectTypeEnum"},"object_name":{"type":"string"},"entity_name":{"type":"string"},"rollup_related_leadsources":{"type":"boolean"},"association_source":{"$ref":"#/components/schemas/AssociationSourceEnum"},"has_commerce_data":{"type":"boolean"},"default_on_activities":{"type":"boolean"},"owner":{"$ref":"#/components/schemas/OwnerRead"},"description":{"type":"string"},"is_custom":{"type":"boolean"},"allow_relations":{"type":"boolean"},"created":{"type":"string","format":"date-time"},"access":{"$ref":"#/components/schemas/AccessSerpy"},"track_entity_value":{"type":"boolean"},"include_percentage_to_close":{"type":"boolean"},"use_ai_to_update_percentage":{"type":"boolean"},"ai_confidence_threshold":{"type":"string","format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$"},"allow_on_forms":{"type":"boolean"},"default_color":{"type":"string"},"default_icon":{"type":"string"}},"required":["access","ai_confidence_threshold","allow_on_forms","allow_relations","association_source","created","default_color","default_icon","default_on_activities","description","entity_name","fetch_url","has_commerce_data","id","include_percentage_to_close","is_custom","name","object_name","object_type","owner","rollup_related_leadsources","track_entity_value","use_ai_to_update_percentage"]},"ObjectTypeEnum":{"enum":["pipeline","standard"],"type":"string","description":"* `pipeline` - pipeline\n* `standard` - standard"},"AssociationSourceEnum":{"enum":["direct","related","direct_and_related"],"type":"string","description":"* `direct` - Direct\n* `related` - Related\n* `direct_and_related` - Direct and Related"},"OwnerRead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"full_name":{"type":"string"},"picture":{"$ref":"#/components/schemas/S3ObjectRead"}},"required":["email","first_name","full_name","id","last_name","picture"]},"S3ObjectRead":{"type":"object","properties":{"id":{"type":"string"},"created":{"type":"string","format":"date-time"},"key":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"thumbnail_url":{"type":"string"},"size_bytes":{"type":"string"},"content_type":{"type":"string"},"size_formatted":{"type":"string"},"is_public":{"type":"boolean"}},"required":["content_type","created","id","is_public","key","name","size_bytes","size_formatted","thumbnail_url","url"]},"AccessSerpy":{"type":"object","properties":{"view":{"type":"boolean"},"edit":{"type":"boolean"},"remove":{"type":"boolean"}},"required":["edit","remove","view"]}}}} ``` *** ## Search Objects API Endpoint Want to try the API out? Visit our [Swagger](https://app.go.kizen.com/api/docs/public/swagger#/custom-objects/custom_objects_search_create) docs. ## POST /api/custom-objects/search > Search custom objects ```json {"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"security":[{"businessId":[],"userId":[],"apiKey":[]}],"components":{"securitySchemes":{"businessId":{"type":"apiKey","in":"header","name":"X-BUSINESS-ID"}},"schemas":{"CustomObjectSearchPayloadRequest":{"type":"object","properties":{"object_ids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"PaginatedCustomMinimalObjectsListList":{"type":"object","required":["count","results"],"properties":{"count":{"type":"integer"},"next":{"type":"string","nullable":true,"format":"uri"},"previous":{"type":"string","nullable":true,"format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/CustomMinimalObjectsList"}},"errors":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"string"}}]}}},"CustomMinimalObjectsList":{"type":"object","properties":{"fetch_url":{"type":"string"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"object_type":{"$ref":"#/components/schemas/ObjectTypeEnum"},"object_name":{"type":"string"},"entity_name":{"type":"string"},"rollup_related_leadsources":{"type":"boolean"},"association_source":{"$ref":"#/components/schemas/AssociationSourceEnum"},"has_commerce_data":{"type":"boolean"},"default_on_activities":{"type":"boolean"},"owner":{"$ref":"#/components/schemas/OwnerRead"},"description":{"type":"string"},"is_custom":{"type":"boolean"},"allow_relations":{"type":"boolean"},"created":{"type":"string","format":"date-time"},"access":{"$ref":"#/components/schemas/AccessSerpy"},"track_entity_value":{"type":"boolean"},"include_percentage_to_close":{"type":"boolean"},"use_ai_to_update_percentage":{"type":"boolean"},"ai_confidence_threshold":{"type":"string","format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$"},"allow_on_forms":{"type":"boolean"},"default_color":{"type":"string"},"default_icon":{"type":"string"}},"required":["access","ai_confidence_threshold","allow_on_forms","allow_relations","association_source","created","default_color","default_icon","default_on_activities","description","entity_name","fetch_url","has_commerce_data","id","include_percentage_to_close","is_custom","name","object_name","object_type","owner","rollup_related_leadsources","track_entity_value","use_ai_to_update_percentage"]},"ObjectTypeEnum":{"enum":["pipeline","standard"],"type":"string","description":"* `pipeline` - pipeline\n* `standard` - standard"},"AssociationSourceEnum":{"enum":["direct","related","direct_and_related"],"type":"string","description":"* `direct` - Direct\n* `related` - Related\n* `direct_and_related` - Direct and Related"},"OwnerRead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"full_name":{"type":"string"},"picture":{"$ref":"#/components/schemas/S3ObjectRead"}},"required":["email","first_name","full_name","id","last_name","picture"]},"S3ObjectRead":{"type":"object","properties":{"id":{"type":"string"},"created":{"type":"string","format":"date-time"},"key":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"thumbnail_url":{"type":"string"},"size_bytes":{"type":"string"},"content_type":{"type":"string"},"size_formatted":{"type":"string"},"is_public":{"type":"boolean"}},"required":["content_type","created","id","is_public","key","name","size_bytes","size_formatted","thumbnail_url","url"]},"AccessSerpy":{"type":"object","properties":{"view":{"type":"boolean"},"edit":{"type":"boolean"},"remove":{"type":"boolean"}},"required":["edit","remove","view"]}}},"paths":{"/api/custom-objects/search":{"post":{"operationId":"custom_objects_search_create","description":"Search custom objects","parameters":[{"in":"query","name":"allow_relations","schema":{"type":"boolean"}},{"in":"query","name":"custom_only","schema":{"type":"boolean","default":true},"description":"Filter Custom Objects for the Client object (is_custom field)"},{"in":"query","name":"default_on_activities","schema":{"type":"boolean"}},{"in":"query","name":"is_custom","schema":{"type":"boolean"}},{"in":"query","name":"name","schema":{"type":"string"}},{"in":"query","name":"object_name","schema":{"type":"string"}},{"in":"query","name":"object_type","schema":{"type":"string","enum":["pipeline","standard"]},"description":"* `pipeline` - pipeline\n* `standard` - standard"},{"in":"query","name":"ordering","schema":{"type":"string","enum":["created","entity_name","number_of_records","object_name","object_type","total_commerce_value","total_pipeline_value","updated"]},"description":"Which field to use when ordering the results. Prepend with '-' for descending order."},{"name":"page","required":false,"in":"query","description":"A page number within the paginated result set.","schema":{"type":"integer"}},{"name":"page_size","required":false,"in":"query","description":"Number of results to return per page.","schema":{"type":"integer"}},{"name":"search","required":false,"in":"query","description":"A search term.","schema":{"type":"string"}}],"tags":["custom-objects"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomObjectSearchPayloadRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCustomMinimalObjectsListList"}}},"description":""}}}}}} ``` ### Search Objects API Schemas ## The CustomObjectSearchPayloadRequest object ```json {"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"CustomObjectSearchPayloadRequest":{"type":"object","properties":{"object_ids":{"type":"array","items":{"type":"string","format":"uuid"}}}}}}} ``` *** ## What's Next? After retrieving space.vars.objects via the API, you can: * Retrieve full space.vars.object details to inspect schema configuration, including fields and relationships * Retrieve space.vars.object fields to understand available data structures and validation rules * Query, create, or update space.vars.entities using validated space.vars.object identifiers * Use space.vars.object identifiers when configuring integrations, space.vars.automations * Combine space.vars.object metadata with field and option APIs to build dynamic, schema-aware integrations * Work with related APIs that depend on space.vars.object schemas For more information on space.vars.objects, check out the following topics:
Related Topics * [Objects](/docs/concepts/objects.md) * [Object APIs](/docs/concepts/objects/object-apis.md) * [Object API Names](/docs/concepts/objects/object-apis/object-api-names.md) * [Retrieve Object Details by ID API](/docs/concepts/objects/object-apis/retrieve-object-details-by-id-api.md) * [Retrieve Object Field Options API](/docs/concepts/objects/custom-fields/custom-field-apis/retrieve-object-field-options-api.md)
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.kizen.com/docs/concepts/objects/object-apis/list-and-search-objects-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.