Customer.io

Object types

Updated August 17, 2026

An object type defines the kind of one-to-many relationship you want to set, like Accounts, Employers, or Job Postings. The first three types appear in the side nav under People. If you have more than three, we’ll nest all of your object types under Custom Objects. Depending on your plan type, you can create 2 or more object types. In our API, we identify object types as integers starting at 1.

The left hand nav is collapsed and the object icon is highlighted underneath the people icon. On the main page, you see a list of objects in a table, each representing a company.

In the example above, the object type is Companies, which has 6 objects/individual companies.

Each object type gets its own object_type_id, and you’ll set an object_id for each object. An object_id must be unique within a type, not across types. For example, object types 1 and 2 could each have an object identifier of a.

Define a custom object type

Remember, an object type helps you differentiate groups of objects. Customer.io generates a unique, immutable object_type_id. You can find this value on the Custom objects page in Workspace Settings. While we define the object_type_id, you define the object_id. You’ll use this value to reference objects belonging to your new type.

Creating objects and types with our API

If you send an API request that includes an object_type_id that doesn’t exist in your workspace, we’ll automatically create a new one for you up to 15 times. We’ll do the same for any object_id that does not exist as well.

  1. Go to Settings > Workspace Settings, and select Custom Objects.

    the list of object types

  2. Click Create Custom Object.

  3. Choose your object type on the left or create your own on the right.

    choose a pre-determined object type on the left or create a new type on the right

  4. Give your object a Name and set the Singular form. In general, we expect that you’ll give objects a plural name (like “Accounts”); we simply use the Singular form to make better sense of your object name in prompts.

    set the name and singular form for your object

    Liquid identifiers for objects

    When you create a new object type, we automatically set the identifier for liquid. This is how you’ll reference objects of this type when personalizing messages with liquid. For example, if your object type is called Accounts, you’d reference objects in the format {{objects.accounts}}. See Use objects in liquid for more information.

  5. Click Save.

API calls create objects and types if they don’t exist

If you send an API request that includes an object_type_id or object_id that doesn’t already exist, we’ll automatically create it for you.

Object types auto-created through our API are disabled by default, but you can enable them if you’re within your plan’s allotment.

If you add an object_type_id or don’t provide one via API, we name it a type of animal. You can set a new Name and liquid tag under Settings > Workspace Settings > Custom Objects.

flowchart LR a[API request]-->b{Does object<br>type exist?} b-->|yes|d{does object ID exist} b-.->|no|c[Create new <code>animal</code><br>object type]-.->d d-->|yes|e[update object<br>& relationships] d-.->|no|f[create new object] c-.->g[Go to UI to change<br>name and liquid tag]

Edit or rename an object type

You can change the name and liquid tag for object types. Changes to the Name and Singular Form affect what you see in Customer.io. Changing the liquid tag could affect your messages.

Is your liquid tag in use?

Messages that reference your liquid tag in active journeys will fail to send after you change your liquid identifier, unless you have a fallback. Before you change your object’s liquid tag, check the Usage field for the object type within Settings > Workspace Settings > Custom Objects. We advise against changing a liquid identifier that’s in use because drafted messages or those triggered between changing the identifier and changing the reference will fail to send.
  1. Go to Settings > Workspace Settings > Custom Objects.
  2. Click Object Name.
  3. Update the Object Type Name, Singular Form and/or Liquid Identifier. Then click Save.

Delete an object type

You can delete an object type through the UI, but not the API at this time.

Deleting an object type also deletes relationships

Deleting an object type permanently deletes all associated objects and relationships to people.

  1. Go to Settings > Workspace Settings > Custom Objects.

  2. Check the Usage of the object type.

    1. You can delete a type when it is no longer in use in segments, automations, broadcasts, snippets, and email layouts.
    There is a field to the right of every object type that reveals how many times an object type is referenced in liquid for automations, broadcasts, and segments.

  3. If needed, adjust usage of your object type.

  4. Check the box beside each object type you want to delete.

    The checkbox to the left of Accounts is checked. A delete button appears at the top of the table.

  5. Select Delete at the top of the table.

  6. Confirm your selection.

You cannot re-use an object type id after it's deleted.

If you create a new object type in the UI, it is automatically assigned a new integer. If you are creating object types programmatically, you must use a new id; we will not create a new object type if the id was previously used/deleted.

Enable/disable an object type

Your plan determines the number of enabled object types you can have. An enabled object type is one you can successfully reference in messaging and segments. You can view all enabled and disabled object types in the side menu.

You can create more than the number of object types allotted by your plan, but you can only enable the count that your plan allows. This grants you the flexibility to create objects and relationships while the object type is disabled so you can enable it shortly after disabling one you no longer need. Object types created over your plan allotment are disabled by default.

You can only disable a type if it is not referenced in any segments or messages.

  1. Go to Settings > Workspace Settings > Custom Objects.

  2. Check the Usage of the object type.

    1. You can disable a type when it is no longer in use in segments, automations, broadcasts, snippets, and email layouts.
    2. You can enable a type as long as you have not surpassed the number of object types allowed in your plan.
    There is a field to the right of every object type that reveals how many times an object type is referenced in liquid for automations, broadcasts, and segments.

  3. If needed, adjust usage of your object type in segments and messages.

  4. Toggle Enable/Disable for the object type.

One object type is enabled and unable to be disabled because it's in use. Another object type is disabled and can be enabled because it's not in use.

Object types auto-created through our API - those without an id or with an id that doesn’t exist yet - are disabled by default, but you can enable them if you’re within your plan’s allotment.