Getting Started

To query Unwrap's GraphQL api you will need an ACCESS_KEY. Contact your unwrap associate to get an access key. Once you have a key you can query our GraphQL api at https://data.api.production.unwrap.ai/.

Here is a helpful read that provides an introduction to GraphQL. If you are not familiar with querying via GraphQL APIs, we recommend giving this a read to start.

Using Apollo Explorer to Explore Unwrap's Graph

Apollo Explorer is a useful tool for exploring the data and documentation available from a GraphQL API as well as test queries against the API. If you navigate to https://data.api.production.unwrap.ai/ you'll be prompted to explore our Graph.

Click 'Query your server' and you'll be directed to Apollo's sandbox.

You can explore our API documentation, allowed operations, and fields in detail by using the sidebar on the left

Configure Authorization

You can also use the Explorer to test queries against our api. You just need to setup the authorization header. Click on the gear icon next to the url.

Click 'New shared header' and enter the header key Authorization and value Bearer UNWRAP_ACCESS_KEY.

Click 'Save'. Now you can submit queries to Unwrap.

Find your TeamId

Most all of the API calls require a teamId to be specified to return the correct data. To find the right teamId use the getOrganizations query. This lists any organizations you belong to as well as all the team names and ids in that organization.

Paste the statement below into the 'Operation' window

query GetOrganizations {
  getOrganizations {
    name
    teams {
      id
      name
    }
  }
}

This query doesn't take any arguements. Running the query results in a payload that looks like:

{
  "data": {
    "getOrganizations": [
      {
        "name": "Good Hospitality",
        "teams": [
          {
            "id": 350, // this is the `teamId` for the team named `La Naranja`
            "name": "La Naranja"
          },
          {
            "id": 351,
            "name": "Handle Bar"
          },
          {
            "id": 353,
            "name": "Lucky Nickel"
          },
          {
            "id": 354,
            "name": "Allesia"
          }
        ]
      }
    ]
  }
}

Fetching Entries from Unwrap

To query for entries against unwrap enter the following in the 'Operation' window.

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

And paste this into the 'Variables' window. Change the teamId to your team's Id.

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

Then if you click the 'Entries' button this will execute the feedbackEntries query on our api and return a list of entries for your team. The 'Operation' window will auto complete text. To include the group mappings on the entry add this to the query statement.

groupMemberships {
      id
      title
    }

the full query should look like

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

Quering Unwrap's Graph via Python

Below is a sample script of how to query our GraphQL api via python:

import json
import os
import requests


### To call api you will need an access token. Contact your unwrap representative to obtain an access token.
### This relies on the environment variable UNWRAP_ACCESS_TOKEN to be set.
ACCESS_TOKEN = os.getenv("UNWRAP_ACCESS_TOKEN")
url = "https://data.api.production.unwrap.ai/"


def get_entries(team_id: int, take: int = 100, skip: int = 0) -> list[dict]:
    """
    Returns entries for a team
    """

    # query copied from apollo explorer
    query = """
        query Entries($teamId: Int!, $filterInput: FilterInput, $take: Int, $skip: Int) {
            entries(teamId: $teamId, filterInput: $filterInput, take: $take, skip: $skip) {
                id
                feedbackEntryText {
                    displayText
                    fullConversation
                }
                providerUniqueId
                groupMemberships {
                    id
                    title
                }
            }
        }
    """

    variables = { "teamId": team_id, "take": take, "filterInput": {}, "skip": skip }

    header = {
        "Authorization": f"Bearer {ACCESS_TOKEN}"
    }

    ### this is the structure of a graphql query.
    ### It's a standard post request made to an api with the fields 'query' and 'variables'
    data = {"query": query, "variables": variables}

    r = requests.post(url=url, json=data, headers=header)
    data = json.loads(r.text)
    return data.get("data").get("feedbackEntries")


### fill in with your team id
get_entries(team_id=494)

Pagniation

Most all of the queries on Unwrap's graph that return a list are paginated. You can tell if a query is paginated if the query takes a take and skip argument. take specifies how many of the item to take and skip specifies how many items to skip in the results.

To fetch all entries for a team you can loop over the take and skip args until the query returns an empty list. See below for an example looping through the paginated query.

def fetch_all_entries_for_team(team_id: int) -> list[dict]:
    """
    Entries are limited to only return 100 entries per query.
    This loops through the pagination and returns all entries for a team.
    """
    page_size = 100
    index = 0
    has_results = True
    accumulated_results = []
    while has_results:
        results = get_entries(team_id=team_id, take=page_size, skip=index * page_size)
        print(f"fetched {len(results)} entries from data api for page {index}.")
        index += 1
        accumulated_results.extend(results)
        if len(results) == 0:
            has_results = False

        # prevent us from infinitely looping
        if index > 100:
            has_results = False

    return accumulated_results

entries = fetch_all_entries_for_team(team_id=494)