Overview

Touchpoint’s API uses GraphQL as a query language to read and update data within Touchpoint. Instead of multiple REST endpoints, GraphQL supports a single endpoint that can receive structured JSON to return or mutate exactly the data types and attributes that you need.

You can learn more about GraphQL at http://graphql.org.

Since documentation is a first-class citizen in GraphQL, we recommend using a GraphQL client to explore our API as you work to develop your interface. We like and use https://github.com/skevy/graphiql-app.

To access the Touchpoint API for your organization, you will need a clientId and a client Token. Please request these credentials from your Touchpoint Account Manager. To interact with the API, you will use these credentials to obtain a token which you will include in the header for all your subsequent requests.

In the GraphiQL client, you would format the token request as

mutation {
  login(clientId: "ff3cbb1d-fb34-4518-943c-7a2e45db4213", clientToken: “d996afcf52165b991e17e3055067ac326ce6c5ca38d5d1b3") {
    token
  }
}

which is equivalent to the following CURL command: (RECOMMENDED)

curl -X POST https://api.certaintouchpoint.com/graphql -H "Content-Type:application/graphql" -d 'mutation { login(clientId: "04c9dc54-313d-560d-03d2-72cc0a0c2ee3", clientToken: "b2ee5f6180d9e0efbb539a4dc383171a2fb3d77a30ef6d6e") { token }}'

You may also run this command with a Content-Type of json, but you would have to nest the query in JSON and escape appropriate characters. (NOT RECOMMENDED)

curl -X POST https://api.certaintouchpoint.com/graphql -H 'Content-Type: application/json' -d '{"query":"mutation {login(clientId: \"ff3cbb1d-fb34-4518-943c-7a2e45db4213\", clientToken: \"d996afcf52165b991e17e3055067ac326ce6c5ca38d5d1b3\") { token}}"}'

In either case you would receive a JSON response:

"data": {
    "login": {
      "token": "123abcveryLongAuthorizationToken456def"
    }
  }
}

All GraphQL responses include this “data” key.

You would use the token in all the header of all subsequent requests you make as demonstrated below. This token typically expires after one day; you are responsible for managing and creating a new token as necessary.

Fetch Resources

When making API requests, you should scope your request to a Gathering ID. For example, to request all first names and last names of all the attendees for Gathering with the id 232, you would format a request as follows:

GraphQL Query

Your header must be set:

Authorization: Bearer 123abcveryLongAuthorizationToken456def

{
  attendees(gatheringId: 232) {
    firstName
    lastName
  }
}

CURL Request

curl -X POST https://api.certaintouchpoint.com/graphql -H 'Content-Type: application/graphql' -H 'Authorization: Bearer 123abcveryLongAuthorizationToken456def' -d '{ attendees(gatheringId: 232) { firstName lastName }}'

GraphQL Response

{“data”:{"attendees":[{"lastName":"Eggers", “firstName”:”Dave”},{“lastName”:Wallace","firstName": "David"},{"lastName":"Smith", "firstName":"Zadie"}]}}

Update Resource

To update an attendee’s first and last name, we would use a mutation.

GraphQL Mutation

mutation {
  updateAttendee(attendee: {firstName: "David Foster", lastName: "Wallace"}, gatheringId: 232, id: 71111) {
    firstName
    lastName
    id
  }
}

CURL Request

curl -X POST https://api.certaintouchpoint.com/graphql -H 'Content-Type: application/graphql' -H 'Authorization: Bearer veryLongAuthorizationToken' -d '{ mutation { updateAttendee(attendee: { firstName: "David Foster", lastName: "Wallace"}, gatheringId: 232, id: 71111) { firstName lastName id } }'

GraphQL Response

{“data":
  { "updateAttendee":
    { "lastName":"Wallace",
      "id":"71111",
      "firstName":"David Foster" 
    }
  }
}