---
title: "Fetch a custom field mapping"
method: GET
path: "/v3/ControlPlane/ConversationInsights/CustomFieldMappings/{mappingId}"
tags: ["TwilioInsightsConfig"]
---

# Fetch a custom field mapping

`GET /v3/ControlPlane/ConversationInsights/CustomFieldMappings/{mappingId}`

## Request

- Base URL: `https://insights.twilio.com`
- URL: `https://insights.twilio.com/v3/ControlPlane/ConversationInsights/CustomFieldMappings/{mappingId}`
- Auth: HTTP basic

Returns a single custom field mapping by its `mappingId`. The `ETag`
response header identifies the mapping's current version; supply it as
`If-Match` on `PATCH` to guard against concurrent updates.

## Path parameters

- `mappingId` string, required

## Response `200`

The custom field mapping.

- CustomFieldMappingResponse: A registered custom field mapping.
  - `id` string: The unique identifier of the custom field mapping.
  - `category` 'MEASURE', required: The category of the custom field. Supported values: - `MEASURE`: a numeric value that can be aggregated and queried as a measure in Conversations Insights.
  - `name` string, required: Name of the custom field, unique within the account.
  - `description` string: Optional, free-text description supplied at registration time. Display-only — not part of any uniqueness check.
  - `entityMetadata` EntityMetadata, required: Identifies the entity that supplies this field's value. `sourceType` selects the source, and the property named for that source carries its details. Exactly that one source property must be present: | `sourceType` | Required property | |---|---| | `INTELLIGENCE_OPERATOR` | `intelligenceOperator` | A request whose `sourceType` doesn't match the source property it sends, or that sends any other property, is rejected with `400`.
    - `sourceType` 'INTELLIGENCE_OPERATOR', required: The kind of entity that supplies the custom field's value. Each value has a matching property on `entityMetadata` that carries that source's details. Supported values: - `INTELLIGENCE_OPERATOR`: the value is read from the output of a Conversational Intelligence operator. Details go in `entityMetadata.intelligenceOperator`.
    - `intelligenceOperator` IntelligenceOperatorSource: Details of a custom field whose value is read from a Conversational Intelligence operator's output. The operator must: - have an active version; - have `outputFormat` `JSON` (`TEXT` and `CLASSIFICATION` operators are rejected). Requests that reference an ineligible operator are rejected with `400`.
      - `operatorId` string, required: The ID of the Conversational Intelligence operator whose output supplies this field's value. Must match `^intelligence_operator_[0-7][0-9a-z]{25}$`. Cannot be changed after registration.
      - `operatorName` string: Optional, display-only name of the operator. Stored as supplied and not validated against the operator.
      - `field` string, required: Path to the property in the operator's output schema that supplies this field's value. Rules: - one or two segments separated by `.` — a top-level property (`leadScore`) or one level of nesting (`scores.leadScore`); - each segment contains only letters, digits and `_`; array indexing (such as `items[0]`) is not supported; - the path must exist in the output schema of the operator's latest active version and resolve to a property of type `number` or `integer`.
  - `createdAt` string, date-time: When the mapping was registered.
  - `updatedAt` string, date-time, nullable: When the mapping was last modified via `PATCH`. Null until the first update.

## Other responses

- `401`: Unauthorized request
- `403`: Forbidden request
- `404`: Resource not found
- `429`: Too Many requests (rate limit exceeded for request originating from public API)
- `500`: Internal server error

## Changes

- **2026-10-12** (v3) `68c9e65dfd52`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/twilio/apis/insights-v3/changes/v3/ControlPlane/ConversationInsights/CustomFieldMappings/:mappingId/get.md)

---

[API](https://skmtc.dev/twilio/apis/insights-v3.md) - [All operations](https://skmtc.dev/twilio/apis/insights-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/twilio/apis/insights-v3/revisions/68c9e65dfd52?raw)