PollAssessmentStatus

GET - /v3/api/assessment/poll

Required Permissions:

scope:api

Description

Poll the status for an assessment. Use this endpoint after ending an assessment to poll for score availability.

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
assessmentId	string	The ID of the assessment to poll.

Successful Response

A successful response

Field Name	Type	Description
status	string	The status of the assessment. Lies in one of four states: created, processing, completed, and failed.
createdAt	date-time	ISO 8601 date-time timestamp for when the assessment was started.
lastChangedAt	date-time	ISO 8601 date-time timestamp for when the assessment status last changed.

Code Example

cURL

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

JavaScript (Fetch)

function getV3ApiAssessmentPoll() {

  const url = 'https://rest.eus.canaryspeech.com/v3/api/assessment/poll?assessmentId=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 { status, createdAt, lastChangedAt } = json;
    // ...
  });
}

JavaScript (Node)

const https = require('https');

function getV3ApiAssessmentPoll() {

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

JavaScript (Axios)

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

async function getV3ApiAssessmentPoll() {

  const url = 'https://rest.eus.canaryspeech.com/v3/api/assessment/poll?assessmentId=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 { status, createdAt, lastChangedAt } = response.data;
  
  // ...
}

TypeScript (Node)

import * as https from 'https';

function getV3ApiAssessmentPoll(): 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/assessment/poll',
    method: 'GET',
    qs: { assessmentId: 'abc123' },
    headers: headers
  };
  
  const request = https.request(options, (response) => {
    if (response.statusCode !== 200) throw new Error(response.statusCode);
    
    response.on('data', (d) => {
      const { status, createdAt, lastChangedAt } = 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 getV3ApiAssessmentPoll(): Promise<void> {

  const url = 'https://rest.eus.canaryspeech.com/v3/api/assessment/poll?assessmentId=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 { status, createdAt, lastChangedAt } = response.data;
  // ...
}

Python (Requests)

import requests

def get_v3_api_assessment_poll():
    url = 'https://rest.eus.canaryspeech.com/v3/api/assessment/poll'
    
    headers = {
        'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
        'Content-Type': 'application/json'
    }
    
    response = requests.get(
        url,
        params={
            'assessmentId': 'abc123'
        },
        headers=headers,
    )
    
    if response.status_code !== 200:
        raise Exception(response.status_code)
    
    response_obj = response.json()
    status = response_obj['status']
    created_at = response_obj['createdAt']
    last_changed_at = response_obj['lastChangedAt']
    
    # ...

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 getV3ApiAssessmentPoll() {
    URI uri = new URI("https://rest.eus.canaryspeech.com/v3/api/assessment/poll?assessmentId=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());
    String status = (String) responseBody.get("status");
    String createdAt = (String) responseBody.get("createdAt");
    String lastChangedAt = (String) responseBody.get("lastChangedAt");
    
    // ...
  }

}

Kotlin

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

suspend fun getV3ApiAssessmentPoll() = runCatching {
    val url = URL.create("https://rest.eus.canaryspeech.com/v3/api/assessment/poll?assessmentId=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 status = responseBody.get("status") as String
        val createdAt = responseBody.get("createdAt") as String
        val lastChangedAt = responseBody.get("lastChangedAt") as String
        
        // ...
    }
}

Swift (URLSession)

import UIKit

func getV3ApiAssessmentPoll() -> void {
    
    let url = URL("https://rest.eus.canaryspeech.com/v3/api/assessment/poll?assessmentId=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(GetV3ApiAssessmentPollResponse.self, data)
            // ...
        } catch {
            print(error)
        }
    }
    }
}

struct GetV3ApiAssessmentPollResponse: Decodable {
    let status: String
    let createdAt: String
    let lastChangedAt: 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 getV3ApiAssessmentPoll()
    {
        var url = "https://rest.eus.canaryspeech.com/v3/api/assessment/poll?assessmentId=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 status = (String)responseJson["status"];
        var createdAt = (String)responseJson["createdAt"];
        var lastChangedAt = (String)responseJson["lastChangedAt"];
        // ...
    }
}

Dart/Flutter

import 'dart:convert';

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

Future<void> function getV3ApiAssessmentPoll() async {
  final queryParams = { 'assessmentId': 'abc123' };
  
  final uri = Uri.https('rest.eus.canaryspeech.com', 'v3/api/assessment/poll', 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 status = response['status'] as String;
    final createdAt = response['createdAt'] as String;
    final lastChangedAt = response['lastChangedAt'] as String;
    
    // ...
  } catch (e) {
    print(e);
  }
}

Models

status

The status of the assessment. Lies in one of four states: created, processing, completed, and failed.

Enum	Type	Description
"created"	string	The assessment is ongoing and waiting for the user to upload recordings (if applicable see here) and end the assessment (see here).
"processing"	string	The assessment has been ended and is being analyzed by Canary Speech.
"completed"	string	The assessment completed successfully, call the list-scores endpoint to retrieve scores.
"failed"	string	The assessment has failed. Call the list-scores endpoint with the errorsIncluded flag to get more information about the failures.