GetSubject

GET - /org/subject/:subjectId

Required Permissions:

scope:api

Description

Get a 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...

Path Parameters

Name	Type	Description
subjectId	string	The UUID of the subject

Successful Response

A successful response

Field Name	Type	Description
UUID	uuid	The UUID of this subject.
groupUUIDs	array<string>	The list of parent groups associated with this subject.
name	string	The name of this subject.
alias	string	The alias of this subject.
status	int32	The status code of this subject.
dateCreated	date-time	The ISO-8601 timestamp of when this subject was created.
dateClosed	date-time	The ISO-8601 timestamp of when this subject was closed.
extraData	object	Any additional optional metadata associated with this subject.

Code Example

cURL

curl \
  -X GET "https://rest.eus.canaryspeech.com/v2/org/subject/${SUBJECT_ID}" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

JavaScript (Fetch)

function getV2OrgSubject() {

  const subjectId = 'abc123';
  
  const url = `https://rest.eus.canaryspeech.com/v2/org/subject/${subjectId}`;
  
  const headers = {
    Authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
  };
  
  fetch(url, {
    method: 'GET',
    headers: headers
  }).then((response) => {
    if (!response.ok) throw new Error(response.status);
    return response.json()
  }).then((json) => {
    const { UUID, groupUUIDs, name, alias, status, dateCreated, dateClosed, extraData } = json;
    // ...
  });
}

JavaScript (Node)

const https = require('https');

function getV2OrgSubject() {

  const subjectId = 'abc123';
  
  
  const headers = {
    Authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
  };
  
  const options = {
    hostname: 'rest.eus.canaryspeech.com',
    port: 443,
    path: `/v2/org/subject/${subjectId}`,
    method: 'GET',
    headers: headers
  };
  
  const request = https.request(options, (response) => {
    if (response.statusCode !== 200) throw new Error(response.statusCode);
    
    response.on('data', (d) => {
      const { UUID, groupUUIDs, name, alias, status, dateCreated, dateClosed, extraData } = JSON.parse(d);
      // ...
    });
  });
  
  request.on('error', (err) => {
    throw new Error(err);
  });
  
  request.end();
  
}

JavaScript (Axios)

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

async function getV2OrgSubject() {

  const subjectId = 'abc123';
  
  const url = `https://rest.eus.canaryspeech.com/v2/org/subject/${subjectId}`;
  
  const headers = {
    Authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
  };
  
  const response = await axios.get(url, { headers });
  
  if (response.status !== 200) throw new Error(response.status);
  
  const { UUID, groupUUIDs, name, alias, status, dateCreated, dateClosed, extraData } = response.data;
  
  // ...
}

TypeScript (Node)

import * as https from 'https';

function getV2OrgSubject(): void {

  const subjectId = 'abc123';
  
  
  const headers = {
    Authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
  };
  
  const options = {
    hostname: 'rest.eus.canaryspeech.com',
    port: 443,
    path: `/v2/org/subject/${subjectId}`,
    method: 'GET',
    headers: headers
  };
  
  const request = https.request(options, (response) => {
    if (response.statusCode !== 200) throw new Error(response.statusCode);
    
    response.on('data', (d) => {
      const { UUID, groupUUIDs, name, alias, status, dateCreated, dateClosed, extraData } = 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 getV2OrgSubject(): Promise<void> {

  const subjectId = 'abc123';
  
  const url = `https://rest.eus.canaryspeech.com/v2/org/subject/${subjectId}`;
  
  const headers = {
    Authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
  };
  
  const response = await axios.get(url, { headers });
  
  if (response.status !== 200) throw new Error(response.status);
  
  const { UUID, groupUUIDs, name, alias, status, dateCreated, dateClosed, extraData } = response.data;
  // ...
}

Python (Requests)

import requests

def get_v2_org_subject():
    subject_id = 'abc123'
    
    url = f'https://rest.eus.canaryspeech.com/v2/org/subject/{subject_id}'
    
    headers = {
        'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
    }
    
    response = requests.get(
        url,
        headers=headers,
    )
    
    if response.status_code !== 200:
        raise Exception(response.status_code)
    
    response_obj = response.json()
    UUID = response_obj['UUID']
    group_uUIDs = response_obj['groupUUIDs']
    name = response_obj['name']
    alias = response_obj['alias']
    status = response_obj['status']
    date_created = response_obj['dateCreated']
    date_closed = response_obj['dateClosed']
    extra_data = response_obj['extraData']
    
    # ...

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 getV2OrgSubject() {
    final String subjectId = "abc123"
    
    URI uri = new URI("https://rest.eus.canaryspeech.com/v2/org/subject/" + subjectId);
    
    HttpRequest request = HttpRequest.newBuilder()
      .uri(uri)
      .version(HttpClient.Version.HTTP_2)
      .header("Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c")
      .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 UUID = (String) responseBody.get("UUID");
    List<String> groupUUIDs = (List<String>) responseBody.get("groupUUIDs");
    String name = (String) responseBody.get("name");
    String alias = (String) responseBody.get("alias");
    Integer status = (Integer) responseBody.get("status");
    String dateCreated = (String) responseBody.get("dateCreated");
    String dateClosed = (String) responseBody.get("dateClosed");
    Map<String, Object> extraData = (Map<String, Object>) responseBody.get("extraData");
    
    // ...
  }

}

Kotlin

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

suspend fun getV2OrgSubject() = runCatching {
    val subjectId = "abc123"
    
    val url = URL.create("https://rest.eus.canaryspeech.com/v2/org/subject/"${subjectId}"")
    with(url.openConnection() as HttpsURLConnection) {
        requestMethod = "GET"
        instanceFollowRedirects = true
        
        setRequestProperty("Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c")
        
        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 UUID = responseBody.get("UUID") as String
        val groupUUIDs = responseBody.get("groupUUIDs") as Array<String>
        val name = responseBody.get("name") as String
        val alias = responseBody.get("alias") as String
        val status = responseBody.get("status") as Int
        val dateCreated = responseBody.get("dateCreated") as String
        val dateClosed = responseBody.get("dateClosed") as String
        val extraData = responseBody.get("extraData") as Map<String, Any?>
        
        // ...
    }
}

Swift (URLSession)

import UIKit

func getV2OrgSubject() -> void {
    
    let subjectId = "abc123"
    
    let url = URL("https://rest.eus.canaryspeech.com/v2/org/subject/\(subjectId)")
    
    let headers: [String: String] = [
        "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
    ]
    
    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(GetV2OrgSubjectResponse.self, data)
            // ...
        } catch {
            print(error)
        }
    }
    }
}

struct GetV2OrgSubjectResponse: Decodable {
    let UUID: String
    let groupUUIDs: [String]
    let name: String
    let alias: String?
    let status: Int32
    let dateCreated: String
    let dateClosed: String?
    let extraData: [String: Any]
}

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 getV2OrgSubject()
    {
        var subjectId = "abc123";
        
        var url = "https://rest.eus.canaryspeech.com/v2/org/subject/${subjectId}\"";
        
        var request = new HttpRequestMessage(HttpMethod.Get, url);
        request.Headers.Add("Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c");
        
        var response = await client.SendAsync(request);
        response.EnsureSuccessStatusCode();
        
        var responseBody = await response.Content.ReadAsStringAsync();
        var responseJson = JsonConvert.DeserializeObject<Dictionary<string, dynamic>>(responseBody);
        var UUID = (String)responseJson["UUID"];
        var groupUUIDs = (List<String>)responseJson["groupUUIDs"];
        var name = (String)responseJson["name"];
        var alias = (String)responseJson["alias"];
        var status = (int)responseJson["status"];
        var dateCreated = (String)responseJson["dateCreated"];
        var dateClosed = (String)responseJson["dateClosed"];
        var extraData = (Dictionary<String, dynamic>)responseJson["extraData"];
        // ...
    }
}

Dart/Flutter

import 'dart:convert';

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

Future<void> function getV2OrgSubject() async {
  final subjectId = 'abc123';
  
  final uri = Uri.https('rest.eus.canaryspeech.com', 'v2/org/subject/$subjectId', queryParams);
  
  final headers = {
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
  };
  
  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 UUID = response['UUID'] as String;
    final groupUUIDs = response['groupUUIDs'] as List<String>;
    final name = response['name'] as String;
    final alias = response['alias'] as String?;
    final status = response['status'] as int;
    final dateCreated = response['dateCreated'] as String;
    final dateClosed = response['dateClosed'] as String?;
    final extraData = response['extraData'] as Map<String, dynamic>?;
    
    // ...
  } catch (e) {
    print(e);
  }
}