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:

  • • Project ID
  • The target project which you use to create new subjects.
  • • Survey Code
  • 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 /v3/auth/tokens/get endpoint to generate an OAuth access token.

There are three public hostnames for the API:

  • • rest.eus.canaryspeech.com (East US)
  • • rest.ne.canaryspeech.com (North Europe)
  • • rest.jpe.canaryspeech.com (Japan East)

The examples below use the East US hostname, but customer projects are configured in a specific region for privacy purposes. Please ensure the correct hostname is used for the given project. If you aren't sure which hostname to use, please contact your account representative or support.

cURL
curl -X POST https://rest.eus.canaryspeech.com/v3/auth/tokens/get \
  -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 /v3/auth/tokens/refresh.

cURL
curl -X POST https://rest.eus.canaryspeech.com/v3/auth/tokens/refresh \
  -H "Csc-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: Create a subject
  • A subject is needed 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 make a call to POST /v3/api/create-subject. This will return a subject ID associated with the created subject.
  • See more: Creating a Subject
  • • Step 2: Start an assessment
  • Beginning an assessment will start the process of vocal analysis and provide you with the signed URLs to upload the assessment's voice files. To do this, call POST - /v3/api/assessment/begin with the code of the survey with which you wish to create an assessment. The response body will include a map of vocal response IDs in the survey as well as corresponding presigned upload URLs to upload the vocal data.
  • See more: Starting an Assessment
  • • Step 3: Upload a voice recording
  • Recording uploads are done by making a presigned call to PUT - /v3/api/upload-recording-signed using one of the presigned URLs retrieved from the previous step, with the binary data of the audio file passed as the body.
  • See more: Using a presigned URL
  • • Step 4: Ending an assessment
  • Ending an assessment will trigger the scoring mechanisms to be performed on that assessment. This is done by calling POST - /v3/api/assessment/end. If the assessment has non-verbal responses, they are uploaded as part of this call, and any non-verbal scores will be calculated and returned. 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 seconds.
  • See more: Ending an Assessment
  • • Step 5: (Optional) 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 - /api/list-scores. The recommendation is to poll no more often than once every two seconds.
  • See more: Getting Scores

Further Reading