Unwrap Application Programming Interface (API) Overview: Query Your Feedback Data With GraphQL

The Unwrap application programming interface (API) gives developers programmatic access to customer feedback and the AI analysis Unwrap runs on it. Use it to work with your feedback text analytics in your own systems.

The GraphQL API lets you get all the metadata attached to each feedback entry in a View. It also lets you send feedback into Unwrap, build Groups and delete entries.

What You Can Do With the API

With the API, you can:

• Pull feedback entries, their full conversations and the Groups each entry belongs to

• Pull your taxonomy, so you can see which Groups are parents of other Groups and how deep each Group sits

• Upload feedback in batches of up to 500 entries, including custom fields such as customer tier or annual contract value (ACV)

• Create a new Group by describing the feedback theme in plain language

• Find other tickets that report the exact same issue as one ticket you're investigating

• Permanently delete entries by a custom field value or by a source ticket ID

• Add survey recipients without uploading a comma-separated values (CSV) file

You can also export only the entries that changed since your last export, instead of pulling everything again.

Available API Services

Most services run through one GraphQL endpoint. Send requests using POST to https://data.api.production.unwrap.ai.

Almost every call needs a teamId, which is the ID of the View you want to work with.

Entries

An Entry is an individual interaction with a customer, such as a support conversation, a social media post or a review on a public forum.

The entries query returns each Entry along with up to 100 conversation parts. That limit keeps response sizes manageable, since long conversations can contain hundreds of parts.

You can also:

• Add groupMemberships to return every Group an Entry belongs to

• Pass filterInput to restrict results to a start and end date

• Pass modifiedSince to return only Entries modified since a date, which is useful for picking up changes since your last export

See Entries API Documentation for each query.

Taxonomy

Groups in Unwrap are organized into a hierarchical taxonomy, so some Groups are parents of other Groups.

The teamGroups query returns your taxonomy trees. Each Group comes back with its id, title, uniqueEntries and totalDescendents, so you can see parent and child relationships and how deep each Group is. See Taxonomy API Documentation.

Building Groups

The buildGroupAsync mutation creates a Group from a title and a natural language description of the feedback theme. Unwrap classifies matching feedback and builds the Group in the background.

The mutation returns a groupId right away. The build typically takes 5 to 60 minutes, depending on the size of your feedback dataset, and you can monitor progress in the Unwrap UI.

Optional settings:

• parentGroupId attaches the new Group as a child of an existing Group in your taxonomy

• scopeToParentEntries, used with parentGroupId, only considers entries already in the parent Group

• filterNode restricts the build to entries that match a metadata (segment) filter, such as enterprise customers

Phrase the description the way customers would describe the issue, and say what to include and exclude. See Building Groups via API.

Batch Upload

The batchImport mutation imports multiple entries at once and returns a count of entriesScheduledForImport.

There's up to a 24 hour delay between scheduling entries and their being fully imported into Unwrap. Each entry can carry:

• Its text, title, source name and a link back to the original ticket

• The feedback date, in ISO 8601 format

• Conversation parts from the customer, a bot or a human agent

• Custom fields, as key and value pairs such as "Customer Tenure" and "0-90 days"

Support agent names and emails are only required if you use Unwrap's SupportIQ module. See Batch Upload Via API.

Entry Deletion

The Entry Deletion API permanently deletes matching Entries from one View. You can match Entries by a custom field (segment) value, such as member_account_ID, or by a primary identifier from a supported integration, such as a Zendesk ticket ID.

Deletion works in 2 steps:

1. Request the deletion. Unwrap finds the matching Entries and reports the match count.

2. Review the count, then confirm the operation before deletion begins.

Deletion doesn't stop the source integration from importing the data again. Delete the case in the source system first so it stays out of Unwrap.

Deleting large blocks of entries and then re-ingesting them may incur a processing fee. See Entry Deletion API Documentation.

Exact Issue Ticket Lookup

Exact Issue Ticket Lookup finds other customer tickets that report the same core issue as a ticket you're investigating. It focuses on the underlying issue the customer reported and what any agent did to fix it.

Call startAgenticEntrySearch with your teamId and a prompt that includes the full ticket conversation. Then call getAgenticEntrySearchResult with the returned workflowId until the status is COMPLETED.

Each result includes a short summary of the search, the matching tickets and a reason each ticket was included. See Exact Issue Ticket Lookup.

Survey Recipients

Admins can add survey recipients through a separate REST endpoint, POST https://surveys.api.production.unwrap.ai/addRecipients. Any metadata you send with a recipient can later be imported as custom fields on the survey responses. See Adding Recipients via API.

Getting an API Key

The API is available to authenticated users only. If you aren't authorized yet or don't have an API token, contact your Unwrap representative or contact@unwrap.ai to discuss pricing and authentication.

Once you have access, you generate a key from your Unwrap user profile:

1. In Unwrap, select your name in the bottom left-hand corner to open your profile.

2. Find the API Token section and generate a new key.

3. Copy the key and store it somewhere secure, such as an environment variable or a credential manager.

4. Send it on every request in the Authorization header as Bearer \<your token>.

Treat the token like a password. Don't share it or commit it to version control, and if it's compromised, delete it from your profile and create a new one.

Find Your teamId

Most API calls need a teamId. Run the getOrganizations query to list every Organization you belong to, with the name and id of each View in it.

query GetOrganizations {

getOrganizations {

name

teams {

id

name

}

}

}

Filtering Feedback Entries

The API supports filtering feedback entries by their fields and metadata. A few examples of what you can query for:

• Feedback entries submitted after November 1, 2022

• Feedback entries submitted via the Google Play Store about the Group "log in"

• Feedback entries where the value for the "version" segment is "v2.1"

Pass dates in the filterInput variable as startDate and endDate. To pick up only what's changed since your last export, use modifiedSince instead.

Paging Through Results

Most queries that return a list are paginated. If a query takes take and skip arguments, take sets how many items to return and skip sets how many to skip.

The entries query returns up to 100 entries per request. To fetch every entry in a View, loop over take and skip until the query returns an empty list.

Example Query and Response

This example GraphQL query gets the display text from recent feedback entries.

query Entries($teamId: Int!, $filterInput: FilterInput, $take: Int, $skip: Int) {
  entries(teamId: $teamId, filterInput: $filterInput, take: $take, skip: $skip) {
    id
    feedbackEntryText {
      displayText
    }
    providerUniqueId
  }
}

Use these variables, replacing teamId with your own:

{
  "teamId": 1056, // replace with your team Id
  "take": 50,
  "filterInput": {
    "startDate": "2020-07-01T07:00:00.000Z",
    "endDate": "2023-09-01T06:59:59.999Z"
  },
  "skip": null
}

Here's an example of the response you'd get for the query above:

{
  "data": {
    "entries": [
      {
        "id": 5607102,
        "feedbackEntryText": {
          "displayText": "I just love it"
        },
        "providerUniqueId": "fc55dc29-b338-4d7c-a951-79b0ed64cdba"
      },
      {
        "id": 5607101,
        "feedbackEntryText": {
          "displayText": "Fun"
        },
        "providerUniqueId": "04ea2e5f-51ba-423e-8d76-1a2557e3af16"
      },
      {
        "id": 5607100,
        "feedbackEntryText": {
          "displayText": "Great game!!"
        },
        "providerUniqueId": "1f27ad95-0efe-4782-a0dd-cbab258f34dd"
      }
    ]
  }
}

To return the Groups each entry belongs to, add this to the query:

groupMemberships {
      id
      title
    }

Usage Restrictions

These limits exist to keep the system stable. If you need more than they allow, reach out to Unwrap.

A token only makes requests to the View (teamId) it was created for, and you can only make tokens for Views in an Organization you belong to.

If an Organization admin removes your membership, your token expires. See Usage Restrictions.

Next Steps

• Read Entries API Documentation to pull feedback and Group memberships

• Read Taxonomy API Documentation to pull your Group hierarchy

• Read Batch Upload Via API to send feedback into Unwrap

• Read Building Groups via API to create Groups from code

• Read Unwrap MCP to query Unwrap from AI tools such as Claude, ChatGPT and Cursor instead of writing GraphQL

Need help with pricing or access? Email contact@unwrap.ai.