Overview - Touchpoint API

Overview

Touchpoint’s API uses GraphQL as a query language to read and update data within Touchpoint. 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, you should use a GraphQL client to explore the Touchpoint 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 need a clientId and a client Token. You request these credentials from your Touchpoint Account Manager. You use these credentials to obtain a token. You include the token in the header for all subsequent requests you make.

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

mutation {
  login(clientId: "04c9dc54-313d-560d-03d2-72cc0a0c2ee3", clientToken: "b2ee5f6180d9e0efbb539a4dc383171a2fb3d77a30ef6d6e") { token }
}

This request 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 the command with a Content-Type of json. You must nest the query in JSON. You must 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 receive a JSON response.

All GraphQL responses include this “data” key. You use the token in all the header of all subsequent requests you make. 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 scope the 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 format the request as follows.

You set the request header:

Authorization: Bearer 123abcveryLongAuthorizationToken456def

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, you 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"}}}