--- title: "Update a custom field mapping" method: PATCH path: "/v3/ControlPlane/ConversationInsights/CustomFieldMappings/{mappingId}" tags: ["TwilioInsightsConfig"] --- # Update a custom field mapping `PATCH /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 Partially updates an existing custom field mapping. Only the properties present in the body are changed. The updatable properties depend on the mapping's `sourceType`; for `INTELLIGENCE_OPERATOR`, only `entityMetadata.intelligenceOperator.field` can be updated today. The new `field` is validated the same way as at registration: it must be one or two `.`-separated segments of letters, digits and `_`, and resolve to a `number` or `integer` property in the output schema of the operator's latest active version. The mapping's `id`, `name`, `category`, `createdAt` and owning entity never change. Sending a `field` value equal to the current one is a no-op that returns `200` without modifying the mapping, so the operation is idempotent. Supply `If-Match` with the `ETag` returned by `GET`, `POST` or a previous `PATCH` to guard against concurrent updates. Values already ingested are not recomputed; results processed after the update use the new `field`. ## Path parameters - `mappingId` string, required ## Headers - `If-Match` string ## Request body - CustomFieldMappingUpdateRequest: Partial update of a custom field mapping. Only properties present in the body are changed; absent properties keep their current value. The body must contain at least one change: an empty body is rejected with `400`. Properties that cannot be updated (such as `name`, `category` or `operatorId`) are rejected with `400` rather than ignored. - `entityMetadata` EntityMetadataUpdate: Updatable subset of `entityMetadata`. `sourceType` must equal the mapping's current `sourceType` (it cannot be changed), and the property named for that source carries the fields to update: | `sourceType` | Update property | Updatable fields | |---|---|---| | `INTELLIGENCE_OPERATOR` | `intelligenceOperator` | `field` | - `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` IntelligenceOperatorSourceUpdate: Updatable fields of a custom field mapping sourced from a Conversational Intelligence operator. At least one field must be present. Currently only `field` can be modified; `operatorId` and `operatorName` cannot be updated. - `field` string: New path to the property in the operator's output schema. Follows the same rules as `field` at registration: one or two `.`-separated segments of letters, digits and `_`, resolving to a `number` or `integer` property on the operator's latest active version. ## Response `200` The mapping was updated, or the supplied values already matched and nothing changed. - 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 - `400`: The request is invalid. One of: - a malformed body, an empty body or source object (nothing to update), a missing `entityMetadata.sourceType`, or a `field` that fails its pattern; - a property that cannot be updated (for example `name`, `category`, `operatorId`) is present; - `entityMetadata.sourceType` does not match the mapping's current `sourceType`, or is not supported for updates; - the new `field` does not resolve to a `number` or `integer` property on the operator's latest active version, or the operator no longer has an active `JSON` version. - `401`: Unauthorized request - `403`: Forbidden request - `404`: Resource not found - `409`: The mapping was modified by a concurrent request while this update was being applied. Fetch the mapping and retry. - `412`: The `If-Match` value does not match the mapping's current `ETag`. - `429`: Too Many requests (rate limit exceeded for request originating from public API) - `500`: Internal server error - `503`: The operator details needed to validate the update could not be retrieved from Conversational Intelligence. The mapping was not changed; retry after the `Retry-After` interval. ## 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/patch.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)