Metadata API

In Unified, metadata is "custom fields": the user-defined fields that a connected provider lets you add to its objects (for example, a custom "Industry" field on a CRM contact). The Metadata API provides a seamless way to view and manage these custom fields on unified objects.

Use it to list (and, when supported by the connection, create and update) custom field definitions for a connection — including each field's name, slug, format, and the unified object type it applies to. The associated objects then expose those custom fields in a metadata array.

Supported objects

Custom fields are available on the following unified objects (availability depends on the connection):

CRM

• Companies (crm_company)
• Contacts (crm_contact)
• Deals (crm_deal)
• Leads (crm_lead)

ATS

• Activities (ats_activity)
• Applications (ats_application)
• Candidates (ats_candidate)
• Companies (ats_company)
• Jobs (ats_job)

HRIS

• Employees (hris_employee)

Accounting

• Bills (accounting_bill)
• Credit memos (accounting_creditmemo)
• Expenses (accounting_expense)
• Invoices (accounting_invoice)
• Purchase orders (accounting_purchaseorder)
• Sales orders (accounting_salesorder)
• Vendor credits (accounting_vendorcredit)

Commerce

• Collections (commerce_collection)
• Items (commerce_item), including item media
• Item variants (commerce_itemvariant)
• Reviews (commerce_review), including review comments

KMS

• Pages (kms_page)

Task

• Projects (task_project)
• Tasks (task_task)

CDP

• Events (cdp_event)
• Profiles (cdp_profile)

Analytics

• Events (analytics_event)
• Visitors (analytics_visitor)

Other

• Calls (uc_call)
• Signing documents (signing_document)

Custom field values

On those objects, metadata is an array of custom field values. For example, a CRM contact:

{
  "id": "contact1",
  "name": "Jane Doe",
  "metadata": [
    {
      "slug": "industry",
      "value": "Software",
      "format": "TEXT"
    }
  ]
}

On many connections, metadata is a slow field. If your workspace excludes slow fields by default, include metadata in the fields query parameter to receive custom field values:

GET /crm/{connection_id}/contact?fields=id,name,metadata

See also Working with Custom & Original Fields.

Custom field definitions

The Metadata object_type field identifies the unified object the custom field belongs to (for example, crm_contact or commerce_item). When listing definitions, filter with the type query parameter to match that object type.

Optional fields on a definition include:

• format — the unified data type for the field (see formats below)
• original_format — the provider's native type string, when available
• options — allowed values for select-style fields, when available
• is_required — when true, the field is required on create for that connection
• objects — when populated by the connection, a map of unified object types to arrays of record IDs associated with the definition. This field is optional and is not updated automatically for every integration when you write metadata values onto records.

Example objects shape:

{
  "objects": {
    "crm_contact": ["contact1", "contact2"],
    "ats_candidate": ["candidate1"],
    "commerce_item": ["item1", "item2"]
  }
}

Formats

Supported format values:

• TEXT
• NUMBER
• DATE
• BOOLEAN
• FILE
• TEXTAREA
• SINGLE_SELECT
• MULTIPLE_SELECT
• MEASUREMENT
• PRICE
• YES_NO
• CURRENCY
• URL

Operations

List and get are available for metadata definitions on connections that support the Metadata API.

Create, update, and delete for definitions are supported only when the underlying connection exposes those operations. Writing custom field values is done by creating or updating the parent unified object and including a metadata array (with id and/or slug matching a definition, plus value).

Canonical paths:

GET    /metadata/{connection_id}/metadata
GET    /metadata/{connection_id}/metadata/{id}
POST   /metadata/{connection_id}/metadata
PUT    /metadata/{connection_id}/metadata/{id}
PATCH  /metadata/{connection_id}/metadata/{id}
DELETE /metadata/{connection_id}/metadata/{id}

For a walkthrough of definitions and values, see Enriching Unified Objects with Custom Metadata.