List custom measure field mappings for an account

(new)

Public beta

Conversation Insights, including the APIs, is currently available as a public beta release and the information contained in this document is subject to change. Some features are not yet implemented and others may be changed before the product is declared as generally available. Public beta products are not covered by the Twilio Support Terms or Twilio Service Level Agreement.

Conversation Insights is not PCI compliant or a HIPAA Eligible Service and should not be used in workflows that are subject to HIPAA or PCI.

Conversations products are only available in the new Twilio Console. If your account hasn't been migrated, you'll be redirected to the legacy Console where these products won't appear.

GET/v3/ControlPlane/ConversationInsights/CustomFieldMappings

Base url: https://insights.twilio.com (base url)

Returns the custom field mappings registered for the account, one page at a time. Use pageSize to limit the number of mappings returned, and pass meta.nextToken from a response as pageToken to fetch the next page. On the last page, meta.nextToken is null.

Request

Authentication

Basic Auth

Query string

Property nameTypeRequiredPIIDescription

pageSizeinteger

Optional

The maximum number of resources to return

Default: 50Minimum: 1Maximum: 1000

pageTokenstring

Optional

Token for pagination

Responses

200400401403429500

A page of custom field mappings registered for the account.

Schema

Property nameTypeRequiredPIIDescriptionChild properties

itemsarray[object]

Optional

Show items properties

Property nameTypeRequiredPIIDescriptionChild properties

idstring

Optional

The unique identifier of the custom field mapping.

Example: convinsights_mapping_01m31967b7em08vh1pqgbam3mj

categoryenum<string>

Optional

The category of the custom field. Supported values:

MEASURE: a numeric value that can be aggregated and queried as a measure in Conversations Insights.

Possible values:

MEASURE

namestring

Optional

Name of the custom field, unique within the account.

Example: LeadScore

descriptionstring

Optional

Optional, free-text description supplied at registration time. Display-only — not part of any uniqueness check.

Example: Lead quality score derived from sentiment analysisMax length: 150

entityMetadataobject

Optional

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.

Show entityMetadata properties

createdAtstring<date-time>

Optional

When the mapping was registered.

Example: 2026-08-13T14:30:00Z

updatedAtstring<date-time>

Optional

When the mapping was last modified via PATCH. Null until the first update.

Example: 2026-09-30T10:00:00Z

metaobject

Optional

The pagination metadata containing navigation tokens and result information. By convention, this schema should be added to the response payload's 'meta' attribute.

Show meta properties

Bad request

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Unauthorized request

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Forbidden request

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Too Many requests (rate limit exceeded for request originating from public API)

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Internal server error

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

List custom measure field mappings for an account

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listCustomFieldMappings() {
11  const customFieldMappings = await client.insights.v3.customFieldMappings.list(
12    { limit: 20 },
13  );
14
15  customFieldMappings.forEach((c) => console.log(c.id));
16}
17
18listCustomFieldMappings();

Response

1{
2  "items": [
3    {
4      "id": "convinsights_mapping_01m31967b7em08vh1pqgbam3mj",
5      "category": "MEASURE",
6      "name": "LeadScore",
7      "description": "Lead quality score derived from sentiment analysis",
8      "entityMetadata": {
9        "sourceType": "INTELLIGENCE_OPERATOR",
10        "intelligenceOperator": {
11          "operatorId": "intelligence_operator_01kcgy1ew0e9x8re6jq542zt8b",
12          "operatorName": "Sentiment Analysis",
13          "field": "leadScore"
14        }
15      },
16      "createdAt": "2026-08-13T14:30:00Z",
17      "updatedAt": "2026-09-30T10:00:00Z"
18    }
19  ],
20  "meta": {
21    "key": "items",
22    "pageSize": 20,
23    "previousToken": "eyJwYWdlIjowLCJxdWVyeSI6ImJvb2tzIn0=",
24    "nextToken": "eyJwYWdlIjoyLCJxdWVyeSI6ImJvb2tzIn0="
25  }
26}