---
title: "Find objects"
method: POST
path: "/v1/objects"
tags: ["Objects"]
---

# Find objects

`POST /v1/objects`

Use a set of filter conditions to find objects in your workspace. Returns a list of object IDs that you can use to look up object attributes, or to create or modify objects.

The list is paged if you have a large number of objects. You can set the `limit` for the number of objects returned, and use the `start` to page through the results. It's possible that you'll see duplicate entries across pages. If you want to export objects or relationships, you may want to use the export feature in our UI to return complete results.

## Query parameters

- `start` string
- `limit` integer

## Request body

- object
  - `object_type_id` string, required — The type of object you want to search in. Object type IDs are integers passed as strings.
  - `filter` union, required — Use `and`, `or`, and `not` to combine object attribute conditions. The top-level object accepts one property; nest groups for complex filters.
    - object
      - `and` object[] — Match *all* conditions to return results.
        - `object_attribute` ObjectattributeFilter — Filter your objects by their attributes.
          - `field` string, required — The name of the attribute you want to filter against.
          - `operator` 'eq' | 'exists', required — Determine how to evaluate criteria against the field—`exists` returns results if an object has the attribute; `eq` returns results an object's attribute exists and the attribute has the `value` you specify.
          - `value` string — The value you want to match for this attribute. You must include a value if you use the `eq` operator.
          - `type_id` string, required — The object type an object belongs to—like "Companies" or "Accounts". Object type IDs are string-formatted integers that begin at `1` and increment for each new type.
    - object
      - `or` object[] — Match *any* condition to return results.
        - `object_attribute` ObjectattributeFilter — Filter your objects by their attributes.
          - `field` string, required — The name of the attribute you want to filter against.
          - `operator` 'eq' | 'exists', required — Determine how to evaluate criteria against the field—`exists` returns results if an object has the attribute; `eq` returns results an object's attribute exists and the attribute has the `value` you specify.
          - `value` string — The value you want to match for this attribute. You must include a value if you use the `eq` operator.
          - `type_id` string, required — The object type an object belongs to—like "Companies" or "Accounts". Object type IDs are string-formatted integers that begin at `1` and increment for each new type.
    - object
      - `not` object — Returns results if a condition is false. While and/or support an array of items, `not` supports a single condition.
        - `object_attribute` ObjectattributeFilter — Filter your objects by their attributes.
          - `field` string, required — The name of the attribute you want to filter against.
          - `operator` 'eq' | 'exists', required — Determine how to evaluate criteria against the field—`exists` returns results if an object has the attribute; `eq` returns results an object's attribute exists and the attribute has the `value` you specify.
          - `value` string — The value you want to match for this attribute. You must include a value if you use the `eq` operator.
          - `type_id` string, required — The object type an object belongs to—like "Companies" or "Accounts". Object type IDs are string-formatted integers that begin at `1` and increment for each new type.
    - object — A simple filter to find objects matching an attribute condition.
      - `object_attribute` ObjectattributeFilter — Filter your objects by their attributes.
        - `field` string, required — The name of the attribute you want to filter against.
        - `operator` 'eq' | 'exists', required — Determine how to evaluate criteria against the field—`exists` returns results if an object has the attribute; `eq` returns results an object's attribute exists and the attribute has the `value` you specify.
        - `value` string — The value you want to match for this attribute. You must include a value if you use the `eq` operator.
        - `type_id` string, required — The object type an object belongs to—like "Companies" or "Accounts". Object type IDs are string-formatted integers that begin at `1` and increment for each new type.

## Response `200`

Returns arrays of `identifiers` and `ids`.

- object
  - `identifiers` object[]
    - `cio_object_id` string — The canonical, immutable identifier for the object, assigned by Customer.io.
    - `object_id` string — The ID of the object, assigned by you or your systems.
  - `ids` string[] — A list of object IDs matching the object_type_id and filter in the request. Items are the same as the `object_id` values under `identifiers`, but this array may be easier to search/sort through if you have a large number of objects and don't need to to use the `cio_object_id`.
  - `next` string — Indicates the next page of results. Add `?start=<next_value>` to the request to get the next page of results.

## Other responses

- `401` — Unauthorized request. Make sure that you provided the right credentials.
- `429` — Your request is over the 10-per-second limit.

---

[API](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference.md) · [All operations](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/customer/customer-io-journeys-api-reference/revisions/4b391af7cb06/schema)