> This page is for Unified.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Custom Objects

> How to read, create, and update custom objects (non-standard object types) in CRM integrations through Merge's Custom Object endpoints.

---

## Overview

Read and write data models that are unique to your users' third-party platforms directly through Merge's Unified API, just like Common Models.

Each Custom Object has its own unique properties, schema, and associations to other objects, which are represented through four models:

1. Custom Object Class
2. Custom Object
3. Association Type
4. Association

> **Info**
>
> See [API reference](/crm/custom-objects/) for CRM Custom Objects endpoints.

---

## Custom Object Class

The Custom Object Class contains schema and association types that apply to all instances of the class.

In this example of Custom Object Class **Company Swag**, the schema tells us that all Company Swag instances must have a `swag_name` and a `swag_type` field.

> **Info**
>
> Merge supports **GET** requests for this model. [API reference](https://docs.merge.dev/crm/custom-object-classes/)

**`CustomObjectClass Example`**

```json {10-25} CustomObjectClass Example
{
  "id": "52ce940b-ecfe-43a6-955f-629f799f7f73",
  "remote_id": "123432",
  "custom_object_class_generator_id": "f35a684f-1160-441c-ae58-39f21e30186e",
  "name": "company_swag",
  "labels": {
    "singular": "Company Swag",
    "plural": "Company Swag"
  },
  "fields": [
    {
      "name": "swag_name",
      "label": "Swag Name",
      "type": "string",
      "description": "The company swag's name.",
      "required": true
    },
    {
      "name": "swag_type",
      "label": "Swag Type",
      "type": "string",
      "description": "The company swag's type.",
      "required": true
    }
  ],
  "association_types": [
    "921fad98-80d3-4cb3-ab20-ddb303f6bc21",
    "b7a2afe9-e465-46ca-9ef2-3f5c4b251806",
    "e950e5ac-48e2-404b-8088-e94048a01839"
  ],
  "remote_data": [...]
}
```

---

## Custom Object

A Custom Object refers to an instance of a Custom Object Class. Custom Objects are just like Merge Common Models with their own properties and fields.

Each Custom Object has a property `custom_object_class_id`, which refers to the Custom Object Class of this instance.

In this example, the Merge T-Shirts Custom Object is an instance of the **Company Swag** class with two field values: name **Merge T-Shirts** and type **Clothes**.

> **Info**
>
> Merge supports **GET** and **POST** requests for this model. [API reference](https://docs.merge.dev/crm/custom-object-classes/)

**`CustomObject Example`**

```json {4-8} CustomObject Example
{
  "id": "34837bc6-3458-431a-324d-dcfgcbfdf4fg",
  "remote_id": "18475794",
  "fields": {
    "swag_name": "Merge T-Shirts",
    "swag_type": "Clothes"
  },
  "custom_object_class_id": "06455bc6-6040-431a-848d-dcfgcbfdf4fg",
  "remote_data": [
    {
      "path": "/v3/objects/company_swag",
      "data": [
        "Varies by platform"
      ]
    }
  ],
  "remote_was_deleted": false
}
```

---

## Association Type

The Association Type model represents the relationship between two object classes, a source and a target. These classes can be Custom Object Classes or Common Models.

Each Association Type has a cardinality, which describes the type of relationship between the two classes. Possible cardinalities are: `ONE_TO_ONE`, `ONE_TO_MANY`, `MANY_TO_ONE`, and `MANY_TO_MANY`.

For example, we can represent company swag items that are given to people by creating an Association Type from the source **Company Swag** class to the target **Contact** Common Model.

The Association Type has cardinality `MANY_TO_MANY`, because multiple swag items can be given to multiple people.

> **Info**
>
> Merge supports **GET** and **POST** requests for this model. [API reference](https://docs.merge.dev/crm/custom-object-classes/)

**`AssociationType Example`**

```json {4-13, 16} AssociationType Example
{
  "id": "ab8ceddb-5520-4ec3-aa20-08f63c55add5",
  "remote_id": "abc123",
  "source_object_class": {
    "id": "297428fd-c1fa-47e6-b4a7-6606a7dd071ec",
    "origin_type": "COMPANY_SWAG"
  },
  "target_object_class": [
    {
      "id": "06455bc6-6040-431a-848d-dcfgcbfdf4fg",
      "origin_type": "CONTACT"
    }
  ],
  "name": "lead_to_swag",
  "label": "Swag for Lead",
  "cardinality": "MANY_TO_MANY"
}
```

---

## Association

The Association model describes the relationship between two instances, a source and a target. These two instances can be Custom Objects or Common Model objects.

Each Association has a property `association_type_id`, which refers to the Association Type of this association.

For example, if a Merge T-shirt was given to Hayley, we can represent this relationship with an Association of the Association Type from the previous example with:

1. Source pointing to the **Merge T-Shirts** Custom Object
2. Target pointing to **Hayley's** Contact

> **Info**
>
> Merge supports **GET** and **PATCH** requests for this model. [API reference](https://docs.merge.dev/crm/custom-object-classes/)

**`Association Example`**

```json {3-5} Association Example
{
  model: {
    "source_object_id": "cbeb4bd0-5808-4f03-9511-c4fb2f1180ec",
    "target_object_id": "297428fd-c1fa-47e6-b4a7-6606a7dd071e",
    "association_type_id": "768c2503-0848-4496-89a9-7030516cda86"
  }
}
```