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.

GraphQL is documented at http://graphql.org.

Since documentation is a first-class citizen in GraphQL, a GraphQL client can be used to explore the Touchpoint API as you work to develop your interface. A GraphQL client option is https://github.com/skevy/graphiql-app.

To access the Touchpoint API for an organization, clientId and a client Token are needed. Credentials for clientId and client Token are requested from a Touchpoint Account Manager.

Client credentials are used to obtain a token. The token is included in the header for all subsequent requests.

Token request using GraphiQL (GraphQL)

In the GraphiQL client, the token request is formatted as a mutation that includes login(clientId: "...", clientToken: "...").

The token request is equivalent to the following CURL command: (RECOMMENDED)

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

The same command can also be run with a Content-Type of json. The json approach requires nesting the query in JSON and escaping appropriate characters. The json approach is (NOT RECOMMENDED).

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

In either case, a JSON response is received. All GraphQL responses include this “data” key.

A token is used in the header of all subsequent requests. The token typically expires after one day. New tokens are managed and created as necessary.

Fetch Resources

API requests are scoped to a Gathering ID.

For example, a request for all first names and last names of all attendees for Gathering with id 232 is formatted as follows.

GraphQL Query

The header must be set:

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, a mutation is used.

GraphQL Mutation

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"