> 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.

# Pulling Remote Field Classes

> How to read Remote Field Class metadata and values. Covers discovering available remote fields and including them in GET requests.

> **Info**
>
> This feature is only available to customers on our **Professional** and **Enterprise** plans. View the [Merge Plans](https://www.merge.dev/pricing) to learn more.

---

## Endpoints and query parameters

| Method  | Endpoint                                               | Description                                                      |
| ------- | ------------------------------------------------------ | ---------------------------------------------------------------- |
| **GET** | `/{common_model_name}/remote-field-classes`            | Read Remote Field Classes for a Common Model                     |
| **GET** | `/{common_model_name}?include_remote_fields=True`      | Read Remote Field Classes and values for a Common Model          |
| **GET** | `/{common_model_name}/{id}?include_remote_fields=True` | Read Remote Field Classes and values for a Common Model instance |

---

## Example

For this example, let's use custom fields set up on the **Contacts** model in Hubspot, which is mapped to the Merge **Contact** Common Model.

We can access Remote Field Classes for Contacts using this endpoint:

**GET** `https://api.merge.dev/api/crm/contacts/remote-field-classes`

### Custom Fields

These two Remote Field Classes in the response are both **custom** fields defined by a Hubspot user, as we can tell from the `is_custom` flag being set to `true`.

The `test_dropdown_custom_field` also has a list of accepted values under `field_choices`.

**`Example response - GET /contacts/remote-field-classes`**

```json Example response - GET /contacts/remote-field-classes
"results": [
  {
    "display_name": "Test String Custom Field",
    "remote_key_name": "test_string_custom_field",
    "description": "Test custom field with a string",
    "is_required": false,
    "field_type": "string",
    "field_format": "text",
    "field_choices": null,
    "item_schema": null,
    "is_custom": true,
    "id": "87dc13db-99d6-4391-9f91-56900e284d92",
    "is_common_model_field": false,
  },
  {
    "display_name": "Test Dropdown Custom Field",
    "remote_key_name": "test_dropdown_custom_field",
    "description": "Test custom field with specific values",
    "is_required": false,
    "field_type": "string",
    "field_format": "select",
    "field_choices": [
      "Option 1",
      "Option 2"
    ],
    "item_schema": null,
    "is_custom": true,
    "id": "9a8f4d23-4c7b-47a9-86d9-c2e8a0f0d84d",
    "is_common_model_field": false,
  }
]
```

### Standard Fields

Meanwhile, these two Remote Field Classes are **standard** fields from Hubspot, as the `is_custom` flag is set to `false`.

**`Example response - GET /contacts/remote-field-classes`**

```json Example response - GET /contacts/remote-field-classes
"results": [
  {
    "display_name": "Latest time in \"Subscriber (Lifecycle Stage Pipeline)\"",
    "remote_key_name": "hs_v2_latest_time_in_subscriber",
    "description": null,
    "is_required": false,
    "field_type": "number",
    "field_format": "number",
    "field_choices": null,
    "item_schema": null,
    "modified_at": "2023-08-03T23:06:12.323009Z",
    "is_custom": false,
    "id": "d3b34c95-257c-4159-8709-a316bfc9f2b5",
    "is_common_model_field": false
  },
  {
    "display_name": "Latest time in \"Sales Qualified Lead (Lifecycle Stage Pipeline)\"",
    "remote_key_name": "hs_v2_latest_time_in_salesqualifiedlead",
    "description": null,
    "is_required": false,
    "field_type": "number",
    "field_format": "number",
    "field_choices": null,
    "item_schema": null,
    "modified_at": "2023-08-03T23:06:12.315781Z",
    "is_custom": false,
    "id": "610ad8ff-1b8b-4781-b158-da8f17a77092",
    "is_common_model_field": false
  }
]
```

### Accessing Field Values

To access Remote Field Classes and values for a specific Contact, use the **include\_remote\_fields=True** query parameter.

This returns all of an object's properties including Remote Field Classes metadata and values.

```json Example response - GET /contacts/{id}?include_remote_fields=True
{
  "first_name": "Gil",
  "last_name": "Feig",
  ...
  ...
  "remote_fields": [
    {
      "remote_field_class": {
        "display_name": "Marketing contact status",
        "remote_key_name": "hs_marketable_status",
        "description": null,
        "is_required": false,
        "field_type": "string",
        "field_format": "booleancheckbox",
        "field_choices": [
          {
            "value": "true",
            "display_name": "Marketing contact",
          },
          {
            "value": "false",
            "display_name": "Non-marketing contact",
          },
        ],
        "item_schema": null,
        "modified_at": "2023-08-03T23:06:08.599197Z",
        "is_custom": false,
        "id": "07955dbe-bdba-4e91-a105-8b6bf4b4bc24",
        "is_common_model_field": false,
      },
      "value": "false",
    },
  ],
}
```