Home/Guides/Metadata

Metadata

How to attach custom data to resources.

Overview

Some resources (such as CRM deals, contacts, and companies) support a metadata field. Metadata is a JSON object that can store arbitrary key-value pairs, useful for integrating with external systems or custom categorization.

Setting Metadata

Pass a JSON object in the metadata field when creating or updating a resource. Existing metadata will be completely replaced with the new value.

curl -X POST https://api.blueai.jp/api/v1/crm/deals \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "name": "New Deal",
    "metadata": {
      "source": "website",
      "campaign_id": "camp_123e4567e89b12d3a456426614174000",
      "priority": "high"
    }
  }'

Retrieving Metadata

The metadata field is included when retrieving a resource.

{
  "id": "deal_11111111111111111111111111111111",
  "name": "New Deal",
  "metadata": {
    "source": "website",
    "campaign_id": "camp_123e4567e89b12d3a456426614174000",
    "priority": "high"
  }
}

Limitations

Metadata has a maximum size of 16 KB. Keys can be up to 40 characters, values are strings up to 500 characters. You can store up to 50 keys.

Example

// Set metadata on a deal
const res = await fetch("https://api.blueai.jp/api/v1/crm/deals/deal_11111111111111111111111111111111", {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  credentials: "include",
  body: JSON.stringify({
    metadata: {
      source: "referral",
      external_id: "ext_456",
    },
  }),
});