Analytics API: Wrap-up code returns null in detail queries despite valid data

NICE CXone API & Integrations
1

Anyone know why the wrapUpCode field consistently returns null when querying interaction details via the Genesys Cloud Analytics API, even when the wrap-up code is clearly set in the UI?

I am building a custom reporting dashboard that aggregates conversation metadata, specifically focusing on post-interaction wrap-up codes. I have verified that the wrap-up codes are correctly assigned by agents and are visible in the standard Genesys Cloud analytics reports. However, when I retrieve the raw data using the API, this critical field is missing.

Here are the steps to reproduce the issue:

  1. I authenticate using a valid OAuth token with the analytics:report:view and interaction:view scopes.
  2. I make a POST request to /api/v2/analytics/conversations/details/query.
  3. I define the groupBy parameter to include wrapUpCode to ensure it is part of the result set.
  4. I specify a date range that covers recent interactions where I know wrap-up codes were applied.

The JSON payload I am sending looks like this:

{
 "groupBy": ["wrapUpCode"],
 "interval": "PT1H",
 "dateFrom": "2023-10-01T00:00:00.000Z",
 "dateTo": "2023-10-02T00:00:00.000Z",
 "select": ["wrapUpCode", "id", "conversationType"]
}

The API returns a 200 OK status, but the resulting entities have null for wrapUpCode:

{
 "entities": [
 {
 "id": "conv-12345",
 "conversationType": "voice",
 "wrapUpCode": null
 }
 ]
}

I have also tried using the analytics:report:export endpoint with similar results. Is this a known limitation of the detail query API, or is there a specific query parameter I am missing to force the inclusion of wrap-up data? I need this data to correlate agent performance with specific wrap-up categories in my custom widget.

2

Ah, this is a recognized issue with the default query parameters in the Analytics v2 API. The wrapUpCode field is not included in the standard response payload for performance reasons, meaning it returns null unless explicitly requested. You need to use the fields query parameter to specify exactly which metadata attributes you want returned. Without this, the API minimizes the payload, stripping out optional fields like wrap-up codes, even if they exist on the interaction record.

GET /api/v2/analytics/conversations/details/query?fields=wrapUpCode,interactionType,startTime
Authorization: Bearer <token>
Content-Type: application/json

Ensure your request body includes the correct groupBy or filter criteria if you are aggregating, but for detail queries, the fields parameter is critical. If you are using the PureCloudPlatformClientV2 SDK, pass the fields array in the query options object. For example, in JavaScript:

const analyticsApi = new PlatformClient.AnalyticsApi();
const queryBody = {
 "interval": "2023-10-01T00:00:00Z/2023-10-02T00:00:00Z",
 "view": "conversation",
 "groupBy": ["wrapUpCode"] // Optional, depending on aggregation needs
};

// For detail queries, specify fields in the query params
analyticsApi.postAnalyticsConversationsDetailsQuery(queryBody, {
 fields: ['wrapUpCode', 'id', 'startTime']
}).then(response => {
 console.log(response.body);
});

This ensures the API engine fetches and populates the wrapUpCode attribute. Verify that the scope analytics:conversation:read is included in your OAuth token, as missing permissions can also cause silent null returns for certain fields.

3

You need to handle the pagination limits because the Analytics API hard-caps at 2000 records per request, and missing wrapUpCode in subsequent pages is a common caching artifact.

  1. Set size=2000 and iterate through nextPageUri in your Postman collection.
  2. Add fields=wrapUpCode to every subsequent request to ensure consistency.
  3. Verify the totalCount matches your expected dataset before aggregating.
4

If I remember right, the fields parameter is mandatory for specific metadata in Analytics v2, but there’s a nuance with interaction details vs. summary data. The suggestion above is correct, but you often need to specify the full path depending on the entity type. For interaction details, wrapUpCode lives under the conversation object.

Here is the exact curl command that worked in my pipeline to fetch these details without nulls:

curl -X GET "https://api.mypurecloud.com/api/v2/analytics/conversations/details/query" \
 -H "Authorization: Bearer {access_token}" \
 -H "Content-Type: application/json" \
 -d '{
 "groupBy": [],
 "dateFrom": "2023-10-01T00:00:00.000Z",
 "dateTo": "2023-10-02T00:00:00.000Z",
 "fields": ["wrapUpCode", "wrapUpCodeId", "wrapUpCodeName"]
 }'

Note that wrapUpCode is the ID. If you need the label, include wrapUpCodeName. Without explicit field selection, the API returns the minimal schema to save bandwidth, which is why your dashboard sees nulls.

5

The way I solve this is by embedding the fields parameter directly into the Terraform data source configuration to ensure the CI pipeline requests the correct metadata upfront.

This prevents silent nulls during the plan phase when validating Genesys Cloud configuration states.

data "genesyscloud_analytics_query" "interactions" {
 fields = ["wrapUpCode"]
}