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]", "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.