The CastingWords store API v4 is a simplified API to create orders and obtain the resulting transcripts.
The API is RESTish. The goal is not to follow REST's practices closely, but rather to make an easy API to get up to speed with using a dynamic language or curl. It accepts data as URL encoded key value pairs. An HTTP body of type JSON in a POST request and with content type application/json is also accepted.
Authentication is via a secret key posted in the HTTPS URL or as JSON in the POST Body (preferred). You may retrieve your secret key from you account at https://castingwords.com/customer/info
All URLS are in the format of
https://castingwords.com/store/API4/
Currently supported: application/json
Although all calls return a success message in the data, failures are always indicated via an HTTP code, 401 not authorized for instance. A message will accompany the error. An overview of HTTP status codes is available at http://en.wikipedia.org/wiki/HTTP_status
#ID indicates a CastingWords id. The '#' is not literal. All calls require an API Key parameter, which has been omitted for clarity (eg: &api_key=#APIKEY)
Returns the order and audiofile ids
POST (curl -X POST)
https://castingwords.com/store/API4/order_url?api_key=#APIKEY&url=http://myaudio.com/audio.mp3&sku=TRANS14&sku=TSTMP1¬es=my+comments+on+this+audio&name=Nathan&name=Rachel&name=Jen&name=Mike
See your prepay balance.
GET https://castingwords.com/store/API4/prepay_balance
See details on an audiofile, including its current state
GET https://castingwords.com/store/API4/audiofile/#AUDIOFILEID
Returns the data of the transcript in the doc type requested by the extention.
GET
https://castingwords.com/store/API4/audiofile/#AUDIOFILEID/transcript.#ext
DEPRECATED:
GET or POST
https://castingwords.com/store/API4/transcript/#AUDIOFILEID.#ext
POST https://castingwords.com/store/API4/audiofile/#AUDIOFILEID/upgrade?sku=#SKU
POST https://castingwords.com/store/API4/audiofile/#AUDIOFILEID/refund
POST https://castingwords.com/store/API4/invoice/#INVOICEID
Set a URL for us to ping on transcript complete, a refund is issued, or a duplicate is detected
GET or POST https://castingwords.com/store/API4/webhook?webhook=#URL_ENCODED_HTTP(S)_ENDPOINT
Description:
Creates a new order for a audio located at a URL.
Accepts a URL and many SKUs, with all SKUs being applied to every URL.
Fetches data on all URLs, response time varies with the number of URLs and the speed of the host;
Parameters:
api_key - Required for authentication
url - Url(s) of audio/video to transcribe. Preferably points to an mp3. ;
sku - one or more skus to order.
TRANS14 = Budget Transcription with a target of 14 days.
TRANS2 = 1 Day Expert Transcription
TRANS6 = 6 Day Transcription
TRANS7 = 7 Day Transcription
EMSR02 = Advanced Machine Transcription
DIFFQ2 = Difficult Audio
TSTMP1 = Timestamps
CAPTION1 = Captions/Subtitles
test - Creates a test only order that will not be transcribed.
notes - text feild with comments for the transcribers about this audio
name - Repeatable parameter with names of the speakers in the audio.
names - a synonym for name
Returns:
audiofiles - an array of ids id for the files
order - an id for the order
message - success/failure human readable
hold - OPTIONAL. Present ONLY when the order was accepted but placed on hold
rather than started. Absent on every normal order - do not expect the
key. Currently the only value is 'billing', meaning the account has a
past-due balance. The order and audiofiles are real and keep their ids,
but no transcription begins and no TRANSCRIPT_COMPLETE will follow until
the hold is released, at which point the order resumes automatically.
An ORDER_ON_HOLD webhook is sent at the same time. NOTE: a held order
still returns HTTP 200, so check for this key rather than the status code.
cURL Example
curl --data \
'{"api_key":"MYAPIKEY", \
"url":"http://mydomain.com/media/test.mp3", \
"test": "1",
"names": ["Jane Doe"]
}' \
https://castingwords.com/store/API4/order_url \
-H "Content-Type: application/json"
Description:
Returns the current prepay_balance in USD for this account as a json structure.
Parameters:
api_key - Required for authentication.
Returns:
balance - The current prepay balance
cURL Example
curl https://castingwords.com/store/API4/prepay_balance?api_key=MYAPIKEY \ -H "Content-Type: application/json"
Description:
Returns details on given audiofile_id
URL Parameters:
audiofile_id
Parameters: api_key - Required for authentication.
Returns: audiofile - a hash of properties statename - A string describing the current state of a file names - A pipe delimited list of speaker names notes - Notes to the transcriber about this file. originallink - The link submitted for transcription title - Title of the transcript duration - Length in minute of the audio id - Audiofile ID description - A description of the audio quality_stars - Quality ranked on a 5 star system
States Audio Processing Awaiting Edit Awaiting Final Approval Billing Processing Checking Audio Quality Delivered Editing to Word Count Error On Hold Order Cancelled Order Chargeable Order Processing Out for edit Pre-Processing Processing Refunded Technical Difficulty Temporary Error Transcribing
cURL Example
curl https://castingwords.com/store/API4/audiofile/101?api_key=MYAPIKEY \ -H "Content-Type: application/json"
Description:
Returns the transcript for a given audiofile_id
URL Parameters:
audiofile_id -
extension - (optional) defaults to .txt
.txt
.doc
.rtf
.html
.srt
.docx
.tstxt
.vtt
Parameters:
api_key - Required for authentication. test - Returns a fake transcription for testing purposes.
Returns:
The text of the transcript in the requested mime types
cURL Example
curl --data '{"api_key":"MYAPIKEY", "test": "1"}'\
https://castingwords.com/store/API4/audiofile/101/transcript.txt \
-H "Content-Type: application/json"
<Deprecated Versions>
Also available from /transcript/#audiofileid.#ext, and via POST
Description:
Orders an upgrade order item for this audiofile
URL Parameters:
audiofile_id -
Parameters:
sku - Repeatable. Valid values:
DIFFQ2 - Difficult Audio Upgrade. Difficult audio SKU on invoice may be different.
TSTMP1 - Timestamps.
CAPTION1 - Subtitles/Captions.
EDIT01 - Extra Editing.
UPGRD1 - Upgrade TRANS14 to TRANS6
UPGRD2 - Upgrade TRANS14 to TRANS2
UPGRD3 - Upgrade TRANS6 to TRANS2
api_key - Required for authentication.
test - Returns a fake success for testing purposes. Only for use with audiofile 100 and 101.
Returns:
Success message.
cURL Example
curl --data '{"api_key":"MYAPIKEY", "test": "1", "sku": "TSTMP1"}'\
https://castingwords.com/store/API4/101/upgrade \
-H "Content-Type: application/json"
Description:
Refunds an audiofile, ordered with PREPAY or on an INVOICE. This only works when no transcription work has been done on a file. Potentially valid states are 'Pre-Processing', 'Audio Processing', and 'Error' .
URL Parameters:
audiofile_id -
Parameters:
api_key - Required for authentication. test - Returns a fake approval for testing purposes. Only for use with audiofile 100 and 101.
Returns:
Success message.
cURL Example
curl --data '{"api_key":"MYAPIKEY", "test": "1"}'\
https://castingwords.com/store/API4/101/refund \
-H "Content-Type: application/json"
Description:
Returns data on an invoice
URL Parameters:
invoice_id - the id of the invoice in question
Parameters:
api_key - Required for authentication.
Returns:
id - The ID
purchase_order - ID of the purchase order if any
createtime - time of creation
paidtime - time that payment was recorded
total - total price of invoiced items
items - A list of items consisting of:
id - Item ID
sku - SKU of the line item
quantity - Number ordered
price - Price per quantity
audiofile - ID of associated audiofile
total - price * quantity
state - PAID (createtime and paidtime should be set)
SUBMITTED - (createtime should be set, but paidtime has not occurred yet.) Waiting for payment
OPEN - Invoices that are complete - but not yet sent for payment.
CREATED - Invoices that do not yet have all items added.
cURL Example
curl https://castingwords.com/store/API4/webhook?api_key=MYAPIKEY \ -H "Content-Type: application/json"
Description:
Returns the webhook for this account
Parameters:
api_key - Required for authentication.
Returns:
The registered webhook url for this account.
cURL Example
curl https://castingwords.com/store/API4/webhook?api_key=MYAPIKEY \ -H "Content-Type: application/json"
Description:
Sets the webhook url for this account
URL Parameters:
webhook - the new url to call on webhook triggers
Parameters:
api_key - Required for authentication.
Returns:
The current webhook url
cURL Example
curl --data '{"api_key":"MYAPIKEY", "webhook":"http://mydomain.com/webhook"}'\
https://castingwords.com/store/API4/webhook \
-H "Content-Type: application/json"
Webhooks are our async notification system. We do a 1 time HTTP POST to a url that you specify when an event occurs. The payload is application/x-www-form-urlencoded. Currently we support these events:
Common Parameters:
webhook_version: Incremented as we add Hooks.
- TRANSCRIPT_COMPLETE which is called after we've completed transcribing a file for you.
Parameters:
audiofile - Used to retrieve your transcript order - The order this file was part of event - 'TRANSCRIPT_COMPLETE' originallink - A url with original location of audio. May not resolve.- DUPLICATE_FILE called when we detect that a file has been ordered before
Parameters:
audiofile - ID of the file in question order - The order this transaction was against. event - 'DUPLICATE_FILE' original_audiofile - the previously transcribed file this file is a duplicate of.- REFUND_ISSUED called after we've refunded money to a Castingwords Prepay Balance
Parameters:
amount - amount of refund audiofile - ID. Present on some refunds - most refunds are against entire orders. order - The order this transaction was against. event - 'REFUND_ISSUED' original_transaction - Old Transaction ID transaction - This Transaction ID- CC_AUTH_FAILURE is called after your CC's authorization has failed. This normally indicates a multi hour delay before we run the card again. Calling your CC company, changing your billing card, or just waiting for us to try again are all valid options.
Parameters:
order - The order this auth was for. event - 'CC_AUTH_FAILURE'- DIFFICULT_AUDIO called after some instances when we've found a file to be difficult
Parameters:
audiofile - ID. The file with the difficult audio. order - The order for this file. event - 'DIFFICULT_AUDIO'- ORDER_ON_HOLD called when an order is accepted but held instead of started.
The order and its audiofiles are real and keep their ids, but no transcription begins and no TRANSCRIPT_COMPLETE will follow until the hold is released, at which point the order resumes automatically with no action needed from you. Note that the ordering API call itself still returns HTTP 200 with a 'hold' key in the body, so this event is the reliable async signal that work is not proceeding.
Parameters:
order - The order that was placed on hold. audiofiles - Comma-separated ids of the files in the order. hold - Why it is held. Currently always 'billing', meaning the account has a past-due balance. Treat any unrecognised value as "held, contact us". skus - Comma-separated skus that were ordered. event - 'ORDER_ON_HOLD'Example
http://example.com/ ?audiofile=101 &order=TeSt &event=TRANSCRIPT_COMPLETE &originallink=https://castingwords.com/uploads/1294130176_hand_uploaded_file.mp3
Description:
Requests a test webhook call of a particular type.
URL Parameters:
type - One of the types of webhooks: TRANSCRIPT_COMPLETE DIFFICULT_AUDIO
REFUND_ISSUED or ORDER_ON_HOLD
Parameters:
api_key - Required for authentication.
Returns:
The current webhook url
cURL Example
curl --data '{"api_key":"MYAPIKEY"}'\
https://castingwords.com/store/API4/webhook/test/TRANSCRIPT_COMPLETE \
-H "Content-Type: application/json"