--- title: "Register a custom measure field mapping" method: POST path: "/v3/ControlPlane/ConversationInsights/CustomFieldMappings" tags: ["TwilioInsightsConfig"] --- # Register a custom measure field mapping `POST /v3/ControlPlane/ConversationInsights/CustomFieldMappings` ## Request - Base URL: `https://insights.twilio.com` - URL: `https://insights.twilio.com/v3/ControlPlane/ConversationInsights/CustomFieldMappings` - Auth: HTTP basic 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}`. ## Request body - CustomFieldMappingRequest: Registration payload for a single custom field. The mapping is created in the account identified by the request's credentials. - `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, used to reference it in Insights queries. Contains only letters, digits and `_`, and must not be empty. Must be unique within the account across every `sourceType`; registering an existing name returns `409`. Cannot be changed after registration. - `description` string: Optional, free-text description of this custom field mapping, up to 150 characters. 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`. ## Response `201` The custom field mapping was created. - 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 required property (`category`, `name`, `entityMetadata`, `entityMetadata.sourceType`, `operatorId`, `field`) is missing, or `category` / `sourceType` is not a supported value; - `name` is empty or contains characters other than letters, digits and `_`, or `description` is longer than 150 characters; - `entityMetadata` does not carry the property that matches its `sourceType`, or carries any other property; - `operatorId` is not a valid operator ID; - the operator has no active version or its `outputFormat` is not `JSON`; - `field` has more than two segments, contains unsupported characters, or does not resolve to a `number` or `integer` property in the operator's output schema. - `401`: Unauthorized request - `403`: The account has reached its limit of custom measures (default 3), or does not have access to custom field mappings. - `409`: A mapping with this `name` already exists for the account. Names are unique per account across every `sourceType`, so this applies regardless of which entity either mapping is sourced from or whether the payload matches. Nothing is changed. `params.id` carries the existing mapping's `id`; use `PATCH` on it to modify the mapping. - `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 registration could not be retrieved from Conversational Intelligence. No mapping was created; retry after the `Retry-After` interval. ## Changes - **2026-10-12** (v3) `68c9e65dfd52`: 5 breaking, 7 info - added the new required request property `entityMetadata/sourceType` - removed `#/components/schemas/IntelligenceOperatorEntityMetadata` from the `entityMetadata` request property `oneOf` list - the `entityMetadata` request property type changed from no type to `object` - the `entityMetadata` response's property type changed from no type to `object` for status `201` - …8 more - **2026-09-28** (v3) `f4ccc4d16905`: 1 info - endpoint added [Operation history](https://skmtc.dev/twilio/apis/insights-v3/changes/v3/ControlPlane/ConversationInsights/CustomFieldMappings/post.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)