Canary Speech

Overview

The Canary Speech API is the primary means with which to integrate with Canary Speech services.

Obtain Credentials

When you receive access to the Canary Speech API, you will be provided with an API key. You will need this key to authenticate with the API and gain access tokens. Note: Canary Speech does not store your key in its unencrypted form, and cannot recover it if it is lost, forgotten, or compromised.

The key will resemble the following:

1A2B3C:YWJjZGVmZ2hhYmNkZWZnaGFiY2RlZmdoYWJjZGVmZ2hhYmNk

In addition to the API Key, you you will be provided with the following:

  • • Group ID
  • The target group which you use to create new subjects.
  • • Survey ID
  • The target survey which you use to create assessments and upload recordings.
  • • Survey Response Metadata
  • The configuration which maps questions to question IDs, which you use to create responses.

Authenticate with the API

The Canary Speech API uses the OAuth 2.0 approach to authentication. Using your provided API key, you can call the oauth/request-tokens endpoint to generate an OAuth access token.

cURL
curl -X POST oauth/request-tokens \
  -H "Csc-Api-Key: ***" \
  -H "Content-Type: application/json"

In addition to the access token, you will also be provided with a refresh token that can be used to generate a new access token without providing the API key via a call to oauth/refresh-tokens.

cURL
curl -X POST oauth/refresh-tokens \
  -H "X-Refresh-Token: ***" \
  -H "Content-Type: application/json"

The expiration of the access token can be obtained by decoding the token as a JWT. The expiration is found in the exp field of the payload, formatted as a Unix timestamp i.e. the number of seconds since Jan. 1, 1970. The expiration of the refresh token is not given and should be used within a few days of the access token expiring.

Typical Workflow

Once you have obtained your credentials and successfully authenticated with the API, you are ready to begin creating subjects and conducting assessments. A typical workflow for this process will resemble the following:

  • • Step 1: (Optional) Create a subject
  • Subjects represent the individual being evaluated. A subject is required in order to conduct assessments. You will need to maintain a record of subject IDs if you wish to submit multiple assessments for a given subject. If you need to create a new subject, using the provided group ID, perform a call to PUT /org/group/<your-group-ID>/put-subject, including the necessary details. This will return a subject ID associated with the created subject.
  • See more: Creating a Subject
  • • Step 2: Upload an assessment
  • In order to upload assessment data use POST - /org/subjects/<your-subject-ID>/post-full-assessment This will return an assessment ID associated with the created assessment which you will use in later steps.
  • See more: Uploading a Full Assessment
  • • Step 3: Upload a voice recording
  • Uploading recordings can be accomplished by calling POST - /media/generate-upload-url/<your-filename> to retrieve a presigned upload URL, passing all required metadata, and then performing a `PUT` request on the returned URL with the binary data of the audio file passed as the body. Note: the filename passed to POST - /media/generate-upload-url/<your-filename> must match the filename given to the audio file’s associated response.
  • See more: Generating an Upload URL
  • • Step 4: Completing an assessment
  • Marking an assessment as complete will trigger the scoring mechanisms to be performed on that assessment. This is done by calling POST - /org/assessment/<your-assessment-ID>/complete. If the assessment has non-verbal scores, they will be calculated and returned from this endpoint. Processed verbal scores will be available shortly after calling this endpoint, with the delay depending on the length of the assessment and number of recordings but typically within 10-15 seconds.
  • See more: Completing an Assessment
  • • Step 5: Polling for Vocal Scores
  • Canary Speech is working on an asynchronous event API which can be used to be notified when the scores are available. In the meantime, you can periodicallly poll the scores API to detect when the scores have been published by calling GET - /org/assessment/<your-assessment-ID>/get-scores. The recommendation is to poll no more often than once every two seconds.
  • See more: Getting Scores

Further Reading