API Documentation

Download Documentation as a PDF

Introduction

Voices.com exposes its data via an Application Programming Interface (API). Developers may use this functionality in order to interact with the Voices.com application.

 

API Endpoint

The API endpoint must be accessed over a secure connection. Ensure that https is used. Note that v4 represents the API version number. In future revisions, this will be a different value. This endpoint represents the most current stable revision, and is the only one to be used.

https://api.voices.com/v4/partners

 

Authentication

For all API calls, a secret key must be passed in the HTTP headers. This key is exclusive to each partner. Please do not share this with anyone. Voices.com will provide you with a key after you have spoken with a Program Account Manager.

If you specify an incorrect key, authentication will fail, and HTTP status 404 Not Found will be returned.

If your key is correct, but we have not enabled your access to the Partner Program, HTTP status 401 Unauthorized will be returned.

Headers

Name Type Description
X-API-KEY string Your unique partner API key

 

Test Mode

All partner accounts begin in test mode. When in test mode, you may retrieve all your available data. Any data intended to be stored in the database will be processed and validated, but not saved. After testing is successful, and you are confident that your software development is complete, you will need to contact your partner account manager. Your manager be able to remove this restriction, and you will be able to proceed live.

If you wish to perform further tests or development, test mode may be manually enabled by adding TEST-MODE to the HTTP headers, and setting it’s value to 1.

Headers

Name Type Description
TEST-MODE integer Enable or disable test mode (0 = off, 1 = on)

If test mode is enabled, all returned data will contain a mode key with a value of test. If test mode is disabled, the value will be live.

{

    "mode": "[live|test]"

}

 

Error Codes

A situation may arise where the API will be unable to fulfill your request. This may be due to an invalid input parameter, a credit limit issue, or various other reasons.

If a problem occurs, an error code and message are returned. When this happens, the API will stop all activity. You will need to address the problem before continuing.

It is recommended that the error code be used when programming with this API. The message may change, but the the error code will not. Each documented action includes a list of possible errors.

Error Response

{

    "error": {

        "code": 100,

        "message": "Program ID must be a number"

    }

}

 

Notice Codes

Like error codes, notices may appear in the returned data. Unlike errors, a notice will not stop the API from processing. You should keep an eye on these notices however, as they may eventually lead to errors.

It is recommended that the notice code be used when programming with this API. The message may change, but the the error code will not. Each documented action includes a list of possible notices.

Notice Response

{

    "notices": [

        {

            "code": 200,

            "message": "Test mode enabled"

        }

    ]

}


 

List all programs

GET /programs

Gets a list of all programs associated with the authenticated partner.

On success, HTTP status code 200 OK is returned, along with all available programs. If no programs are available, an empty array is returned.

Successful Response Format

200 OK

{

    "data": [

        {

            "program_id": "[program id]",

            "name": "[program name]",

            "description": "[program description]",

            "unit_price": "[unit price]",

            "start_date": "[program start date]",

            "end_date": "[program end date]",

            "created": "[created date/time]",

            "updated": "[last updated date/time]"

        }

  ],

  "data_count": 1,

  "mode": "[live|test]"

}

 

List a single program

GET /programs/:program_id

Gets details for the specified program. Only programs associated with the authenticated partner are available.

Input Parameters

Name Type Description
program_id string Program ID

On success, HTTP status code 200 OK is returned, along with all available programs. If no programs are available, an empty array is returned.

Successful Response

200 OK

{

    "data": {

        "program_id": "[program id]",

        "name": "[program name]",

        "description": "[program description]",

        "unit_price": "[unit price]",

        "start_date": "[program start date]",

        "end_date": "[program end date]",

        "created": "[created date/time]",

        "updated": "[last updated date/time]"

    },

    "mode": [live|test]

}

Errors

Error Code HTTP Status Description
100 400 Program ID must be a number
The specified program ID must be a number.
120 403 Program is not associated with your account
The specified program is not associated with your account.

 

List all jobs

GET /programs/:program_id/jobs

Gets a list of all jobs associated with the authenticated partner.

Input Parameters

Name Type Description
program_id string Program ID

On success, HTTP status code 200 OK is returned, along with all available jobs. If no jobs are available, an empty array is returned.

If an invalid program_id is specified, HTTP status code 403 Forbidden will be returned.

Successful Response

200 OK

{

    "data": [

        {

            "job_id": "[job id]",

            "program_id": "[program id]",

            "talent_id": "[talent id]",

            "sample_script": "[script]",

            "script_file": [

                "name": "[script file name]",

                "url": "[script file url]"

             ],

            "job_description": "[job description]"

            "job_status": "[status = new, assigned, edit or approved]",

            "edit_count": "[total number of requested edits]",

            "created": "[created date/time]",

            "updated": "[last updated date/time]"

         }

    ],

    "data_count": 1,

    "mode": [live|test]

}

 

List a single job

GET /jobs/:job_id

Gets details for the specified job. Only jobs associated with the authenticated partner are available.

Input Parameters

Name Type Description
job_id string Job ID

Successful Response

200 OK

{

    "data": {

        "job_id": "[job id]",

        "program_id": "[program id]",

        "talent_id": "[talent id]",

        "sample_script": "[script]",

        "script_file": [

            "name": "[script file name]",

            "url": "[script file url]"

         ],

        "job_description": "[job description]"

        "job_status": "[status = new, assigned, edit or approved]",

        "edit_count": "[total number of requested edits]",

        "created": "[created date/time]",

        "updated": "[last updated date/time]"

      },

    "mode": [live|test]

}

Errors

Error Code HTTP Status Description
101 400 Job ID must be a number
The specified job ID must be a number.
121 403 Job is not associated with your account
The specified job is not associated with your account.

 

List all talents

GET /programs/:program_id/talents

Gets a list of all talents associated with the specified program. If no talents are available, an empty array is returned.

Input Parameters

Name Type Description
program_id string Program ID

If an invalid program_id is specified, HTTP status code 400 Bad Request will be returned.

Successful Response

200 OK

{

    "data": [

        "talent_id": "[talent id]",

        "talent_url": "[talent url]",

        "first_name": "[first name]",

        "last_name": "[last name]",

        "gender": "[gender]",

        "languages": [

            "[language 1]",

            "[language 2]",

            ...

        ],

        "feedback": "[feedback]",

        "avatar": "[avatar url]",

        "demo": [

            "url": [

                "audio_url": "[audio file url]",

                "voices_standard": "[voices standard url]",

                "light_standard": "[light standard url]",

                "light_standard_timer": "[light standard with timer url]",

                "light_standard_complete": "[light standard complete url]",

                "dark_standard": "[dark standard url]",

                "dark_standard_timer": "[dark standard with timer url]",

                "dark_standard_complete": "[dark standard complete url]",

 

            ],

          "tags": [

              "[demo tag 1]",

              "[demo tag 2]",

              ...

          ]

      ]

  ],

  "data_count": 1,

  "mode": [live|test]

}

 

List a single talent

GET /talents/:talent_id

Gets details for the specified talent associated with the specified program.

Input Parameters

Name Type Description
talent_id string Talent ID

Successful Response

200 OK

{

    "data": [

        "talent_id": "[talent id]",

        "talent_url": "[talent url]",

        "first_name": "[first name]",

        "last_name": "[last name]",

        "gender": "[gender]",

        "languages": [

            "[language 1]",

            "[language 2]",

            ...

        ],

        "feedback": "[feedback]",

        "avatar": "[avatar url]",

        "demo": [

            "url": [

                "audio_url": "[audio file url]",

                "voices_standard": "[voices standard url]",

                "light_standard": "[light standard url]",

                "light_standard_timer": "[light standard with timer url]",

                "light_standard_complete": "[light standard complete url]",

                "dark_standard": "[dark standard url]",

                "dark_standard_timer": "[dark standard with timer url]",
                "dark_standard_complete": "[dark standard complete url]",

            ],

          "tags": [

              "[demo tag 1]",

              "[demo tag 2]",

              ...

          ]

      ]

  ],

  "data_count": 1,

  "mode": [live|test]

}

Errors

Error Code HTTP Status Description
102 400 Talent ID must be a number
The specified talent ID must be a number.
122 403 Talent is not associated with your account
The specified job is not associated with any programs on your account.

 

Create a job

POST /jobs

Creates a new job record and associates it with the specified program. The new job record’s ID will be return on successful creation. If you are in test mode, a null will be returned, since no record is actually created.

Input Parameters

Name Type Description
program_id string Program ID
talent_id string Talent ID
script_file file File containing text of script
sample_script string Sample script text
job_description string Additional information related to the job

Input Example

{

    "program_id": "program id",

    "talent_id": "talent id",

    "script_file": "script file"

    "sample_script": "sample script text"

    "job_description": "job description text"

}

Successful Response

201 Created

 

{

    "data": {

        "job_id": 123456

    },

    "mode": [live|test]

}

In some cases, an array of notices will be appear in the response. See the table below for possible notices. If no notices are available, this will be omitted.

Failed Response

400 Bad Request

 

{

    "error": {

        "code": 143,

        "message": "Job could not be created"

    },

    "mode": [live|test]

}

Errors

Error Code HTTP Status Description
100 400 Program ID must be a number
The specified program ID must be a number.
102 400 Talent ID must be a number
The specified talent ID must be a number.
104 400 Script file or sample script must be provided
A valid script file or sample script must be included.
105 400 Invalid file type (accepted types: {list of types})
The supplied script file must be one of the indicated formats.
106 400 Job description required
A job description is required.
120 403 Program is not associated with your account
The specified program is not associated with your account.
122 403 Talent not associated with any programs on your account
The specified talent is not associated with any of the programs on your account.
123 400 Program is not active
The specified program is not active.
140 400 Credit limit reached or exceeded
Your account's credit limit has been reached or exceeded.
141 400 Credit limit unavailable
A credit limit for your account has not been set. Contact your program account manager.
142 400 Credit limit could not be determined
An error has occurred on voices.com. This issue could be temporary; retry the request at least once. Contact your program account manager if this persists.
143 400 Job could not be created
An unexpected error has occurred. This issue could be temporary; retry the request at least once. Contact your program account manager if this persists.

Notices

Notice Code Description
240 Credit balance approaching limit
If your account's outstanding credit balance is within your threshold (normally 80-100%), you will receive this warning. Jobs will still be saved until credit limit is reached.

 

Approve a job file

POST /jobs/:job_id/approveFile

Sets the status flag in a partner program’s job record to approved. The updated field is set to current date/time.

Input Parameters

Name Type Description
job_id string Job ID

Successful Response

204 No Content

Errors

Error Code HTTP Status Description
121 403 Job is not associated with your account
The specified job is not associated with your account.
144 400 Job file approval was unsuccessful
Request was unsuccessful, likely due to a validation error.

 

Request an edit for a job file

POST /jobs/:job_id/editFile

 

Sets the status flag in a partner program’s job record to edit. edit_count is incremented by one. When the edit_count field exceeds the program’s specified limit, the partner program manager will receive an e-mail. notes field is updated with partner-supplied notes. updated field is set to current date/time.

Input Parameters

Name Type Description
job_id integer Job ID
edit_notes string Text containing reasons/instructions for edit

Input Example

{

    "edit_notes": "[notes]"

}

Successful Response

204 No Content

Errors

Error Code HTTP Status Description
121 403 Job is not associated with your account
The specified job is not associated with your account.
146 400 Job is approved, no edits allowed
Additional edit requests are not allowed because the job is approved.
147 400 Maximum number of edits reached
Additional edit requests are not allowed because the maximum number of edits has been reached.
103 400 Edit notes required
Notes for the requested edit are required.
145 400 Job file edit request was unsuccessful
Request was unsuccessful, likely due to invalid error.

 


API Overview

Read an overview of the Voices.com API, what it does and how you can use it to build your own apps.

Browse an overview of the API

API Key

Get an API key so you can immediately start developing your app.

Get an API key