GetSubject

GET - /v3/api/subject

Required Permissions:

scope:api

Description

Fetches metadata associated with a specified subject.

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
id	string	The ID of the subject to query.

Successful Response

A successful response

Field Name	Type	Description
id	uuid	The ID of the subject.
name	string	The name of the subject.
subjectGroupIds	array<string>	A list of groups that this subject belongs to, if any.
identity	object	The identity object for the subject.
dateCreated	date-time	The ISO-8601 timestamp of when this subject was added.
dateRetired	date-time	The ISO-8601 timestamp of when this subject was retired.

Code Example

cURL

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

JavaScript (Fetch)

function getV3ApiSubject() {

  const url = 'https://rest.eus.canaryspeech.com/v3/api/subject?id=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 { id, name, subjectGroupIds, identity, dateCreated, dateRetired } = json;
    // ...
  });
}

JavaScript (Node)

const https = require('https');

function getV3ApiSubject() {

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

JavaScript (Axios)

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

async function getV3ApiSubject() {

  const url = 'https://rest.eus.canaryspeech.com/v3/api/subject?id=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 { id, name, subjectGroupIds, identity, dateCreated, dateRetired } = response.data;
  
  // ...
}

TypeScript (Node)

import * as https from 'https';

function getV3ApiSubject(): 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/subject',
    method: 'GET',
    qs: { id: 'abc123' },
    headers: headers
  };
  
  const request = https.request(options, (response) => {
    if (response.statusCode !== 200) throw new Error(response.statusCode);
    
    response.on('data', (d) => {
      const { id, name, subjectGroupIds, identity, dateCreated, dateRetired } = 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 getV3ApiSubject(): Promise<void> {

  const url = 'https://rest.eus.canaryspeech.com/v3/api/subject?id=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 { id, name, subjectGroupIds, identity, dateCreated, dateRetired } = response.data;
  // ...
}

Python (Requests)

import requests

def get_v3_api_subject():
    url = 'https://rest.eus.canaryspeech.com/v3/api/subject'
    
    headers = {
        'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
        'Content-Type': 'application/json'
    }
    
    response = requests.get(
        url,
        params={
            'id': 'abc123'
        },
        headers=headers,
    )
    
    if response.status_code !== 200:
        raise Exception(response.status_code)
    
    response_obj = response.json()
    id = response_obj['id']
    name = response_obj['name']
    subject_group_ids = response_obj['subjectGroupIds']
    identity = response_obj['identity']
    date_created = response_obj['dateCreated']
    date_retired = response_obj['dateRetired']
    
    # ...

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 getV3ApiSubject() {
    URI uri = new URI("https://rest.eus.canaryspeech.com/v3/api/subject?id=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 id = (String) responseBody.get("id");
    String name = (String) responseBody.get("name");
    List<String> subjectGroupIds = (List<String>) responseBody.get("subjectGroupIds");
    Map<String, Object> identity = (Map<String, Object>) responseBody.get("identity");
    String dateCreated = (String) responseBody.get("dateCreated");
    String dateRetired = (String) responseBody.get("dateRetired");
    
    // ...
  }

}

Kotlin

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

suspend fun getV3ApiSubject() = runCatching {
    val url = URL.create("https://rest.eus.canaryspeech.com/v3/api/subject?id=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 id = responseBody.get("id") as String
        val name = responseBody.get("name") as String
        val subjectGroupIds = responseBody.get("subjectGroupIds") as Array<String>
        val identity = responseBody.get("identity") as Map<String, Any?>
        val dateCreated = responseBody.get("dateCreated") as String
        val dateRetired = responseBody.get("dateRetired") as String
        
        // ...
    }
}

Swift (URLSession)

import UIKit

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

struct GetV3ApiSubjectResponse: Decodable {
    let id: String
    let name: String
    let subjectGroupIds: [String?]
    let identity: [String: Any]
    let dateCreated: String
    let dateRetired: 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 getV3ApiSubject()
    {
        var url = "https://rest.eus.canaryspeech.com/v3/api/subject?id=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 id = (String)responseJson["id"];
        var name = (String)responseJson["name"];
        var subjectGroupIds = (List<String>)responseJson["subjectGroupIds"];
        var identity = (Dictionary<String, dynamic>)responseJson["identity"];
        var dateCreated = (String)responseJson["dateCreated"];
        var dateRetired = (String)responseJson["dateRetired"];
        // ...
    }
}

Dart/Flutter

import 'dart:convert';

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

Future<void> function getV3ApiSubject() async {
  final queryParams = { 'id': 'abc123' };
  
  final uri = Uri.https('rest.eus.canaryspeech.com', 'v3/api/subject', 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 id = response['id'] as String;
    final name = response['name'] as String;
    final subjectGroupIds = response['subjectGroupIds'] as List<String>?;
    final identity = response['identity'] as Map<String, dynamic>?;
    final dateCreated = response['dateCreated'] as String;
    final dateRetired = response['dateRetired'] as String?;
    
    // ...
  } catch (e) {
    print(e);
  }
}

Models

identity

The identity object for the subject.

Name	Type	Description
firstName	string	The first name of the subject.
middleName	string	The middle name of the subject.
lastName	string	The last name of the subject.
prefix	string	A prefix for this subject. (e.g. Mr., Mrs., etc.)
suffix	string	A suffix for this subject. (e.g. Sr., Jr., etc.)
alias	string	An alternate identifier for this subject.
dateOfBirth	string	The date of birth for this subject.
contact	object

identity.contact

Name	Type	Description
email	string	The email of this subject.
phoneNumber	string	The phone number of this subject.