Registers a custom field for the account. entityMetadata.sourceType selects where the field's value comes from, and the matching property on entityMetadata (intelligenceOperator for INTELLIGENCE_OPERATOR) carries its details. Only the MEASURE category is supported for now.

The request is validated before the mapping is created:

• name contains only letters, digits and _, and is not already registered for the account (otherwise 409);
• description, when present, is at most 150 characters;
• for INTELLIGENCE_OPERATOR, the operator has an active version with outputFormat JSON, and entityMetadata.intelligenceOperator.field is one or two .-separated segments that resolve to a number or integer property in that version's output schema (otherwise 400);
• the account has a free slot in the category; by default an account can register up to 3 custom measures (otherwise 403). Use GET /v3/ControlPlane/ConversationInsights/CustomFieldMappingsCapacity to check the remaining slots.

Create-only: if a mapping with the same name already exists for the account, 409 is returned with the existing mapping's id and nothing is changed. To modify an existing mapping, use PATCH /v3/ControlPlane/ConversationInsights/CustomFieldMappings/{mappingId}.

{
  "name": "LeadScore",
  "description": "Lead quality score derived from sentiment analysis",
  "entityMetadata": {
    "intelligenceOperator": {
      "operatorId": "intelligence_operator_01kcgy1ew0e9x8re6jq542zt8b",
      "operatorName": "Sentiment Analysis",
      "field": "leadScore"
    }
  }
}

{
  "id": "convinsights_mapping_01m31967b7em08vh1pqgbam3mj",
  "name": "LeadScore",
  "description": "Lead quality score derived from sentiment analysis",
  "entityMetadata": {
    "intelligenceOperator": {
      "operatorId": "intelligence_operator_01kcgy1ew0e9x8re6jq542zt8b",
      "operatorName": "Sentiment Analysis",
      "field": "leadScore"
    }
  },
  "createdAt": "2026-08-13T14:30:00Z",
  "updatedAt": "2026-09-30T10:00:00Z"
}