Overview

Touchpoint’s API uses GraphQL as a query language to read and update data within Touchpoint. GraphQL is a query language. It uses a single endpoint. The single endpoint can receive structured JSON to return or mutate exactly the data types and attributes that you need. GraphQL documentation is available at graphql.org. A GraphQL client is recommended to explore the API as you work to develop your interface. The team likes and uses GraphiQL App. To access the Touchpoint API for your organization, you will need a clientId and a clientToken. These credentials must be requested from your Touchpoint Account Manager. These credentials are used to obtain a token. The token is included in the header for all your subsequent requests. In the GraphiQL client, you format the token request as a mutation that returns a token. The mutation example is shown below. The CURL command is shown as the equivalent. You may also run this command with a Content-Type of json. In that case you would nest the query in JSON and escape appropriate characters. In either case you would receive a JSON response. The response includes a data key. All GraphQL responses include this data key. The token is used in the header of all subsequent requests. The token typically expires after one day; you are responsible for managing and creating a new token as necessary.

Mutation example (RECOMMENDED)

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

CURL Command (RECOMMENDED)

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

Content-Type json (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}}"}'

JSON response shape

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

All GraphQL responses include this “data” key. The token is used in the header for all subsequent requests you make as demonstrated below. The 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:

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

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

Was this article helpful? [Yes] [No]

Attendees Query
createAttendee
Leads Query
Gatherings Query
Features Overview