CaptionSync RESTful API

This is a maximum number of results to return. An offset may optionally prepended, e.g. If making calls in pages of 50, the third page of results would have an offset of 100, i.e.

This is comma delimited list of the fields to sort on, e.g.

This is a date in the ISO format of YYYY-MM-DD. Time may be optionally appended as HH:MM:SS. This time is to be interpreted as PT.
One of =, >=, <=, <, >, or <> must be prepended followed by a space.

This is the filename of the media submitted or downloaded.

The values of Y or N specify if the search should be constrained to just originals or just redos.
If not present both results will be returned.

This is a comma delimited list of the status to filter on, e.g.

This is the batch identifier used with the submission.

This uses a like match parameter on the leading end to deal with Batch: or Redo: prefixes.

This can be one of the valid application types associated with your account: e.g. Captioning, Transcription, or Production. If not present, the submission will inherit the default set via the web UI.

This is the optional batch identifier to be used with the submission. Numerous submissions can be grouped together under a batch identifier for reporting and collecting of results (all results for a particular batch are zipped together for retrieval via SFTP or the web UI).

Keep in mind that the batch identifier needs to be nicely named -- no spaces, punctuation, or high ASCII characters, please.

If present, this will be the description presented to the user in lieu of the basename of the media file.

The database field is 255 characters in length – anything beyond 255 characters will be truncated.

This can be one of the valid languages associated with your account: English, Spanish, Mixed Spanish/English, French or German. If not present, the submission will inherit the default set via the web UI.

This is the flag to specify which transcription SLA should be used. Normally the default priority associated with the account is used to determine the SLA. This can be used to override that default.

Note that the account must allow the selected SLA level and for prepaid accounts, sufficient prepaid credits must be present.

The permitted SLAs for the user can be found via the submissions->get_transcription_options method.

Presently values may include L (4 Business Day), T (2 Business Day), R (1 Business Day), H (8 Hour), as well as a more generic Y (default expedited transcription for account), and N (default non expedited transcription for account).

This does not apply if you are providing your own transcript.

This is the flag to specify if your own transcription will be provided or not (Y or N). The default is N.

This is the name of the 3rd part transcription entity for the submission request to be sent to. Only applicable if there is more than one transcriber associated with the account. If not present, the submission will inherit the default transcriber set via the web UI. This is rarely used.

These are notes to help the transcriber regarding the spelling of proper names, speaker ID formats, etc.

If there are enabled Persistent Notes to the Transcriber configured on your account, these will be added to each submission first, followed by the content in Notes.

This does not a apply if you are providing your own transcript.

This specifies the integer ID of the persistent note to the transcriber to be used, or 0 if no persistent note to be used (overriding any default).

If not present, the default from the web UI is used to determine the persistent note to the transcriber (if any).

The existing notes for the user can be found via the submissions->get_persistent_notes method.

This does not a apply if you are providing your own transcript.

This specifies the integer ID(s) of the transcriber expertise area to be used, or 0 if no persistent note to be used (overriding any default). If not present, the default from the web UI is used to determine the transcriber expertise area (if any). If more than one is passed they should comma delimited.

The transcriber expertise areas for the user can be found via the submissions->get_transcriber_expertise_options method.

This does not apply if you are providing your own transcript.

This is used to specify offset timecode for broadcast outputs for Captioning submissions in the format hh:mm:ss:ff. If not present, the default offset timecode associated with the account is used. If present for any application type other than Captioning, it will be ignored.

This is the flag to specify if extra charge Result Review should be added to this submission (Y or N).
The default is N.

Note that for Prepaid accounts, sufficient prepaid credits must be present.

If present for any application type other than Captioning, it will be ignored. If not present, the Result Review default set via the web UI will be used.

This is the flag to specify if the process should wait for the customer to approve the transcript before any
caption results are generated (Y or N). The default is N. If present for any application type other than
Captioning, it will be ignored. If not present, the Customer Reviews Transcription default set via the
web UI will be used.

This is the purchase order number for the submission for accounts set up as requiring purchase orders. If not present, the submission will inherit the default or most recently used valid purchase order for the account via the web UI.

Keep in mind that the purchase order number needs to be nicely named -- no spaces, punctuation, or high ASCII characters please.

This tells AST where to send results files back to via HTTP or HTTPS POST with a Content-Transfer-
Encoding of binary. This needs to be present with an approved PartnerType, otherwise this will be ignored.

AST needs to approve your PartnerType in conjunction with the CallBack for any result posting to take place.

This callback URL needs to be properly encoded e.g. %20 for SPACE.

This also needs to be less than 512 characters in length.

If you need more than one result type returned for the submission and/or you need to differentiate between different types of result files posted back (e.g. a caption file and transcript file) an additional {fileType} macro also needs to be present in the callback URL so that different posts can be completed for each result file.

This could result in posts URLs like:

https://67.34.4.22/bio1/closedCaptioning?id=1283232
https://67.34.4.22/bio1/transcript?id=1283232

The specific file types of the macro expansion (e.g., closedCaptioning, transcript, etc.) will need to be configured by AST.
Alternatively, the type of results files can be handled by different MIME types, which will need to be configured by AST.

This tells AST where to send status information back via HTTP or HTTPS POST with a Content-Transfer-Encoding of binary for a particular submission.

This call back URL needs to be properly encoded e.g. %20 for SPACE.

In addition, XML encoding may be required. For example
http://67.34.45.122/status%20results?id=%7B12387987983%7D&course=50 needs to be encoded as
http://67.34.45.122/status%20results?id=%7B12387987983%7D&amp;course=50 to properly escape the &.

The tag also needs to be less than 512 characters in length.

The status information will be directly posted back to the specified URL as a raw POST with a MIME type of text/xml (note that there will not be any form URL encoding). The information will be presented in the following manner:
e.g.

<StatusUpdate>
     <Type>Initial</Type>
     <Result>IN_PROCESS</Result>
     <ASTid>1312468614joe</ASTid>
     <ASTstatus>Awaiting Transcription</ASTstatus>
</StatusUpdate>

The status callback will be sent as soon as a fatal error occurs, but in general as far enough into the ingest processing to know that it is on track to succeed. For example if an error occurs when attempting to extract audio from the media file, the status callback will be sent at that point. Otherwise the system will not send the status callback until the file has been fetched, audio processing has been completed and an AST ID has been assigned.

Type The tag will be one of Initial or Update. A status callback of the type of Update will only occur where a submission which was successfully ingested, subsequently fails or is rejected (the result will be FAILURE).

Result The tag will be one of IN_PROCESS, NOT_INGESTED, or FAILURE. A status callback with a result of FAILURE will only occur where a submission, which was successfully ingested, subsequently fails or is rejected (the type will be Update). e.g.

The transcriber tells us there is just silence in the audio:

<StatusUpdate>
     <Type>Update</Type>
     <Result>FAILURE</Result>
     <ASTid>1312468614joe</ASTid>
     <ASTstatus>Rejected Audio</ASTstatus>
     <ErrDetail>No audio.</ErrDetail>
</StatusUpdate>

ASTid  If the submission was successfully ingested, this tag will reference the unique AST ID that has been assigned to the submission (also known as "submission_id"). The tag will not be present for the Result of NOT_INGESTED.

ASTstatus  If the submission was successfully ingested, this tag will reference the current status of the submission. Possible statuses include "Awaiting Transcription" and "Rejected Audio". The tag will not be present for the Result of NOT_INGESTED.

ErrDetail The tag will only be present for the Result of NOT_INGESTED and FAILURE. e.g.

<StatusUpdate>
     <Type>Update</Type>
     <Result>NOT_INGESTED</Result>
     <ErrDetail>Unable to successfully download URL. Result code 
     is "404 File Not Found".</ErrDetail>
</StatusUpdate>

It is important to consider the possibility that the callback itself fails and no status information about the list item is received (e.g. 500 Internal Server Error). If no status information is received, it is important not to make assumptions about the status, rather further investigation is required.

The application can be changed: e.g. Captioning, Transcription, or Production.

The description presented to the user in lieu of the basename of the media file can be changed.

The database field is 255 characters in length – anything beyond 255 characters will be truncated.

The language can be changed: English, Spanish, Mixed Spanish/English, French or German.

The flag to specify if extra charge Result Review should be added to this submission (Y or N) can be changed.

Note that for Prepaid accounts, sufficient prepaid credits must be present.

If present for any application type other than Captioning, it will be ignored.

This is the flag to specify which transcription SLA should be used. Normally the default priority associated with the account is used to determine the SLA. This can be used to override that default.

Note that the account must allow the selected SLA level and for Prepaid accounts, sufficient prepaid credits must be present.

The permitted SLAs for the user can be found via the submissions->get_transcription_options method.

Presently values may include L (4 Business Day), T (2 Business Day), R (1 Business Day), H (8 Hour), as well as a more generic Y (default expedited transcription for account), and N (default non expedited transcription for account).

This does not apply if you are providing your own transcript.

Notes to help the transcriber regarding the spelling of proper names, speaker ID formats, etc. can be changed.

If there are enabled Persistent Notes to the Transcriber configured on your account, these will be added to each submission first, followed by the content in Notes.

The offset timecode for broadcast outputs for Captioning submissions in the format hh:mm:ss:ff can be changed.

This is comma delimited list of the fields to sort on.
The fields can be any of the those from the list (not list item)
e.g.

language, app, when_created, description

This is a date in the ISO format of YYYY-MM-DD.
Time may be optionally appended as HH:MM:SS. This time is to be interpreted as PT.
One of =, >=, <=, <, >, or <> must be prepended followed by a space.

This can be one of the valid application types associated with your account:e.g. Captioning, Transcription, or Production.

If not present, the submission will inherit the default set via the web UI.

This is used for your tracking purposes and will be presented to the user to describe the list. If you select
to have the list item collected together as a batch, this name will be used as the batch identifier.

This description needs to be unique, though CaptionSync will try to robustly rename the description by appending timestamps if it is not.

The database field is 250 characters in length – anything beyond 250 characters will be truncated.

These are notes to help the transcriber regarding spelling of proper names, speaker ID formats, etc.
will apply to all list items.

If there are enabled Persistent Notes to the Transcriber configured on your account, these will be added to each list item first, followed by the content in Notes.

This specifies the integer ID of the persistent note to the transcriber to be used, or 0 if no persistent note to
be used (overriding any default). If not present, the default from the web UI is used to determine the
persistent note to the transcriber (if any).

The existing notes for the user can be found via the submissions->get_persistent_notes method.

This specifies the integer ID(s) of the transcriber expertise area to be used, or 0 if no persistent note to
be used (overriding any default). If not present, the default from the web UI is used to determine the
transcriber expertise area (if any). If more than one is passed they should comma delimited.

The transcriber expertise areas for the user can be found via the submissions->get_transcriber_expertise_options method.

This can be one of the valid languages associated with your account: e.g. English, French, Spanish, or Mixed Spanish/English. If not present, the list items will inherit the default set via the web UI.

This is the flag to specify which transcription SLA should be used. Normally the default priority associated with the account is used to determine the SLA. This can be used to override that default.

Note that the account must allow the selected SLA level, and for Prepaid accounts, sufficient prepaid credits must be present.

The permitted SLAs for the user can be found via the submissions->get_transcription_options method.

Presently values may include L (4 Business Day), T (2 Business Day), R (1 Business Day), H (8 Hour), as well as a more generic Y (default expedited transcription for account), and N (default non expedited transcription for account).

This is the flag to specify if extra charge Result Review should be added to the submissions in this list (Y or N).The default is N.

Note that for Prepaid accounts, sufficient prepaid credits must be present.

If present for any application type other than Captioning, it will be ignored. If not present, the Result Review default set via the web UI will be used.

This is the flag to specify that the list items should be grouped together as a batch for reporting and
collecting of results (all results for a particular batch are zipped together for retrieval via SFTP or the web
UI and will use the cleansed value of Description as the batch identifier). Values are (Y or N). If not present, the list items will not be grouped together as a batch.

This is used to specify offset timecode for broadcast outputs for Captioning application types in the format hh:mm:ss:ff. If not present, the default offset timecode associated with the account is used. If present for any application type other than Captioning, it will be ignored.

This is the purchase order number for the list for accounts set up as requiring purchase orders. If not present, the list will inherit the default or most recently used valid purchase order for the account via the web UI.

Keep in mind that the purchase order number needs to be nicely named -- no spaces, punctuation, or high ASCII characters please.

This tells AST where to get the media file from, and what type it is. In general the URL needs to
specifically call out the media file, but additional GET parameters can be added.

This URL needs to be properly encoded e.g. %20 for SPACE.

This needs to be less than 1024 characters in length.

This tells AST where to send results files back to via HTTP or HTTPS POST with a Content-Transfer-Encoding of binary. This needs to be present with an approved PartnerType, otherwise this will be ignored.

AST needs to approve your PartnerType in conjunction with the CallBack for any result posting to take place.

This callback URL needs to be properly encoded e.g. %20 for SPACE.

This also needs to be less than 512 characters in length.

If you need more than one result type returned for the submission and/or you need to differentiate between different types of result files posted back (e.g. a caption file and transcript file) an additional {fileType} macro also needs to be present in the callback URL so that different posts can be completed for each result file.

This could result in posts URLs like:

https://67.34.4.22/bio1/closedCaptioning?id=1283232
https://67.34.4.22/bio1/transcript?id=1283232

The specific file types of the macro expansion (e.g., closedCaptioning, transcript, etc.) will need to be configured by AST.

Alternatively, the type of results files can be handled by different MIME types, which will need to be configured by AST.

This tells AST how to name the media file basename (which is used as a description in the submission
pertaining to this list item). If not present the system will try to use an appropriate name gleaned from the URL.

It needs to be nicely named and less than 128 characters -- no spaces, punctuation, or high ASCII characters please.

This tells AST where to send status information back via HTTP or HTTPS POST with a Content-Transfer-Encoding of binary for a particular list item.

This call back URL needs to be properly encoded e.g. %20 for SPACE.

In addition, XML encoding may be required. For example
http://67.34.45.122/status%20results?id=%7B12387987983%7D&course=50 needs to be encoded as
http://67.34.45.122/status%20results?id=%7B12387987983%7D&amp;course=50 to properly escape the &.

The tag also needs to be less than 512 characters in length.

The status information will be directly posted back to the specified URL as a raw POST with a MIME type of text/xml (note that there will not be any form URL encoding). The information will be presented in the following manner:
e.g.

<StatusUpdate>
     <Type>Initial</Type>
     <Result>IN_PROCESS</Result>
     <ASTid>1312468614joe</ASTid>
     <ASTstatus>Awaiting Transcription</ASTstatus>
</StatusUpdate>

The status callback will be sent as soon as a fatal error occurs, but in general as far enough into the ingest processing to know that it is on track to succeed. For example if a 404 error occurs when attempting to fetch the media file, the status callback will be sent at that point. Otherwise the system will not send the status callback until the file has been fetched, audio processing has been completed and an AST ID has been assigned.

Type The tag will be one of Initial or Update. A status callback of the type of Update will only occur where a submission which was successfully ingested, subsequently fails or is rejected (the result will be FAILURE).

Result The tag will be one of IN_PROCESS, NOT_INGESTED, or FAILURE. A status callback with a result of FAILURE will only occur where a submission, which was successfully ingested, subsequently fails or is rejected (the type will be Update). e.g.

The transcriber tells us there is just silence in the audio:

<StatusUpdate>
     <Type>Update</Type>
     <Result>FAILURE</Result>
     <ASTid>1312468614joe</ASTid>
     <ASTstatus>Rejected Audio</ASTstatus>
     <ErrDetail>No audio.</ErrDetail>
</StatusUpdate>

ASTid  If the submission was successfully ingested, this tag will reference the unique AST ID that has been assigned to the submission. The tag will not be present for the Result of NOT_INGESTED.

ASTstatus  If the submission was successfully ingested, this tag will reference the current status of the submission. Possible statuses include "Awaiting Transcription" and "Rejected Audio". The tag will not be present for the Result of NOT_INGESTED.

ErrDetail The tag will only be present for the Result of NOT_INGESTED and FAILURE. e.g.

<StatusUpdate>
     <Type>Initial</Type>
     <Result>NOT_INGESTED</Result>
     <ErrDetail>Unable to successfully download URL. 
     Result code is "404 File Not Found".</ErrDetail>
</StatusUpdate>

It is important to consider the possibility that the callback itself fails and no status information about the list item is received (e.g. 500 Internal Server Error). If no status information is received, it is important not to make assumptions about the status, rather further investigation is required.

The application can be changed: e.g. Captioning, Transcription, or Production.

The database field is 255 characters in length – anything beyond 255 characters will be truncated.

The language can be changed: e.g. English, French, Spanish, or Mixed Spanish/English.

The flag to specify if extra charge Result Review can be changed for submissions in this list (Y or N).

Note that for Prepaid accounts, sufficient prepaid credits must be present.

If present for any application type other than Captioning, it will be ignored.

The flag to specify that the list items should be grouped together as a batch for reporting and collecting of results can be changed (all results for a particular batch are zipped together for retrieval via SFTP or the web UI and will use the cleansed value of Description as the batch identifier). Values are (Y or N). If not present, the list items will not be grouped together as a batch.

This is the flag to specify which transcription SLA should be used. Normally the default priority associated with the account is used to determine the SLA. This can be used to override that default.

Note that the account must allow the selected SLA level and for Prepaid accounts, sufficient prepaid credits must be present.

The permitted SLAs for the user can be found via the submissions->get_transcription_options method.

Presently values may include L (4 Business Day), T (2 Business Day), R (1 Business Day), H (8 Hour), as well as a more generic Y (default expedited transcription for account), and N (default non expedited transcription for account).

Notes to help the transcriber regarding the spelling of proper names, speaker ID formats, etc. can be changed.

If there are enabled Persistent Notes to the Transcriber configured on your account, these will be added to each submission first, followed by the content in Notes.

This is used to specify offset timecode for broadcast outputs for Captioning application types in the format hh:mm:ss:ff can be changed.