Scorebuddy supports the insertion of cases and creation of scoring lists via the OpenAPI. In this article we will run through how to set up an API integration, creating meta data for the integration, inserting cases, and creating a scoring list that can be used within Scorebuddy.
Detail on all Scorebuddy endpoints can be found within our developer documentation by navigating to Admin > Developers > Documentation, or by requesting the yaml document via the API.
Setting up Scorebuddy to accept cases via the API
The first step required to utilize the API for inserting cases is to create an Internal integration within your Scorebuddy account.
This can be done by navigating to Score > Interactions and then selecting 'View Integrations'
From here select 'Add Integration' and then select the Scorebuddy Integration
You will be prompted to enter information to configure this integration:
- Label: The name given to the integration, used to identify the integration
- Description: You can give a description of the integration and what it is being used for
- Data retention policy: Can be use to set how long the information is stored within Scorebuddy. This can be configured in time frames of Days, Weeks, Months, Quarters, or Years
Once you have created the Internal integration we can move on to create the API client within Scorebuddy.
Creating your Scorebuddy API Client
Scorebuddy utilizes OAuths Client Credentials grant type for accessing information via the OpenAPI. (More information on this can be found at: https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/)
We must first set up our client in order to create the client ID and client secret for verification. These can be set up by navigating to Admin > Developers > API Clients
Within the API clients page you can see, access, edit or delete already created API clients. To add a new client select 'Add API Client'.
Within the pop up you can give the client a name which will generate the client ID and also determine the necessary scopes for the client (For adding cases via the API we will need to ensure that the client has the scopes 'integrations:read' and 'integrations:write'). Make sure to save the client secret before closing this page as it will not be visible again once the client is created.
With our API client set up we are now ready to start using the API.
Using the API
Step 1 - Requesting Bearer token
First we will need to request our bearer token for authentication. This can be done via an API platform such as Postman or programmatically (example code snippets below will be shown in Python using the requests module).
NB. ##{{URL}} in the below endpoints refers to your own Scorebuddy URL (eg https://www.cloud.scorebuddy.co.uk/1234567)
To request a bearer token you must make a POST request to ##{{url}}/api/v1/authorisation/token. You must ensure that when requesting your token that you also include the relevant scopes you wish the token to have. In our case we need to include 'integrations:read integrations:write' within a scope key.
Postman example:
Python request:
import requests
url = "https://www.cloud.scorebuddy.co.uk/1234567/api/v1/authorisation/token"
payload={
'grant_type': 'client_credentials',
'client_id': '<client_id>' #enter your own client id here
'client_secret': '<client_secret>' #enter your own client secret here
'scope': 'integrations:read integrations:write'
}
files=[]
headers = {}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)
Response example:
{
"token_type":"Bearer",
"expires_in":3600,
"access_token":"<bearer_token>"
}Step 2 - Getting our integration ID
In order to insert the chat case into our integration we must locate the ID of the integration we created previously. This can be achieved by making a GET request to ##{{url}}/api/v1/integrations.
Postman example:
Python request:
import requests
url = "https://www.cloud.scorebuddy.co.uk/1234567/api/v1/integrations"
payload={}
headers = {'Authorization': 'Bearer <bearer_token>} #insert your generated bearer token here
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
Example response:
{
"integrations": [
{
"integration_id": "a1b2c3d4",
"label": "API Integration",
"description": "API Integration",
"integration_type": "internal",
"group_ids": [],
"data_retention": {
"policy": "limited",
"rules": {
"interval": "years",
"numeracy": 1
}
},
"last_updated": null,
"created_by": 138,
"created_at": "2023-03-02T10:31:36+00:00"
}
],
"total": 1,
"next_page": null,
"previous_page": null
}Within the response body from this request we now have access to the integration ID. Note, if you have multiple integrations within your Scorebuddy account this request will return all of them, make sure to use the integration ID for the internal integration which was set up, this can be identified using the label field within the response.
Step 3 - Adding Meta Data to your integration
You may want to pass in various pieces of meta data with your cases to aid your evaluators in the scoring process. Before the integration will access a case with meta data the meta data itself must be configured within the integration.
The endpoint which we will be using to insert the meta data points into the integration is ##{{url}}/api/v1/integrations/{integration_id}/meta_data.
We can make a GET request to return all meta data points which have already been entered, or make a POST request to configure a new meta data point.
When making the POST request we must specify what the readable name of the data point is, its type, and whether it can be soft deleted (more information on the schema can be found within the Scorebuddy developer documentation and the yaml file).
Postman example:
Python Request:
import requests
import json
url = "https://www.cloud.scorebuddy.co.uk/1234567/api/v1/integrations/<integration_id>/meta_data" #Insert your own integration ID here
payload= json.dumps({
"readable_name": "Customer Location",
"data_type": "plain_text",
"deleted": False
})
headers = {
'Authorization': 'Bearer <bearer_token>, #insert your generated bearer token here
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
Example response:
{
"meta_data": {
"definition_name": "customer_location",
"readable_name": "Customer Location",
"data_type": "plain_text",
"deleted": false,
"created_by": 267,
"created_at": "2023-03-08T12:48:35+00:00"
}
}Step 4 - Inserting a chat case to the integration
Now that we have our integration ID and have configured some meta data for our integration we are now able to insert the case.
The chat case which we are inserting is below (Note that in this example we are inserting a chat type case however the integration can also be used for basic cases, email, or ticket cases. Schemas for these can be found within the documentation):
{
"staff_id": 831,
"case_type": "chat",
"external": {
"staff_id": "A-G35T4123",
"case_id": 15834597512
},
"messages": [
{
"message_id": 125487532985,
"body": "Hi, I would like to speak with someone from customer support",
"body_format": "html",
"sender_id": "A-G33T3932",
"sender_role": "customer",
"sender_name": null,
"sent_at": "2020-10-14T17:13:01+00:00"
},
{
"message_id": 125487532986,
"body": "You're through to customer support, how can I help?",
"body_format": "html",
"sender_id": "A-G35T4123",
"sender_role": "representative",
"sender_name": "AngelinaT Saville-Kent",
"sent_at": "2020-10-14T18:15:15+00:00"
},
{
"message_id": 125487532987,
"body": "I'm unable to locate my account number",
"body_format": "plain_text",
"sender_id": "A-G33T3932",
"sender_role": "customer",
"sender_name": null,
"sent_at": "2020-10-14T19:19:17+00:00"
},
{
"message_id": 125487532988,
"body": "Your account number can be found at the bottom of your most recent invoice",
"body_format": "html",
"sender_id": "A-G35T4123",
"sender_role": "representative",
"sender_name": "AngelinaT Saville-Kent",
"sent_at": "2020-10-14T20:35:29+00:00"
}
],
"meta_data": [
{
"name": "customer_location",
"value": "Ireland"
}
]
}The endpoint which we will be using to insert the case is ##{{url}}/api/v1/integrations/{integration_id}/cases/chat, more information on the schema needed can be found within the developer documentation or the yaml file.
Postman example:
Python Request:
import requests
import json
url = "https://www.cloud.scorebuddy.co.uk/1234567/api/v1/integrations/<integration_id>/cases/chat" #Insert your own integration ID here
payload= json.dumps({
"staff_id": 831,
"case_type": "chat",
"external": {
"staff_id": "A-G35T4123",
"case_id": 15834597512
},
"messages": [
{
"message_id": 125487532985,
"body": "Hi, I would like to speak with someone from customer support",
"body_format": "html",
"sender_id": "A-G33T3932",
"sender_role": "customer",
"sender_name": null,
"sent_at": "2020-10-14T17:13:01+00:00"
},
{
"message_id": 125487532986,
"body": "You're through to customer support, how can I help?",
"body_format": "html",
"sender_id": "A-G35T4123",
"sender_role": "representative",
"sender_name": "AngelinaT Saville-Kent",
"sent_at": "2020-10-14T18:15:15+00:00"
},
{
"message_id": 125487532987,
"body": "I'm unable to locate my account number",
"body_format": "plain_text",
"sender_id": "A-G33T3932",
"sender_role": "customer",
"sender_name": null,
"sent_at": "2020-10-14T19:19:17+00:00"
},
{
"message_id": 125487532988,
"body": "Your account number can be found at the bottom of your most recent invoice",
"body_format": "html",
"sender_id": "A-G35T4123",
"sender_role": "representative",
"sender_name": "AngelinaT Saville-Kent",
"sent_at": "2020-10-14T20:35:29+00:00"
}
],
"meta_data": [
{
"name": "customer_location",
"value": "Ireland"
}
]
}
headers = {
'Authorization': 'Bearer <bearer_token>, #insert your generated bearer token here
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
Example response:
{
"case": {
"case_id": "640899b9d7d27145880c68c5",
"staff_id": 831,
"case_type": "chat",
"external": {
"staff_id": "A-G35T4123",
"case_id": 15834597512
},
"messages": [
{
"message_id": 125487532985,
"body": "Hi, I would like to speak with someone from customer support",
"body_format": "html",
"sender_id": "A-G33T3932",
"sender_role": "customer",
"sender_name": null,
"sent_at": "2020-10-14T17:13:01+00:00"
},
{
"message_id": 125487532986,
"body": "You're through to customer support, how can I help?",
"body_format": "html",
"sender_id": "A-G35T4123",
"sender_role": "representative",
"sender_name": "AngelinaT Saville-Kent",
"sent_at": "2020-10-14T18:15:15+00:00"
},
{
"message_id": 125487532987,
"body": "I'm unable to locate my account number",
"body_format": "plain_text",
"sender_id": "A-G33T3932",
"sender_role": "customer",
"sender_name": null,
"sent_at": "2020-10-14T19:19:17+00:00"
},
{
"message_id": 125487532988,
"body": "Your account number can be found at the bottom of your most recent invoice",
"body_format": "html",
"sender_id": "A-G35T4123",
"sender_role": "representative",
"sender_name": "AngelinaT Saville-Kent",
"sent_at": "2020-10-14T20:35:29+00:00"
}
],
"meta_data": [
{
"name": "customer_location",
"value": "Ireland"
}
],
"created_by": 267,
"created_at": "2023-03-08T14:20:41+00:00",
"expire_at": "2024-03-08T14:20:41+00:00"
}
}Note that when we insert the chat case a case_id is generated. It is important to note this as it is required to identify which case is used when creating a list. Making a GET request to ##{{url}}/api/v1/integrations/{integration_id}/cases/chat will return all of the inserted cases with their case ID's.
Step 5 - Creating a scoring list
The final step required now that we have our case inserted is to create a scoring list using that case.
To do this you will need to make a POST request to ##{{url}}/api/v1/integrations/{integration_id}/lists.
Again this can be done via an API program or programmatically.
The schema can be found within the developer documentation. Points to note regarding the assignment is that it is a group of arrays into which we insert the id of the particular group/team/user we want to assign the list to. We also need to ensure that we use the case_id for the cases we have inserted which we want to use in the scoring list
Postman example:
Python Request:
import requests
import json
url = "https://www.cloud.scorebuddy.co.uk/1234567/api/v1/integrations/<integration_id>/meta_data" #Insert your own integration ID here
payload= json.dumps({
"list_name": "API List",
"list_type": "all",
"assignment": {
"group_ids": [37],
"team_ids": [],
"user_ids": []
},
"cases": [
"640899b9d7d27145889c68c5"
],
"schedule": "none",
"deleted": False,
"settings": {
"next_case": True
}
})
headers = {
'Authorization': 'Bearer <bearer_token>, #insert your generated bearer token here
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
Example response:
{
"list": {
"list_id": 197,
"integration_id": "a30b15621d6",
"list_name": "API List",
"list_type": "all",
"assignment": {
"group_ids": [
37
],
"team_ids": [],
"user_ids": []
},
"cases": [
"640899b9d7d27145880c68c5"
],
"schedule": "none",
"deleted": false,
"settings": {
"next_case": true
},
"created_by": 267,
"created_at": "2023-03-08T14:43:04+00:00"
}
}Your create list should now be accessible on Scorebuddy within the interactions tab.