Semble GraphQL API Documentation: Using Integration Tokens

This feature is only available to customers on our Commercial+ and Enterprise packages.

----

The Semble GraphQL API provides a secure, fast, and flexible way to interact with the Semble platform, including functionalities like generating an integration token for matching a specific patient with their questionnaire.

Integration tokens enhance the patient experience by allowing them to access questionnaires without re-entering personal details which you already have on your system for them.

Prerequisites

Before you start, you will need to have the following:

Your Semble API key: This key provides access to Semble's GraphQL API. This key can be found in Semble settings.
A GraphQL Client: The Semble GraphQL API is accessed via HTTP POST requests to https://open.semble.io/graphql. You can use any HTTP client to send requests.

This guide will walk you through generating and using integration tokens with your questionnaires.

1. Creating an Integration Token

To create an integration token, you'll need to use the createIntegrationToken mutation. The basic structure of this GraphQL mutation is:

mutation { createIntegrationToken(patient: "<PatientId>") { token } }

Replace <PatientId> with the ID of the patient for whom you want to create an integration token.

Here's an example of this mutation using the fetch API in JavaScript:

const CREATE_INTEGRATION_TOKEN_MUTATION = ` mutation { createIntegrationToken(patientId: "1234") { token } } `; fetch('https://api.semble.io/graphql', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Accept': 'application/json', 'x-token': `Bearer ${YOUR_API_KEY}`, }, body: JSON.stringify({ query: CREATE_INTEGRATION_TOKEN_MUTATION }) }) .then(r => r.json()) .then(data => console.log('data returned:', data));

Remember to replace YOUR_API_KEY with your actual Semble API key and 1234 with the ID of the patient for whom you want to create an integration token.

2. Retrieving Integration Tokens

Integration tokens can be retrieved via the integrationToken query. Here is the basic structure of the query:

query { integrationToken(id: "<TokenId>") { token } }

Replace <TokenId> with the ID of the integration token you wish to retrieve.Using the fetch API in JavaScript, the query would look something like this:

const GET_INTEGRATION_TOKEN_QUERY = ` query { integrationToken(id: "abcd") { token } } `; fetch('https://api.semble.io/graphql', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Accept': 'application/json', 'x-token': `Bearer ${YOUR_API_KEY}`, }, body: JSON.stringify({ query: GET_INTEGRATION_TOKEN_QUERY }) }) .then(r => r.json()) .then(data => console.log('data returned:', data));

Again, replace YOUR_API_KEY with your Semble API key and "abcd" with the ID of the token you want to retrieve.

3. Using Integration Tokens

Once you have the integration token, you can append it to the end of a questionnaire URL as follows:

https://questionnaire.semble.io/:questionnaireToken/:integrationToken.

This will direct the patient to their questionnaire without needing to input their personal details each time.Example URL with a questionnaire token and an integration token would look like this:

https://questionnaire.semble.io/5d8f731a48250f7992ff4a10/7b8f731a48250f7992ff4a11

With a valid integration token, patient data fields will not show, and the rest of the questionnaire will function as usual. If the token is invalid, an error will appear on the screen - "Failed to load questionnaire."

By following this guide, you can effectively generate and use integration tokens to improve your patient experience for accessing your questionnaires.