SparkThink API - Part 3 - Mutations

Roger Chan -

Overview

Mutations are not what you think! Mutations are "read/write" requests to make changes to the database using the SparkThink API. We will walkthrough the main types of mutations that you can perform in SparkThink API:

  1. createCollector
  2. addSurveyRespondentByExternalID
  3. addSurveyRespondentByEmail

createCollector

Description

This mutation allows a survey collector to be added to a survey project. You can specify the type of survey collector to be added (e.g. email invitation, survey link)

General Structure

createCollector (surveyId: String, collectorName: String, collectorType: CollectorType) {
{
    field1
    field2
    field3 {
      nested_field_1
      ...
    }
    ...
  }
}

Arguments

Name Type Description
surveyid String The unique survey ID
collectorName String The unique collector ID for the survey
collectorType String An enum representing the collector types (e.g. SlalomLink, AnonymousLink, Email, SlalomEmail)

Fields

Name Type Description
surveyId ID The Survey ID where the new collector was made
collectorId String The ID of the new collector
collectorName String The name of the new collector
status String The status of the new collector
url String The URL of the new collector

Example Mutation

mutation {
	createCollector (surveyId: "6269a574361cd3004684378f", collectorName: "May 2022 Email", collectorType: Email) {
    surveyId
    collectorId
    collectorName
    status
    url
  }
}

Example Response

{
  "data": {
    "createCollector": {
      "surveyId": "6269a574361cd3004684378f",
      "collectorId": "62700f0e7a8ea0004325633f",
      "collectorName": "May 2022 Email",
      "status": "Draft",
      "url": null
    }
  }
}

Notes

There are 4 types of collectors that can be made:

  • AnonymousLink (anybody can take the survey)
  • SlalomLink (a link to the a Slalom-only survey)
  • SlalomEmail (a Slalom-only email invitation)
  • Email (a general email invitation)

addSurveyRespondentByEmail

Description

This mutation allows a survey respondent to be added to a survey email invitation collector. The survey respondent is specified by a unique email address for that survey collector, first name, last name, as well as a set of custom attributes.

General Structure

addSurveyRespondentByEmail (surveyId: String, 
collectorId: String, 
contacts: [ContactDetailsByEmail] ) {
{
    field1
    field2
    field3 {
      nested_field_1
      ...
    }
    ...
  }
}

Arguments

Name Type Description
surveyId String The unique survey ID
collectorId String The unique collector ID for the survey
contacts [ContactDetailsByEmail] An array containing the contacts to be added

Fields

Name Type Description
[SurveyLinkByEmail] Array An array containing the newly created survey links for all the provided contacts

Example Query

mutation {
	addSurveyRespondentByEmail (surveyId: "6269a574361cd3004684378f", collectorId: "62701aaf7a8ea00043256341", contacts: [{firstName: "Roger", lastName: "Chan", email: "roger.chan@slalom.com"}] ) {
    surveyId
    url
    email	
  } 
}

Example Response

"data": {
    "addSurveyRespondentByEmail": [
      {
        "surveyId": "6269a574361cd3004684378f",
        "url": "https://sparkthink-dev.slalom.com/join/u/4273842c-6d59-4913-bfa8-db7d96305200",
        "email": "roger.chan@slalom.com"
      }
    ]
  }
}

Notes

For Slalom-only email invitations, the email address provided must match a Slalom, Versa or Two Degrees email domain.

addSurveyRespondentByExternalID

Description

This mutation allows a survey respondent to be added to a survey email invitation collector. The survey respondent is specified by a unique external identifier (such as a Salesforce Customer ID), as well as a set of custom attributes.

General Structure

addSurveyRespondentByExternalId (surveyId: String, 
collectorId: String, 
contacts: [ContactDetailsByExternalId] ) {
{
    field1
    field2
    field3 {
      nested_field_1
      ...
    }
    ...
  }
}

Arguments

Name Type Description
surveyId String The unique survey ID
collectorId String The unique collector ID for the survey
contacts [ContactDetailsByEmail] An array containing the contacts to be added

Fields

Name Type Description
[SurveyLinkById] Array An array containing the newly created survey links for all the provided contacts

Example Query

mutation {
	addSurveyRespondentByExternalId (surveyId: "6269a574361cd3004684378f", collectorId: "62700f0e7a8ea0004325633f", contacts: [{contactId: "test-12345"}] ) {
    surveyId
    url
    contactId	
  } 
}

Example Response

{
  "data": {
    "addSurveyRespondentByExternalId": [
      {
        "surveyId": "6269a574361cd3004684378f",
        "url": "https://sparkthink-dev.slalom.com/join/u/5c374172-e804-40f9-8841-721f03af7e99",
        "contactId": "test-12345"
      }
    ]
  }
}

Notes

You can only add respondents by an external ID to AnonymousLink or Email collector type (i.e. you cannot add respondents by an external ID to SlalomLink and SlalomEmail collector types)