Storing Questionnaire Responses

Welcome to the Semble GraphQL API how-to guide. In this guide, we'll walk you through how to use the Semble public API to store the responses of questionnaire into Semble.

The process involves four main steps:

1. Authenticate
2. Either get a patient or create a new patient.
3. Get a questionnaire.
4. Insert the responses from your questionnaire.

Let's dive into the details.

Step 1: Authenticate

Before making any requests, make sure you have a valid token. Refer to the Authentication section for more details.

Step 2: Get or Create a Patient

To get an existing patient, use the patients query. Here is the code for three languages:

curl

curl -X POST https://open.semble.io/graphql \
-H "Content-Type: application/json" \
-H "x-token: yourtoken" \
-d '{
  "query": "query findPatients($search: String) { patients(search: $search) { data { id firstName lastName dob email } } }",
  "variables": {"search": "John Doe"}
}'

Javascript

const fetch = require('node-fetch');

const query = `
  query findPatients($search: String) {
    patients(search: $search) {
      data {
        id
        firstName
        lastName
        dob
        email
      }
    }
  }
`;

const variables = {
  search: 'John Doe',
};

fetch('https://open.semble.io/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-token': 'yourtoken',
  },
  body: JSON.stringify({ query, variables }),
})
  .then((res) => res.json())
  .then((res) => console.log(res.data));

Python

import requests
import json

query = """
  query findPatients($search: String) {
    patients(search: $search) {
      data {
        id
        firstName
        lastName
        dob
        email
      }
    }
  }
"""

variables = {
  "search": "John Doe"
}

headers = {
    'Content-Type': 'application/json',
    'x-token': 'yourtoken',
}

response = requests.post(
    'https://open.semble.io/graphql',
    headers=headers,
    data=json.dumps({"query": query, "variables": variables})
)

print(response.json())

If you want to create a new patient, use the createPatient mutation. Make sure to replace the $first, $last, and $email placeholders with the correct patient's first name, last name, and email respectively.

curl

curl -X POST https://open.semble.io/graphql \
-H "Content-Type: application/json" \
-H "x-token: yourtoken" \
-d '{
  "query": "mutation createPatient($first: String, $last: String, $email: String) { createPatient(firstName: $first, lastName: $last, email: $email) { id } }",
  "variables": {"first": "John", "last": "Doe", "email": "john.doe@example.com"}
}'

Javascript

const fetch = require('node-fetch');

const query = `
  mutation createPatient($first: String, $last: String, $email: String) {
    createPatient(firstName: $first, lastName: $last, email: $email) {
      id
    }
  }
`;

const variables = {
  first: 'John',
  last: 'Doe',
  email: 'john.doe@example.com',
};

fetch('https://open.semble.io/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-token': 'yourtoken',
  },
  body: JSON.stringify({ query, variables }),
})
  .then((res) => res.json())
  .then((res) => console.log(res.data));

Python

import requests
import json

query = """
  mutation createPatient($first: String, $last: String, $email: String) {
    createPatient(firstName: $first, lastName: $last, email: $email) {
      id
    }
  }
"""

variables = {
  "first": "John",
  "last": "Doe",
  "email": "john.doe@example.com"
}

headers = {
    'Content-Type': 'application/json',
    'x-token': 'yourtoken',
}

response = requests.post(
    'https://open.semble.io/graphql',
    headers=headers,
    data=json.dumps({"query": query, "variables": variables})
)

print(response.json())

Step 3: Get a Questionnaire

To get a questionnaire, use the questionnaire query by providing a valid questionnaire ID. If you don't know the questionnaire ID, you might also consider taking a look at the questionnaires query.

curl

curl -X POST https://open.semble.io/graphql \
-H "Content-Type: application/json" \
-H "x-token: yourtoken" \
-d '{
  "query": "query questionnaire($questionnaireId: ID!) { questionnaire(id: $questionnaireId) { data { id title } } }",
  "variables": {"questionnaireId": "1"}
}'

Javascript

const fetch = require('node-fetch');

const query = `
  query questionnaire($questionnaireId: ID!) {
    questionnaire(id: $questionnaireId) {
      data {
        id
        title
      }
    }
  }
`;

const variables = {
  questionnaireId: '1',
};

fetch('https://open.semble.io/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-token': 'yourtoken',
  },
  body: JSON.stringify({ query, variables }),
})
  .then((res) => res.json())
  .then((res) => console.log(res.data));

Python

import requests
import json

query = """
  query questionnaire($questionnaireId: ID!) {
    questionnaire(id: $questionnaireId) {
      data {
        id
        title
      }
    }
  }
"""

variables = {
  "questionnaireId": "1"
}

headers = {
    'Content-Type': 'application/json',
    'x-token': 'yourtoken',
}

response = requests.post(
    'https://open.semble.io/graphql',
    headers=headers,
    data=json.dumps({"query": query, "variables": variables})
)

print(response.json())

Step 4: Insert Questionnaire Responses

To insert the responses from your questionnaire, use the fillQuestionnaire mutation with the correct questionnaire ID, patient ID and responses from your questionnaire.

curl

curl -X POST https://open.semble.io/graphql \
-H "Content-Type: application/json" \
-H "x-token: yourtoken" \
-d '{
  "query": "mutation fillQuestionnaire($questionnaireId: ID!, $patientId: ID!, $answers: [QuestionnaireAnswerInput!]!) { fillQuestionnaire(questionnaireId: $questionnaireId, patientId: $patientId, answers: $answers) { __typename } }",
  "variables": {"questionnaireId": "1", "patientId": "2", "answers": [{"questionId": "3", "answer": "answer12345"}]}
}'

Javascript

const fetch = require('node-fetch');

const query = `
  mutation fillQuestionnaire($questionnaireId: ID!, $patientId: ID!, $answers: [QuestionnaireAnswerInput!]!) {
    fillQuestionnaire(questionnaireId: $questionnaireId, patientId: $patientId, answers: $answers) {
      __typename
    }
  }
`;

const variables = {
  questionnaireId: '1',
  patientId: '2',
  answers: [
    {
      questionId: '3',
      answer: 'answer12345',
    },
  ],
};

fetch('https://open.semble.io/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-token': 'yourtoken',
  },
  body: JSON.stringify({ query, variables }),
})
  .then((res) => res.json())
  .then((res) => console.log(res.data));

Python

import requests
import json

query = """
  mutation FillQuestionnaire($questionnaireId: ID!, $patientId: ID!, $answers: [QuestionnaireAnswerInput!]!) {
    fillQuestionnaire(questionnaireId: $questionnaireId, patientId: $patientId, answers: $answers) {
      __typename
    }
  }
"""

variables = {
  "questionnaireId": "1",
  "patientId": "2",
  "answers": [
    {
      "questionId": "3",
      "answer": "answer12345"
    }
  ]
}

headers = {
    'Content-Type': 'application/json',
    'x-token': 'yourtoken',
}

response = requests.post(
    'https://open.semble.io/graphql',
    headers=headers,
    data=json.dumps({"query": query, "variables": variables})
)

print(response.json())

Additional notes

Please note that the answer field for QuestionnaireAnswerInput is expected to be of type QuestionnaireAnswerScalar. This is a custom type that makes it possible to have answers of different shapes based on question type and settings. Below are some examples of what's expected for this type:

• The answer to a question of type Relationship should be an object containing firstName, lastName, company, email, phoneNumber, address, city, postcode, country. If the relationship is of type Insurance provider, insurerPolicyNumber, insurerAuthorizationCode are also accepted.

• The answer to a question of type File upload should be an object containing name, type.

• The answer to a question of type Signature should be a single, valid base64 encoded string.

• The answer to a question of any other type with multiple answers allowed should be an array of valid, truthy strings.

• The answer to a question of any other type with a single answer allowed should be a valid, truthy string.

Also note that this guide assumes that you have a questionnaire set up in your practice in Semble. If you want to store responses of a 3rd party medical questionnaire, consider using the createFreeTextRecord mutation.

Congratulations! You've now learned how to store the responses of a questionnaire into Semble using the Semble public API.