ListScores

GET - /v3/api/list-scores

Required Permissions:

scope:api

Description

Either the session ID or assessment ID must be provided.

Headers

Header Key	Description	Example
Authorization	The Authorization header for this endpoint. The value must be the token from the /v3/auth/tokens/get endpoint and given using the Bearer pattern.	Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdW...
Content-Type	The content type for this request.	application/json

Query Parameters

Name	Type	Description
sessionId	string	The ID of the session to query.
assessmentId	string	The ID of the assessment to query.
includeErrors	string	Whether to return scores that have errored out, use for getting information about assessment or scoring failures. Can either be false or true, defaults to false.

Successful Response

A successful response

Field Name	Type	Description
scores	array<object>	A list of score objects for the requested assessment. See below to find more details.

Code Example

cURL

curl \
  -X GET "https://rest.eus.canaryspeech.com/v3/api/list-scores?sessionId=abc123&assessmentId=abc123&includeErrors=abc123" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
  -H "Content-Type: application/json"

JavaScript (Fetch)

function getV3ApiListScores() {

  const url = 'https://rest.eus.canaryspeech.com/v3/api/list-scores?sessionId=abc123&assessmentId=abc123&includeErrors=abc123';
  
  const headers = {
    Authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
    'Content-Type': 'application/json'
  };
  
  fetch(url, {
    method: 'GET',
    headers: headers
  }).then((response) => {
    if (!response.ok) throw new Error(response.status);
    return response.json()
  }).then((json) => {
    const { scores } = json;
    // ...
  });
}

JavaScript (Node)

const https = require('https');

function getV3ApiListScores() {

  
  const headers = {
    Authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
    'Content-Type': 'application/json'
  };
  
  const options = {
    hostname: 'rest.eus.canaryspeech.com',
    port: 443,
    path: '/v3/api/list-scores',
    method: 'GET',
    qs: { sessionId: 'abc123', assessmentId: 'abc123', includeErrors: 'abc123' },
    headers: headers
  };
  
  const request = https.request(options, (response) => {
    if (response.statusCode !== 200) throw new Error(response.statusCode);
    
    response.on('data', (d) => {
      const { scores } = JSON.parse(d);
      // ...
    });
  });
  
  request.on('error', (err) => {
    throw new Error(err);
  });
  
  request.end();
  
}

JavaScript (Axios)

const axios = require('axios').default;

async function getV3ApiListScores() {

  const url = 'https://rest.eus.canaryspeech.com/v3/api/list-scores?sessionId=abc123&assessmentId=abc123&includeErrors=abc123';
  
  const headers = {
    Authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
    'Content-Type': 'application/json'
  };
  
  const response = await axios.get(url, { headers });
  
  if (response.status !== 200) throw new Error(response.status);
  
  const { scores } = response.data;
  
  // ...
}

TypeScript (Node)

import * as https from 'https';

function getV3ApiListScores(): void {

  
  const headers = {
    Authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
    'Content-Type': 'application/json'
  };
  
  const options = {
    hostname: 'rest.eus.canaryspeech.com',
    port: 443,
    path: '/v3/api/list-scores',
    method: 'GET',
    qs: { sessionId: 'abc123', assessmentId: 'abc123', includeErrors: 'abc123' },
    headers: headers
  };
  
  const request = https.request(options, (response) => {
    if (response.statusCode !== 200) throw new Error(response.statusCode);
    
    response.on('data', (d) => {
      const { scores } = JSON.parse(d) as Record<string, unknown>;
      // ...
    });
  });
  
  request.on('error', (err) => {
    throw new Error(err);
  });
  
  request.end();
}

TypeScript (Axios)

import axios from 'axios';

async function getV3ApiListScores(): Promise<void> {

  const url = 'https://rest.eus.canaryspeech.com/v3/api/list-scores?sessionId=abc123&assessmentId=abc123&includeErrors=abc123';
  
  const headers = {
    Authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
    'Content-Type': 'application/json'
  };
  
  const response = await axios.get(url, { headers });
  
  if (response.status !== 200) throw new Error(response.status);
  
  const { scores } = response.data;
  // ...
}

Python (Requests)

import requests

def get_v3_api_list_scores():
    url = 'https://rest.eus.canaryspeech.com/v3/api/list-scores'
    
    headers = {
        'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
        'Content-Type': 'application/json'
    }
    
    response = requests.get(
        url,
        params={
            'sessionId': 'abc123',
            'assessmentId': 'abc123',
            'includeErrors': 'abc123'
        },
        headers=headers,
    )
    
    if response.status_code !== 200:
        raise Exception(response.status_code)
    
    response_obj = response.json()
    scores = response_obj['scores']
    
    # ...

Java

import org.json.simple.JSONObject;
import org.json.simple.JSONArray;
import org.json.simple.JSONParser;
import org.json.simple.JSONValue;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.Map;

public class CanarySpeechApi {

  public void getV3ApiListScores() {
    URI uri = new URI("https://rest.eus.canaryspeech.com/v3/api/list-scores?sessionId=abc123&assessmentId=abc123&includeErrors=abc123");
    
    HttpRequest request = HttpRequest.newBuilder()
      .uri(uri)
      .version(HttpClient.Version.HTTP_2)
      .header("Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c")
      .header("Content-Type", "application/json")
      .GET()
      .build();
    
    HttpClient client = HttpClient.newBuilder()
      .version(HttpClient.Version.HTTP_1_1)
      .build();
    
    HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
    
    if (client.status != 200) {
      throw new Exception(client.status.toString());
    }
    
    JSONParser parser = new JSONParser();
    JSONObject responseBody = (JSONObject) parser.parse(client.body());
    List<Object> scores = (List<Object>) responseBody.get("scores");
    
    // ...
  }

}

Kotlin

import org.json.JSONObject
import java.lang.StringBuilder
import java.net.URL
import javax.net.ssl.HttpsURLConnection

suspend fun getV3ApiListScores() = runCatching {
    val url = URL.create("https://rest.eus.canaryspeech.com/v3/api/list-scores?sessionId=abc123&assessmentId=abc123&includeErrors=abc123")
    with(url.openConnection() as HttpsURLConnection) {
        requestMethod = "GET"
        instanceFollowRedirects = true
        
        setRequestProperty("Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c")
        setRequestProperty("Content-Type", "application/json")
        
        doOutput = true
        
        if (responseCode != 200) throw Error(responseMessage)
        
        val buffer = StringBuilder()
        var line: String?
        inputStream.bufferedReader(Charsets.UTF-8).use {
            do {
                line = it.readLine()
                if (line != null) buffer.appendLine(line)
            } while (line != null)
        }
        
        val responseBody = JSONObject(buffer.toString())
        val scores = responseBody.get("scores") as Array<Object>
        
        // ...
    }
}

Swift (URLSession)

import UIKit

func getV3ApiListScores() -> void {
    
    let url = URL("https://rest.eus.canaryspeech.com/v3/api/list-scores?sessionId=abc123&assessmentId=abc123&includeErrors=abc123")
    
    let headers: [String: String] = [
        "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
        "Content-Type": "application/json"
    ]
    
    var request = URLRequest(url: url)
    request.httpMethod = "GET"
    request.allHTTPHeaderFields = headers
    
    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        guard
            let data = data,
            let response = response as? HTTPURLResponse,
            error == nil
        else {
            print("error", error ?? URLError(.badServerResponse)
            return
        }
        
        guard (200 ... 299) ~= response.statusCode else {
            print("statusCode = \(response.statusCode)")
            print("response = \(response)")
            return
        }
        
        do {
            let responseObj = try JSONDecoder().decode(GetV3ApiListScoresResponse.self, data)
            // ...
        } catch {
            print(error)
        }
    }
    }
}

struct GetV3ApiListScoresResponse: Decodable {
    let scores: [undefined]
}

using System.Collections.Generic;
using System.Net.Http;
using System.Text.Encoding;
using System.Text.Json;
using System.Text.Json.Serialization;

public static class CanarySpeechAPI
{
    public static readonly HttpClient client = new HttpClient();
    
    public static async Task getV3ApiListScores()
    {
        var url = "https://rest.eus.canaryspeech.com/v3/api/list-scores?sessionId=abc123&assessmentId=abc123&includeErrors=abc123\"";
        
        var request = new HttpRequestMessage(HttpMethod.Get, url);
        request.Headers.Add("Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c");
        request.Headers.Add("Content-Type", "application/json");
        
        var response = await client.SendAsync(request);
        response.EnsureSuccessStatusCode();
        
        var responseBody = await response.Content.ReadAsStringAsync();
        var responseJson = JsonConvert.DeserializeObject<Dictionary<string, dynamic>>(responseBody);
        var scores = (List<undefined>)responseJson["scores"];
        // ...
    }
}

Dart/Flutter

import 'dart:convert';

import 'package:http/http.dart' as http;

Future<void> function getV3ApiListScores() async {
  final queryParams = { 'sessionId': 'abc123', 'assessmentId': 'abc123', 'includeErrors': 'abc123' };
  
  final uri = Uri.https('rest.eus.canaryspeech.com', 'v3/api/list-scores', queryParams);
  
  final headers = {
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
    'Content-Type': 'application/json'
  };
  
  final request = http.Request('GET', uri);
  request.headers.addAll(headers)
  
  final client = http.Client();
  try {
    final responseStream = await client.send(request);
    final statusCode = responseStream.statusCode;
    
    if (statusCode < 200 || statusCode >= 300) {
      throw Error(statusCode.toString());
    }
    
    final responseBytes = await responseStream.stream.toBytes();
    final responseString = utf8.decode(responseBytes);
    final response = json.decode(responseString);
    
    final scores = response['scores'] as List<dynamic>;
    
    // ...
  } catch (e) {
    print(e);
  }
}

Models

scores.[]

Name	Type	Description
code	string	The code of the score. Use this to identify which score this is e.g. Anxiety_Overall or Depression_Overall.
timestamp	date-time	The ISO-8601 timestamp of when the score was calculated.
source	string	Note: This value is not recommended for general client use. Normally the score's code value will be more useful. This value identifies what produced the score, whether a model (Depression, Anxiety, EnergyScore, ...) or a function (sum, count, composite, ...).
type	unknown	A value indicating where the score originated.
data	object

scores.[].data

Name	Type	Description
result	unknown	An object containing the score's data. Contents may vary, consult survey documentation.
error	object	An object containing any error information if present. Will only be present if includeErrors is set to true and an error occurred in scoring.

scores.[].data.error

An object containing any error information if present. Will only be present if includeErrors is set to true and an error occurred in scoring.

Name	Type	Description
status	string	Error status code. More info here.
title	string	Basic summary of error
detail	string	A description of what went wrong.
innerErrors	array<object>	An array of errors related to this error.