Building Groups via API

Overview

The Group Building API allows you to programmatically create groups in Unwrap. You provide a natural language description of the feedback theme you want to track, and Unwrap's NLP system will find matching feedback and build the group in the background.

This is an asynchronous API — you trigger the build, then check on the group later in the Unwrap UI.

Create a Group

Mutation

mutation CreateGroup($teamId: Int!, $description: String!, $title: String!) {
  buildGroupFromDescription(teamId: $teamId, description: $description, title: $title) {
    groupId
  }}

Parameters

Tips for writing a good description:

• The classifier looks at customer feedback - align your description with how customers would describe the issue.

• Be specific about what feedback should match, and what it should not match: "DO capture customers complaining about price being too high, expensive, or not worth the cost. DO NOT capture customers complaining about billing issues unrelated to pricing."

curl Example

curl -s -X POST https://data.api.production.unwrap.ai/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "query": "mutation CreateGroup($teamId: Int!, $description: String!, $title: String!) { buildGroupFromDescription(teamId: $teamId, description: $description, title: $title) { groupId } }",
    "variables": {
      "teamId": 123,
      "description": "DO capture customers complaining about price being too high, expensive, or not worth the cost. DO NOT capture customers complaining about billing issues unrelated to pricing.",
      "title": "Pricing complaints"
    }
  }'

Response

{
  "data": {
    "buildGroupFromDescription": {
      "groupId": "98765"
    }
  }
}

The mutation returns immediately with the new groupId. The group build runs in the background and typically completes within 5 - 60 minutes depending on the size of your feedback dataset. You can view the group's progress in the Unwrap UI.

Full Python Example

import os
import requests

ACCESS_TOKEN = os.getenv("UNWRAP_ACCESS_TOKEN")
URL = "https://data.api.production.unwrap.ai/graphql"
HEADERS = {"Authorization": f"Bearer {ACCESS_TOKEN}"}

MUTATION = """
    mutation CreateGroup($teamId: Int!, $description: String!, $title: String!) {
        buildGroupFromDescription(teamId: $teamId, description: $description, title: $title) {
            groupId
        }
    }
"""

def create_group(team_id: int, description: str, title: str) -> str:
    """Create a group and return the groupId."""
    variables = {"teamId": team_id, "description": description, "title": title}
    response = requests.post(URL, json={"query": MUTATION, "variables": variables}, headers=HEADERS)
    response.raise_for_status()
    data = response.json()
    if "errors" in data:
        raise Exception(f"GraphQL errors: {data['errors']}")
    return data["data"]["buildGroupFromDescription"]["groupId"]


# Usage
group_id = create_group(
    team_id=123,
    description="DO capture customers complaining about price being too high, expensive, or not worth the cost. DO NOT capture customers complaining about billing issues unrelated to pricing.",
    title="Pricing complaints",
)
print(f"Group created. ID: {group_id}")