The Semble Public API enables clinics to access specific data and functionalities from Semble and integrate them into their existing software. This service is available to all Semble clinics at no extra cost.

The Semble API is based on GraphQL as its query language.

GraphQL (GQL) is rapidly becoming the API standard across many software development landscapes. Here are a few reasons why GQL is gaining popularity:

Precise data fetching: Clients can specify exactly what they want from a server, minimising the risk of over-fetching or under-fetching data.
Flexibility: GQL is highly flexible, allowing client-side changes without requiring additional work on the server side.
Efficient data retrieval: With GQL, you can retrieve multiple resources in a single request. Unlike REST APIs, which often require multiple requests to different endpoints, GQL can fetch all the data an app needs in one go.
Type and field-based structure: GQL APIs are organized by types and fields, rather than endpoints. This ensures apps only request what is possible, while providing clearer and more helpful error messages.
Legacy system integration: GQL APIs can still integrate with legacy REST systems, providing a bridge between newer and older architectures.

For more information on the GQL, see here.

You can send GraphQL requests to the following Semble API endpoint:

Live Environment

Generating an API Key

If you would like to use our APIs you will be able to generate your API key as below.

1. Go to "Settings"

2. Scroll all the way down and click on "API Access" on the left

You will see the page below:

3. Click "New" in the top right hand corner

4. You are able to change the name of your credentials if you wish and then assign a role to this:

Please note that API access may or may not be available to you depending on your Semble package and/or role. If you have questions about whether you have access to our APIs please email support@semble.io

Authentication Token Expiry

Authentication tokens last for 12 hours. It is recommended that you sign in at the start of every day.

For more information, see here.

Data Available With the Semble API

For a full list of what is available from the Semble API, see here.

API Request Limit

At the moment you can send the Semble API 240 requests per minute.

Benefits of Using the Semble API

The Semble API offers several ways for your clinic to enhance its workflows and integrate with other systems. Here are some ways your clinic could benefit:

- Custom Reporting
  Retrieve more detailed analytical data than what’s available on the Semble Analytics page, enabling deeper insights and custom reporting tailored to your clinic’s needs.
- Bespoke Booking Systems
  Create a custom booking system with your own user interface (UI) and personalized questions on your website. When a patient books an appointment through your system, the data can be forwarded to Semble for seamless management and scheduling.
- CRM Integration
  Incorporate Semble into your marketing and sales workflows. For example, every time a new patient is added to Semble, their information can be sent to your CRM system, where you can generate follow-up opportunities or campaigns.
- Application Integrations
  If there are specific features or functionalities you need that Semble doesn’t currently offer, you can integrate Semble’s data with other applications. This allows you to enhance your clinic’s operations while keeping patient records consistent and up-to-date across platforms.
- Third-Party Medical Questionnaires
  You can use the Semble Public API to store the answers from third-party medical questionnaires directly into Semble. This can help streamline the intake process and ensure that all patient data is consolidated in one place.

For more information, see here.

Queries in GraphQL (GQL)

Click here to see the list of available queries on Semble.

In GraphQL (GQL), a query is a request to the server to retrieve data. Queries are the most common operation you’ll use when interacting with a GraphQL service because they allow you to fetch exactly the data you need, no more, no less.

Each query consists of a root field that defines the type of data you want, and then the fields you specify after it determine exactly what data should be returned. You can also use arguments to further filter or refine the data you're requesting.

For example, here's a simple query to fetch a patient's name and age:

The server will respond with the data for that specific patient:

You can also make more complex queries with multiple fields, nested objects, and arguments.

To learn more about queries, you can visit the official GQL website here.

Mutations in GraphQL (GQL)

Click here to see the list of available mutations on Semble.

In GraphQL (GQL), a mutation is a request to the server that allows you to create, update, or delete data. Mutations are similar to queries, but instead of retrieving data, they modify it in some way.

Each mutation has a root field, which is the main action or operation you're asking the server to perform.

After the root field, you include the payload, which consists of the specific data or changes you want to apply.

You can add more fields to the payload to request additional information to be mutated.

For example, here’s a mutation that creates a new patient in a practice's database:

The response to this mutation might look like this:

With mutations, you can also delete or update data, depending on your needs. The process remains flexible, allowing you to customise the payload and arguments to fit your specific use case.

To learn more about mutations, you can visit the official GQL website here.

Types in GraphQL (GQL)

In GraphQL (GQL), the service defines a set of types that describe the possible data you can query.

This set of definitions is called the schema. The schema is central to understanding how to work with GraphQL, as it outlines the types of data available, as well as how to interact with it.

The core components of a GraphQL schema are object types, which represent the types of objects you can retrieve from the service.

Click here to see the list of available objects on Semble.

Each object type will have specific fields that are available for querying. The fields can vary in data types and may have specific requirements.

Example of an Object Type:

Let’s look at an example of an object type:

type Patient { name: String! insurance: [Insurance!]! }

Patient: This is the object type. It represents a patient object, which you can query for data.
name and insurance: These are the fields within the Patient object type. These are the specific pieces of data that you can query about a patient.
- String!: The name field is a text-based value (String). The exclamation mark (!) indicates that this field is required — meaning that the GQL service will always return a value for this field when queried.
- [Insurance!]!: This field represents an array of Insurance objects. The first exclamation mark after the square brackets indicates that the array cannot be null, and the second exclamation mark indicates that each individual Insurance object in the array is required.

To learn more about types, you can visit the official GQL website here.

Customising Queries with Arguments

Queries, mutations and object type can also accept arguments. These arguments allow you to customise the data returned in your query.

For example, you can specify which insurance providers to retrieve or limit the number of results returned.

To dive deeper into types and how to structure your queries, visit the official GraphQL website here.