Fetch a custom field mapping

(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/{mappingId}

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

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.

Request

Authentication

Basic Auth

Path parameters

Property nameTypeRequiredPIIDescription

mappingIdstring

required

The unique identifier of the custom field mapping, as returned in id when the mapping was created.

Example: convinsights_mapping_01m31967b7em08vh1pqgbam3mj

Responses

200401403404429500

The custom field mapping.

Schema

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

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

Resource not found

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

Fetch a custom field mapping

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 fetchCustomFieldMapping() {
11  const customFieldMapping = await client.insights.v3
12    .customFieldMappings("convinsights_mapping_01m31967b7em08vh1pqgbam3mj")
13    .fetch();
14
15  console.log(customFieldMapping.id);
16}
17
18fetchCustomFieldMapping();

Response

1{
2  "category": "MEASURE",
3  "createdAt": "2026-08-13T14:30:00Z",
4  "description": "Lead quality score derived from sentiment analysis",
5  "entityMetadata": {
6    "sourceType": "INTELLIGENCE_OPERATOR",
7    "intelligenceOperator": {
8      "operatorId": "intelligence_operator_01kcgy1ew0e9x8re6jq542zt8b",
9      "operatorName": "Sentiment Analysis",
10      "field": "leadScore"
11    }
12  },
13  "id": "convinsights_mapping_01m31967b7em08vh1pqgbam3mj",
14  "name": "Miss Christine Morgan",
15  "updatedAt": "2026-09-30T10:00:00Z"
16}