EndAssessment

POST - /v3/api/assessment/end

Required Permissions:

scope:api

Description

Uploads assessment data for storage and processing. Upon uploading of assessment data, vocal processing will begin (if applicable).

Responses provided in body will depend on survey. Please consult your customer documentation under the Sample Responses section for a survey-specific example of this request body.

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

Body Parameters

Name	Type	Description
* assessmentId	uuid	The ID of the assessment
responseData	array<object>	The static responses associated with this assessment. NOTE Contents may vary. Do not blindly use example below, consult survey documentation.

Successful Response

A successful response

Field Name	Type	Description
message	string	"OK"

Code Example

cURL

curl \
  -X POST "https://rest.eus.canaryspeech.com/v3/api/assessment/end" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" \
  -H "Content-Type: application/json" \
  -d "{ \"assessmentId\": \"0192530c-4ce5-7aa1-be9b-bc52dec8a184\", \"responseData\": [ { \"timestamp\": \"2024-10-12T04:40:35.848Z\", \"code\": \"free_speech\", \"type\": \"recordedResponse\", \"data\": { \"filename\": \"Sample__00000000-0000-0000-0000-000000000000.wav\", \"duration\": 56 } }, { \"timestamp\": \"2024-10-12T04:40:35.848Z\", \"code\": \"GAD7_1\", \"type\": \"multipleChoice\", \"data\": { \"answer\": 0 } } ] }"

JavaScript (Fetch)

function postV3ApiAssessmentEnd() {

  const url = 'https://rest.eus.canaryspeech.com/v3/api/assessment/end';
  
  const headers = {
    Authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
    'Content-Type': 'application/json'
  };
  
  const body = {
    assessmentId: '0192530c-4ce5-7aa1-be9b-bc52dec8a184',
    responseData: [
      {
        timestamp: '2024-10-12T04:40:35.848Z',
        code: 'free_speech',
        type: 'recordedResponse',
        data: {
          filename: 'Sample__00000000-0000-0000-0000-000000000000.wav',
          duration: 56
        }
      },
      {
        timestamp: '2024-10-12T04:40:35.848Z',
        code: 'GAD7_1',
        type: 'multipleChoice',
        data: { answer: 0 }
      }
    ]
  };
  
  fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(body)
  }).then((response) => {
    if (!response.ok) throw new Error(response.status);
    return response.json()
  }).then((json) => {
    const { message } = json;
    // ...
  });
}

JavaScript (Node)

const https = require('https');

function postV3ApiAssessmentEnd() {

  
  const headers = {
    Authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
    'Content-Type': 'application/json'
  };
  
  const body = {
    assessmentId: '0192530c-4ce5-7aa1-be9b-bc52dec8a184',
    responseData: [
      {
        timestamp: '2024-10-12T04:40:35.848Z',
        code: 'free_speech',
        type: 'recordedResponse',
        data: {
          filename: 'Sample__00000000-0000-0000-0000-000000000000.wav',
          duration: 56
        }
      },
      {
        timestamp: '2024-10-12T04:40:35.848Z',
        code: 'GAD7_1',
        type: 'multipleChoice',
        data: { answer: 0 }
      }
    ]
  };
  
  const options = {
    hostname: 'rest.eus.canaryspeech.com',
    port: 443,
    path: '/v3/api/assessment/end',
    method: 'POST',
    headers: headers
  };
  
  const request = https.request(options, (response) => {
    if (response.statusCode !== 200) throw new Error(response.statusCode);
    
    response.on('data', (d) => {
      const { message } = JSON.parse(d);
      // ...
    });
  });
  
  request.on('error', (err) => {
    throw new Error(err);
  });
  
  request.write(JSON.stringify(body));
  request.end();
  
}

JavaScript (Axios)

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

async function postV3ApiAssessmentEnd() {

  const url = 'https://rest.eus.canaryspeech.com/v3/api/assessment/end';
  
  const headers = {
    Authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
    'Content-Type': 'application/json'
  };
  
  const body = {
    assessmentId: '0192530c-4ce5-7aa1-be9b-bc52dec8a184',
    responseData: [
      {
        timestamp: '2024-10-12T04:40:35.848Z',
        code: 'free_speech',
        type: 'recordedResponse',
        data: {
          filename: 'Sample__00000000-0000-0000-0000-000000000000.wav',
          duration: 56
        }
      },
      {
        timestamp: '2024-10-12T04:40:35.848Z',
        code: 'GAD7_1',
        type: 'multipleChoice',
        data: { answer: 0 }
      }
    ]
  };
  
  const response = await axios.post(url, body, { headers });
  
  if (response.status !== 200) throw new Error(response.status);
  
  const { message } = response.data;
  
  // ...
}

TypeScript (Node)

import * as https from 'https';

function postV3ApiAssessmentEnd(): void {

  
  const headers = {
    Authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
    'Content-Type': 'application/json'
  };
  
  const body = {
    assessmentId: '0192530c-4ce5-7aa1-be9b-bc52dec8a184',
    responseData: [
      {
        timestamp: '2024-10-12T04:40:35.848Z',
        code: 'free_speech',
        type: 'recordedResponse',
        data: {
          filename: 'Sample__00000000-0000-0000-0000-000000000000.wav',
          duration: 56
        }
      },
      {
        timestamp: '2024-10-12T04:40:35.848Z',
        code: 'GAD7_1',
        type: 'multipleChoice',
        data: { answer: 0 }
      }
    ]
  };
  
  const options = {
    hostname: 'rest.eus.canaryspeech.com',
    port: 443,
    path: '/v3/api/assessment/end',
    method: 'POST',
    headers: headers
  };
  
  const request = https.request(options, (response) => {
    if (response.statusCode !== 200) throw new Error(response.statusCode);
    
    response.on('data', (d) => {
      const { message } = JSON.parse(d) as Record<string, unknown>;
      // ...
    });
  });
  
  request.on('error', (err) => {
    throw new Error(err);
  });
  
  request.write(JSON.stringify(body));
  request.end();
}

TypeScript (Axios)

import axios from 'axios';

async function postV3ApiAssessmentEnd(): Promise<void> {

  const url = 'https://rest.eus.canaryspeech.com/v3/api/assessment/end';
  
  const headers = {
    Authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
    'Content-Type': 'application/json'
  };
  
  const body = {
    assessmentId: '0192530c-4ce5-7aa1-be9b-bc52dec8a184',
    responseData: [
      {
        timestamp: '2024-10-12T04:40:35.848Z',
        code: 'free_speech',
        type: 'recordedResponse',
        data: {
          filename: 'Sample__00000000-0000-0000-0000-000000000000.wav',
          duration: 56
        }
      },
      {
        timestamp: '2024-10-12T04:40:35.848Z',
        code: 'GAD7_1',
        type: 'multipleChoice',
        data: { answer: 0 }
      }
    ]
  };
  
  const response = await axios.post(url, body, { headers });
  
  if (response.status !== 200) throw new Error(response.status);
  
  const { message } = response.data;
  // ...
}

Python (Requests)

import requests

def post_v3_api_assessment_end():
    url = 'https://rest.eus.canaryspeech.com/v3/api/assessment/end'
    
    headers = {
        'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
        'Content-Type': 'application/json'
    }
    
    body = {
        'assessmentId': '0192530c-4ce5-7aa1-be9b-bc52dec8a184',
        'responseData': [
            {
                'timestamp': '2024-10-12T04:40:35.848Z',
                'code': 'free_speech',
                'type': 'recordedResponse',
                'data': {
                    'filename': 'Sample__00000000-0000-0000-0000-000000000000.wav',
                    'duration': 56
                }
            },
            {
                'timestamp': '2024-10-12T04:40:35.848Z',
                'code': 'GAD7_1',
                'type': 'multipleChoice',
                'data': {
                    'answer': 0
                }
            }
        ]
    }
    
    response = requests.post(
        url,
        headers=headers,
        data=body,
    )
    
    if response.status_code !== 200:
        raise Exception(response.status_code)
    
    response_obj = response.json()
    message = response_obj['message']
    
    # ...

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 postV3ApiAssessmentEnd() {
    URI uri = new URI("https://rest.eus.canaryspeech.com/v3/api/assessment/end");
    
    JSONObject body$responseData$0$data = new JSONObject();
    body$responseData$0$data.put("filename", "Sample__00000000-0000-0000-0000-000000000000.wav");
    body$responseData$0$data.put("duration", new Integer(56));
    
    JSONObject body$responseData$0 = new JSONObject();
    body$responseData$0.put("timestamp", "2024-10-12T04:40:35.848Z");
    body$responseData$0.put("code", "free_speech");
    body$responseData$0.put("type", "recordedResponse");
    body$responseData$0.put("data", body$responseData$0$data);
    JSONObject body$responseData$1$data = new JSONObject();
    body$responseData$1$data.put("answer", new Integer(0));
    
    JSONObject body$responseData$1 = new JSONObject();
    body$responseData$1.put("timestamp", "2024-10-12T04:40:35.848Z");
    body$responseData$1.put("code", "GAD7_1");
    body$responseData$1.put("type", "multipleChoice");
    body$responseData$1.put("data", body$responseData$1$data);
    
    
    JSONArray body$responseData = new JSONArray();
    body$responseData.add(body$responseData$0);
    body$responseData.add(body$responseData$1);
    
    JSONObject body = new JSONObject();
    body.put("assessmentId", "0192530c-4ce5-7aa1-be9b-bc52dec8a184");
    body.put("responseData", body$responseData);
    
    byte[] bodyBytes = JSONValue.toJSONString(body).getBytes(StandardCharsets.UTF_8);
    
    HttpRequest request = HttpRequest.newBuilder()
      .uri(uri)
      .version(HttpClient.Version.HTTP_2)
      .header("Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c")
      .header("Content-Type", "application/json")
      .POST(BodyPublishers.ofByteArray(bodyBytes))
      .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());
    String message = (String) responseBody.get("message");
    
    // ...
  }

}

Kotlin

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

suspend fun postV3ApiAssessmentEnd() = runCatching {
    val url = URL.create("https://rest.eus.canaryspeech.com/v3/api/assessment/end")
    with(url.openConnection() as HttpsURLConnection) {
        requestMethod = "POST"
        instanceFollowRedirects = true
        
        setRequestProperty("Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c")
        setRequestProperty("Content-Type", "application/json")
        
        doInput = true
        setChunkedStreamingMode(0)
        
        val body$responseData$0$data = JSONObject()
        body$responseData$0$data.put("filename", String("Sample__00000000-0000-0000-0000-000000000000.wav"))
        body$responseData$0$data.put("duration", Integer(56))
        
        val body$responseData$0 = JSONObject()
        body$responseData$0.put("timestamp", String("2024-10-12T04:40:35.848Z"))
        body$responseData$0.put("code", String("free_speech"))
        body$responseData$0.put("type", String("recordedResponse"))
        body$responseData$0.put("data", body$responseData$0$data)
        val body$responseData$1$data = JSONObject()
        body$responseData$1$data.put("answer", Integer(0))
        
        val body$responseData$1 = JSONObject()
        body$responseData$1.put("timestamp", String("2024-10-12T04:40:35.848Z"))
        body$responseData$1.put("code", String("GAD7_1"))
        body$responseData$1.put("type", String("multipleChoice"))
        body$responseData$1.put("data", body$responseData$1$data)
        
        
        val body$responseData = JSONArray()
        body$responseData.add(body$responseData$0)
        body$responseData.add(body$responseData$1)
        
        val body = JSONObject()
        body.put("assessmentId", String("0192530c-4ce5-7aa1-be9b-bc52dec8a184"))
        body.put("responseData", body$responseData)
        
        outputStream.bufferedWriter(Charsets.UTF_8).use {
            it.write(body.toString())
            it.flush()
        }
        
        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 message = responseBody.get("message") as String
        
        // ...
    }
}

Swift (URLSession)

import UIKit

func postV3ApiAssessmentEnd() -> void {
    
    let url = URL("https://rest.eus.canaryspeech.com/v3/api/assessment/end")
    
    let headers: [String: String] = [
        "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
        "Content-Type": "application/json"
    ]
    
    let body: [String: Any] = [
        "assessmentId": "0192530c-4ce5-7aa1-be9b-bc52dec8a184",
        "responseData": [
            [
                "timestamp": "2024-10-12T04:40:35.848Z",
                "code": "free_speech",
                "type": "recordedResponse",
                "data": [
                    "filename": "Sample__00000000-0000-0000-0000-000000000000.wav",
                    "duration": 56
                ]
            ],
            [
                "timestamp": "2024-10-12T04:40:35.848Z",
                "code": "GAD7_1",
                "type": "multipleChoice",
                "data": [ "answer": 0 ]
            ]
        ]
    ]
    
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.allHTTPHeaderFields = headers
    request.httpBody = JSONEncoder().encode(body)
    
    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(PostV3ApiAssessmentEndResponse.self, data)
            // ...
        } catch {
            print(error)
        }
    }
    }
}

struct PostV3ApiAssessmentEndResponse: Decodable {
    let message: String
}

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 postV3ApiAssessmentEnd()
    {
        var url = "https://rest.eus.canaryspeech.com/v3/api/assessment/end\"";
        
        var body = new Dictionary<string, dynamic> {
            { "assessmentId": "0192530c-4ce5-7aa1-be9b-bc52dec8a184" },
            { "responseData": new[] {
                new Dictionary<string, dynamic> {
                    { "timestamp": "2024-10-12T04:40:35.848Z" },
                    { "code": "free_speech" },
                    { "type": "recordedResponse" },
                    { "data": new Dictionary<string, dynamic> {
                        { "filename": "Sample__00000000-0000-0000-0000-000000000000.wav" },
                        { "duration": 56
                    }
                },
                new Dictionary<string, dynamic> {
                    { "timestamp": "2024-10-12T04:40:35.848Z" },
                    { "code": "GAD7_1" },
                    { "type": "multipleChoice" },
                    { "data": new Dictionary<string, dynamic> { { "answer": 0 }
                }
            }
        };
        var bodyString = JsonConvert.Serialize(body);
        
        var request = new HttpRequestMessage(HttpMethod.Post, url);
        request.Headers.Add("Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c");
        request.Headers.Add("Content-Type", "application/json");
        request.Content = new ByteArrayContent(Encoding.UTF8.GetBytes(bodyString));
        
        var response = await client.SendAsync(request);
        response.EnsureSuccessStatusCode();
        
        var responseBody = await response.Content.ReadAsStringAsync();
        var responseJson = JsonConvert.DeserializeObject<Dictionary<string, dynamic>>(responseBody);
        var message = (String)responseJson["message"];
        // ...
    }
}

Dart/Flutter

import 'dart:convert';

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

Future<void> function postV3ApiAssessmentEnd() async {
  final uri = Uri.https('rest.eus.canaryspeech.com', 'v3/api/assessment/end', queryParams);
  
  final headers = {
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
    'Content-Type': 'application/json'
  };
  
  final body =  {
    'assessmentId': '0192530c-4ce5-7aa1-be9b-bc52dec8a184',
    'responseData': [
      {
        'timestamp': '2024-10-12T04:40:35.848Z',
        'code': 'free_speech',
        'type': 'recordedResponse',
        'data': {
          'filename': 'Sample__00000000-0000-0000-0000-000000000000.wav',
          'duration': 56
        }
      },
      {
        'timestamp': '2024-10-12T04:40:35.848Z',
        'code': 'GAD7_1',
        'type': 'multipleChoice',
        'data': { 'answer': 0 }
      }
    ]
  };
  
  final request = http.Request('POST', uri);
  request.headers.addAll(headers)
  request.body = json.encode(body);
  
  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 message = response['message'] as String;
    
    // ...
  } catch (e) {
    print(e);
  }
}

Models

responseData.[]

Name	Type	Description
timestamp	date-time	The ISO-8601 timestamp of when this response was recorded.
code	string	The code of the response, used to identify what part of the survey it is used for e.g. "free_speech", "GAD7_1", etc...
type	string	Indicates what type of data is in the response. See "Responses and Scores" section of this documentation for more information.
data	object	An object containing the response data. Contents may vary, consult survey documentation.