Getting Started with Voxjar’s API




Visit for current API documentation

Table of Contents


This guide is intended to get you from 0 to uploading calls as quickly as possible.

This is not Voxjar’s API Documentation or intended to be your only API resource. For full Voxjar API Documentation and a web-based query environment go to

About Voxjar’s API

API Tokens

Python Client Library




     -Uploading Call Recordings



About Our API


Voxjar maintains an open GraphQL API along with a Python Client Library for uploading, transcribing, analyzing, and interacting with phone call recordings and call metadata. 

To learn more about GraphQL visit How to GraphQL or

A web interface is available at where you can test queries and mutations, access our full API documentation, generate curl commands, and generally become familiar with our API.

We also provide a Python Client Library for simplified call recording and metadata uploading.The Python library will be the main focus of this guide due to the simplicity of implementation.

Although the Python library does expose a GraphQL library that you can use for executing Queries and Mutations found in our API documentation this guide will only briefly touch on it here.

API Tokens


Voxjar’s API authenticates with a system-generated API Token as a JWT.

Long-lived tokens (1 year) are generated in Voxjar’s web app on the settings/developers page. You cannot recover or disable a lost API token. Each new token that you generate will have a new expiration date.

(Tokens should be kept secret and safe. Ain’t nobody got time for a data breach.)

If you can’t view the developers page you might not have permission to do so. Talk with your administrator or reach out to Voxjar’s support team for help.

Generating a Long-Lived API Token





Short-lived tokens (generally a few hours) can be generated in Voxjar’s API Playground with the login mutation for testing purposes.
These tokens should NOT be used in production.

Generating a Short-Lived API Token for Testing



With your Token generated you can now authenticate API requests.

Python Client Library


Voxjar provides a Python library to simplify uploading calls and metadata. Documentation can be found here. The rest of this guide will walk you through implementation in detail.



$ pip3 install voxjar




The Client() class needs a URL and a Token. We suggest using a JSON keyfile in production as seen in our docs.
For testing, you can hardcode the values as seen in the example below.

You can test against our dev server before moving to production with the URLs below.


Use your system generated API token

import voxjar

client = voxjar.Client(url="", token="MY_API_TOKEN")



Next, you’ll need to create a metadata dictionary. This dictionary should be dynamically populated for each individual call recording.

The following example shows a completed metadata object with placeholder values. Many fields are not required, but we suggest populating as many fields as you can to create a rich dataset.

Required Fields

identifier string unique call id

type dictionary e.g sales, support, brand, etc.

identifierstringunique id for call type

namestringhuman readable call type name

timestamp datetime when the call took place

direction enumcall direction OUTGOING/INCOMING

agents list of dictionaries

identifierstring unique agent id

namestringthe agent’s name

customers list of dictionaries

identifierstring unique customer id

namestringcustomer’s name

Optional Fields

agents list of dictionaries

phoneNumberstringagent’s phone number/extension

metadata dictionaryset your own key value pairs to associate with this agent

customers list of dictionaries

phoneNumberstringcustomer’s phone number

metadata dictionaryset your own key value pairs to associate with this customer

disposition dictionary e.g. update billing, dropped call, deal won, etc.

identifierstringunique id for disposition

namestringhuman readable disposition name

tags list

metadata dictionary set your own key value pairs to associate with this call

Common Mistakes:

  • Copying the example code from the docs without replacing the Placeholder values. When every comes across as “typeName” you’ve made the same mistake.
  • Again, forgetting to replace the Placeholder value for timestamp. Be sure to use the datetime that the call took place.
  • Using non-unique identifiers, especially for agents. This usually comes in the form of using phone extensions or phone numbers instead of an employee id or email address.
  • Locking yourself into the pre-defined metadata fields. We added the custommetadata fields so you can add any additional data to your calls, agents, or customers for a richer experience. All metadata fields become filters in the Voxjar webapp.
import datetime
import voxjar

metadata = {
    'identifier': 'callIdentifier',
    'type': {
        'identifier': 'typeIdentifier',
        'name': 'typeName',
    'direction': 'OUTGOING',  # or INCOMING
    'agents': [{
        'identifier': 'agentIdentifier',
        'name': 'Agent Name',
# optional 'phoneNumber': 1234567890, # optional 'metadata': { 'someCustomField': 'someCustomValue', }, }], 'customers': [{ 'identifier': 'customerIdentifier', 'name': 'Customer Name',
# optional 'phoneNumber': 9876543210, # optional 'metadata': { 'someCustomField': 'someCustomValue', }, }], # optional 'disposition': { 'identifier': 'dispositionIdentifier', 'name': 'dispositionName', }, # optional 'tags': ['tag1', 'tag2'], # optional 'metadata': { 'someCustomField': 'someCustomValue', }, }



There two ways to upload call recordings and metadata with the library. Both require that the call recording as well as a complete metadata dictionary be uploaded together.

The first method is used when you have the recording files stored locally and the other is when you pull the recordings from a URL.

Local files

import voxjar

client = voxjar.Client()

with open('test.wav', 'rb') as f:
    client.push(metadata, f)

File like objects (URL)

import voxjar

client = voxjar.Client()

r = requests.get('', stream=True)
with client.push_request(metadata) as push_request:
    for chunk in r.iter_content(chunk_size=1024):



It is also possible to execute GraphQL queries and mutations with Voxjar’s Python library. You can explore our API and test your queries/mutations in our playground first and then copy them into your script. 

To learn about GraphQL in detail visit How to GraphQL or

Check out the syntax below, then go build something cool!

import voxjar

client = voxjar.Client()

def get_hours(**kwargs):
    document = """{
    response = client.execute(document, variable_values=kwargs)
    return response.get('aggregate', {}).get('sum')