Dotsub API

The Dotsub REST API provides you a fast and simple way to query our system. We provide methods to upload videos and captions, monitor the status your videos and access to your video captions. We cannot wait to see what you can create with our API.

If you are one of our enterprise clients you also have access to the 'Extended API'. This API extension allows you to programmatically order captions, translations and files from Dotsub. It also provides facilities to monitor your orders and track your captioning and translation costs.

Authentication

Our API uses HTTP Basic authentication. Please use your Dotsub username as password for authenticated API requests.

External Identifiers

Our API allows you to set an external identifier on videos. This field is a place to store your systems ID for a given video. As an example; our enterprise integration with Brightcove stores the Brightcove ID in this field.

External Identifier has to be unique per username. You can use this to query videos without having to save our UUID.

General Information on API responses

Please always check the HTTP Status code before processing the reply. Status codes of 400, 401, some 404s will not return a JSON reply. When possible the API will return additional information on an error in a JSON format.

{
  "status": {
    "message": "Unable to find media for external id '839' in user 'tester'",
    "error": true,
    "code": 404
  }
}

Public API

Our public API is accessible to everyone.

Language API

Language Listing

Path: https://dotsub.com/api/language

Method: GET

Shows a listing of the languages supported by Dotsub.

Example Response

{
    "languages":{
        "abk":"Abkhaz",
        "ace":"Aceh (Achenese)",
        "ach":"Acholi (Acoli)",
        "ady":"Adyghe (Adygei)",
        "aar":"Afar",
        "afh":"Afrihili",
        "afr":"Afrikaans",
        "afa":"Afro-Asiatic",
        "ain":"Ainu",
        "aka":"Akan",
        "akk":"Akkadian",
        "alb":"Albanian",
        "ale":"Aleut",
        "alg":"Algonquian languages",
        "alt":"Altai, Southern"
    …
    }
}

Language Mapping

Path: https://dotsub.com/api/language?code=$languageCode

Method: GET

Some sites use ISO-693-2 others use ISO-693-3 language codes. This method provides an API method to map these codes to Dotsub's language codes. You can send any code to Dotsub and it will reply with the code that should be used to load that language on Dotsub.com

Name Description Required
code The language code you are looking up on Dotsub. This can be a ISO-693-3, ISO-693-2 or Dotsub language code. Yes

Example Response

{
    "language": {
        "direction": "ltr",
        "iso2Code": "en",
        "legacyCodes": [
            "en"
        ],
        "languageNameLocalized": "English",
        "languageName": "English",
        "iso3Code": "eng"
    }
}

Media API

Upload

Path: https://dotsub.com/api/media

Method: POST

You can upload media to Dotsub from your system using a HTTP Post to our media upload API. This form does require you to be authenticated.

Request Parameters

Name Description Required
title The title of this video. Yes
description A description of this video. This can not be more than 800 characters. Yes
language The source language of the video. This is the 3 letter ISO code that can be found using the languages API call. Yes
license The ID of the license of this video. License ID's can be obtained from our license API. Yes
file The file you are uploading. This should be included as part of a multi-part post request. A request must contain file or url
url A url to the file to be uploaded to Dotsub. This must be a url directly to a video file not a webpage that contains a video. A request must contain file or url
country The country code of this video. Ex: CA, US, CZ No
genre The genre of this video. This will default to none if omitted. No
producer The producer of this video. No
director The director of this video. No
publicity This value determines if the video is publicly listed on Dotsub. This value defaults to false. No
publicallyViewable This value determines if a video is listed on the public listing pages (Latest, Most Viewed, Videos from User). Defaults to 'true'. This option is only used if publicity is 'true'. No
externalIdentifier The external ID you wish to use for this video. No
project The ID of the project you want to post this video to. Please consult the Project API to get a listing of the projects available to you. No
postToProjectAsDefaultUser This determines if a video will default to the user that is specified on the project. Default 'true' if project is present. No
doNotCaption If you have a standing caption or translation order this lets us know this item should not be captioned or translated. Defaults to 'false'. No

Example Response

{
  "status": {
    "message": "Media created",
    "error": false,
    "uuid": "b98b2559-5440-4eef-bd22-a4e482f5ebe6",
    "code": 200
  }
}

Metadata

Path: https://dotsub.com/api/media/$UUID or https://dotsub.com/api/user/$username/media/$externalIdentifier

Method: GET

You can retrieve the metadata of a given media via this call.

Request Parameters

Name Description Required
includeEmptyTranslations If you set this parameter to true, translations with no work done will also be included in the response. This defaults to false. No

Example Response

{
  "genre": "genre.publicServiceAnnouncement",
  "numberOfViews": 82519,
  "numberOfLanguages": 2,
  "numberOfTranslations": 1,
  "languages": {
    "eng": {
      "workflowStatus": null,
      "lastModified": 1188338461138,
      "languageNameLocalized": "English",
      "properties": {

      },
      "languageName": "English",
      "languageCode": "eng",
      "percentageComplete": 100,
      "title": "Sample Video",
      "level": "professional",
      "description": "Orbiting the sun at about 98 million miles is a little blue planet and this planet is run by a bunch of monkeys.\n\n Now, the monkeys don't think of themselves as monkeys...\n ",
      "workflowStatusLastModified": 0,
      "languageDirection": "ltr",
      "dateCreated": 1188334861138,
      "actors": {

      }
    },
    "spa": {
      "workflowStatus": null,
      "lastModified": 1188331261138,
      "languageNameLocalized": "Espa\u00f1ol",
      "languageName": "Spanish",
      "languageCode": "spa",
      "percentageComplete": 100,
      "title": "Video Ejemplo",
      "level": "human",
      "description": "El sol en \u00f3rbita alrededor de 98 millones de millas es un peque\u00f1o planeta azul y el planeta es\n dirigido por un grupo de monos. Ahora, los monos no se ven a s\u00ed mismos como los monos ...\n ",
      "workflowStatusLastModified": 0,
      "languageDirection": "ltr",
      "dateCreated": 1188324061138,
      "actors": {
        "REVISOR": "otheruser",
        "TRANSLATOR": "user"
      }
    }
  },
  "screenshotURI": "http:\/\/dotsub.com\/media\/af0e8151-f78a-4168-8712-9cc6f8b9e2dc\/p",
  "title": "Dance, Monkeys, Dance by Ernie Cline",
  "description": "Orbiting the sun at about 98 million miles is a little blue planet and this planet is run by a bunch of monkeys.\n\n Now, the monkeys don't think of themselves as monkeys...\n ",
  "type": "LocalMedia",
  "license": {
    "description": "By selecting \"Other\" your media is licensed under the dotSUB terms of service",
    "id": "a2be14e0-37d9-11dd-ae16-0800200c9a66",
    "name": "dotSUB - Other",
    "url": "http:\/\/dotsub.com\/termsOfUse.jsp"
  },
  "displayURI": "http:\/\/dotsub.com\/view\/af0e8151-f78a-4168-8712-9cc6f8b9e2dc",
  "workflowStatus": "READY",
  "transcriptionStatus": "COMPLETED",
  "lastModified": 1156957261138,
  "transcriptionCompletion": 100,
  "isPublic": true,
  "director": null,
  "duration": 233000,
  "producer": null,
  "translateURIPattern": "http:\/\/dotsub.com\/translate\/af0e8151-f78a-4168-8712-9cc6f8b9e2dc\/",
  "dateCreated": 1156957261138,
  "externalIdentifier": "625719",
  "uuid": "af0e8151-f78a-4168-8712-9cc6f8b9e2dc",
  "language": "eng",
  "user": "user"
}

Metadata Editing

Path: https://dotsub.com/api/media/$UUID or https://dotsub.com/api/user/$username/media/$externalIdentifier

Method: POST

You can update the metadata for a media via this call. Any omitted fields will retain their existing values.

Request Parameters

Name Description Required
title The title of this video. Yes
description A description of this video. This can not be more than 800 characters. Yes
language The source language of the video. This is the 3 letter ISO code that can be found using the languages API call. Yes
country The country code of this video. Ex: CA, US, CZ No
genre The genre of this video. This will default to none if omitted. No
producer The producer of this video. No
director The director of this video. No
publicity This value determines if the video is publicly listed on Dotsub. No
publicallyViewable This value determines if a video is listed on the public listing pages (Latest, Most Viewed, Videos from User). No
externalIdentifier The external ID you wish to use for this video. No
projectId The ID of the project that this video is a memeber of. Sitting this value to "" will remove it from its current project. No

Example Response

{
  "status": {
    "message": "Media Metadata Updated",
    "error": false,
    "code": 200
  }
}

Media Delete

Path: https://dotsub.com/api/media/$UUID or https://dotsub.com/api/user/$username/media/$externalIdentifier

Method: DELETE

A media can be removed from the system using this API call.

Example Response

{
  "status": {
    "message": "Media Deleted",
    "error": false,
    "code": 200
  }
}

Add Media Permissions

Path: https://dotsub.com/api/media/$UUID/permissions

Method: PUT

The media permission API allows you to add permissions to videos on Dotsub. Permissions can be added per user or as general settings on a video.

Request Parameters

Name Description Required
action The type of permission to add. This is a CASE sensitive field. This can have the following values:
Action Description
READ Allow a user to read the video.
WRITE Allow the user to make changes to the video.
UPDATE_TRANSCRIPTION Allow the user to transcribe the video. Omitting the username parameter in a request with this action allows 'all registered' Dotsub users to preform this action
CREATE_TRANSLATION Allow the user to create new translations on the video. Omitting the username parameter in a request with this action allows 'all registered' Dotsub users to preform this action.
Yes
username The username of the user to add the permission to access this video. Omitting this value will allow you to add permissions for 'all registered' users of Dotsub, this can only be done for 'UPDATE_TRANSCRIPTION' and 'CREATE_TRANSLATION'. No

Example Response

{
  "status": {
    "message": "Permission added to media",
    "error": false,
    "code": 200
  }
}

Add Media Permissions

Path: https://dotsub.com/api/media/$UUID/permissions

Method: DELETE

The media permission API allows you to delete permissions from videos on Dotsub.

Request Parameters

Name Description Required
action The type of permission to add. This is a CASE sensitive field. This can have the following values:
Action Description
READ Allow a user to read the video.
WRITE Allow the user to make changes to the video.
UPDATE_TRANSCRIPTION Allow the user to transcribe the video. Omitting the username parameter in a request with this action allows 'all registered' Dotsub users to preform this action
CREATE_TRANSLATION Allow the user to create new translations on the video. Omitting the username parameter in a request with this action allows 'all registered' Dotsub users to preform this action.
Yes
username The username of the user to add the permission to access this video. Omitting this value will allow you to add permissions for 'all registered' users of Dotsub, this can only be done for 'UPDATE_TRANSCRIPTION' and 'CREATE_TRANSLATION'. No

Example Response

{
  "status": {
    "message": "Permission removed from media",
    "error": false,
    "code": 200
  }
}

Media Query

Path: https://dotsub.com/api/media

Method: GET

The Media Query API allows you to query public videos in Dotsub. This API returns any videos that are public and publicly listed.

Request Parameters

Name Description Required
q The search query you wish to do.
Query Syntax

Query syntax is straightforward. Some examples:

To return media with the word "monkeys" anywhere in the metadata or transcript AND that it is available in English: monkeys AND language:eng (Which needs to be URL-encoded into: monkeys%20AND%20language:eng)

To return media that start with the word "Adobe" in the "title" field: title:Adobe*

We can do fuzzy searches, which are cool: title:humane~ This will return media with title containing "human", for example.

More examples:

(description:leakey OR title:leakey) AND language:ger

numberOfTranslations:[5 TO 99]

Supported query fields: description, title, country, language, genre, workflowStatus, preview, dateCreated, publicity, displayToPublic, length, year, lastModified, numberOfTranslations, transcription, createdBy, translationList, numberOfViews, numberOfEmbeddedViews and availableTranslations

No
limit The number of results per page. This defaults to 20. No
start The first result to return. This defaults to 0. No
{
  "result": [
    {
      "screenshotURI": "http:\/\/dotub.com\/media\/af0e8151-f78a-4168-8712-9cc6f8b9e2dc\/p",
      "translateURIPattern": "http:\/\/dotub.com\/translate\/af0e8151-f78a-4168-8712-9cc6f8b9e2dc\/",
      "displayURI": "http:\/\/dotub.com\/view\/af0e8151-f78a-4168-8712-9cc6f8b9e2dc",
      "duration": 233000,
      "numberOfLanguages": 2,
      "numberOfTranslations": 1,
      "transcriptionCompletion": 100,
      "numberOfViews": 82519,
      "language": "eng",
      "genre": "genre.publicServiceAnnouncement",
      "user": "user",
      "uuid": "af0e8151-f78a-4168-8712-9cc6f8b9e2dc",
      "description": "Orbiting the sun at about 98 million miles is a little blue planet and this planet is run by a bunch of monkeys.\n\n                Now, the monkeys don't think of themselves as monkeys...\n            ",
      "type": "LocalMedia",
      "title": "Sample Video",
      "license": {
        "description": "By selecting \"Other\" your media is licensed under the dotSUB terms of service",
        "id": "a2be14e0-37d9-11dd-ae16-0800200c9a66",
        "name": "dotSUB - Other",
        "url": "http:\/\/www.dotsub.com\/termsOfUse.jsp"
      },
      "externalIdentifier": "625719",
      "transcriptionStatus": "COMPLETED",
      "isPublic": true,
      "producer": null,
      "director": null,
      "dateCreated": 1156957261138,
      "lastModified": 1411129183108,
      "workflowStatus": "READY",
      "languages": {
        "eng": {
          "workflowStatus": null,
          "lastModified": 1188338461138,
          "languageNameLocalized": "English",
          "properties": {

          },
          "languageName": "English",
          "languageCode": "eng",
          "percentageComplete": 100,
          "title": "Sample Video",
          "level": "professional",
          "description": "Orbiting the sun at about 98 million miles is a little blue planet and this planet is run by a bunch of monkeys.\n\n                Now, the monkeys don't think of themselves as monkeys...\n            ",
          "workflowStatusLastModified": 0,
          "languageDirection": "ltr",
          "dateCreated": 1188334861138,
          "actors": {

          }
        },
        "spa": {
          "workflowStatus": null,
          "lastModified": 1188331261138,
          "languageNameLocalized": "Espa\u00f1ol",
          "properties": {
            "Reviewer": "Brooks",
            "Published": "True",
            "Translator": "Adam"
          },
          "languageName": "Spanish",
          "languageCode": "spa",
          "percentageComplete": 100,
          "title": "Danza, monos, Danza por Ernie Cline",
          "level": "human",
          "description": "El sol en \u00f3rbita alrededor de 98 millones de millas es un peque\u00f1o planeta azul y el planeta es\n                dirigido por un grupo de monos. Ahora, los monos no se ven a s\u00ed mismos como los monos ...\n            ",
          "workflowStatusLastModified": 0,
          "languageDirection": "ltr",
          "dateCreated": 1188324061138,
          "actors": {
            "REVISOR": "otheruser",
            "TRANSLATOR": "user"
          }
        }
      }
    }
  ],
  "pagesize": 20,
  "sortField": "dateCreated",
  "totalResults": 1,
  "sortDirection": "desc",
  "offset": 0,
  "totalPages": 1
}

Captions API

Caption Listing

Path: https://dotsub.com/api/media/$UUID/captions?language=$languageCode or https://dotsub.com/api/user/$username/media/$externalIdentifier/captions?language=$languageCode

Method: GET

You can retrieve the captions of a given media in a selected language via this call. The captions will be returned if they exist. If there are no captions in the selected language an error will be returned.

Example Response

{
  "captions": [
    {
      "content": "There are billions of galaxies in the observable universe",
      "startTime": 7000,
      "duration": 3000,
      "startOfParagraph": false
    },
    {
      "content": "And each of them contains hundreds of billions of stars",
      "startTime": 10000,
      "duration": 4000,
      "startOfParagraph": false
    },
    …
    {
      "content": "They want to be something else But they're not.",
      "startTime": 231000,
      "duration": 3000,
      "startOfParagraph": false
    }
  ]
}

Transcription Upload

Path: https://dotsub.com/api/media/$UUID/transcription or https://dotsub.com/api/user/$username/media/$externalIdentifier/transcription

Method: POST

You can upload an existing caption file as the video transcription. Most standard subtitle formats are supported (ex: SRT, WebVTT, Timed Text).

Request Parameters

Name Description Required
file The caption file to be uploaded as the transcription. Yes

Example Response

{
  "status": {
    "message": "File imported",
    "error": false,
    "code": 200
  }
}

Translation Upload

Path: https://dotsub.com/api/media/$UUID/translation or https://dotsub.com/api/user/$username/media/$externalIdentifier/translation

Method: POST

You can upload an existing caption file as a video translation. Most standard subtitle formats are supported (ex: SRT, WebVTT, Timed Text).

Please note: Dotsub requires the timing of a translation to exactly match the timing of the transcription.

Request Parameters

Name Description Required
file The caption file to be uploaded as the transcription. Yes
language The language of this translation. Yes

Example Response

{
  "status": {
    "message": "File imported",
    "error": false,
    "code": 200
  }
}

Transcription Quality Level

Path: https://dotsub.com/api/media/$UUID/transcription or https://dotsub.com/api/user/$username/media/$externalIdentifier/transcription

Method: POST

You can tag the quality level of a transcription using this API. This value will be returned in all metadata calls for future use.

Request Parameters

Name Description Required
level The caption file to be uploaded as the transcription. Yes

Example Response

{
  "status": {
    "message": "Transcription Level Set",
    "error": false,
    "code": 200
  }
}

Translation Quality Level

Path: https://dotsub.com/api/media/$UUID/translation or https://dotsub.com/api/user/$username/media/$externalIdentifier/translation

Method: POST

You can tag the quality level of a translation using this API. This value will be returned in all metadata calls for future use.

Request Parameters

Name Description Required
level The caption file to be uploaded as the transcription. Yes
language The translation language to set this level on. Yes

Example Response

{
  "status": {
    "message": "Translation Level Set",
    "error": false,
    "code": 200
  }
}

Translation/Transcription File Download

Path: https://dotsub.com/media/$UUID/c/$languageCode/$format or https://dotsub.com/media/u/$username/$externalIdentifier/c/$languageCode/$format

Method: POST

Translation and transcription files can be downloaded from Dotsub using the following requests. Any private videos will require you to be authenticated to download.

Request Parameters

Name Description Required
format The format of file you would like to receive. This can be any of the following:
Format Description
srt A SRT file.
tt A DFXP/Timed Text file.
vtt A WebVTT file.
txt A text file. (no timing included)
csv A Comman Seperated Values file.
Yes
language The language of the captions to be downloaded. Yes
offset This parameter can be used to shift a subtitle file by a given number of seconds. Ex: Setting offset to 3.5 will shift all subtitles forward by 3.5 seconds. No. Defaults to 0

License API

License Listing

Path: https://dotsub.com/api/license

Method: GET

Shows a listing of the video licenses supported by Dotsub.

Example Response

{
  "licenses": [
    {
      "active": true,
      "description": "dotSUB has adopted the 'CC-Attribution Non-Commercial No Derivatives' license as our default license. This license is the most restrictive of the six main CC licenses, allowing redistribution. This license is often called the 'free advertising' license because it allows others to download your works and share them with others as long as they mention you and link back to you, but they can't change them in any way or use them commercially.",
      "id": "a2be14e1-37d9-11dd-ae16-0800200c9a66",
      "licenseVersion": "3.0",
      "name": "CC - Attribution Non-commercial No Derivatives",
      "url": "http:\/\/creativecommons.org\/licenses\/by-nc-nd\/3.0\/"
    },
    …
    {
      "active": true,
      "description": "\"All rights reserved\" indicates that the copyright holder reserves, or holds for their own use, all the rights provided by copyright law, such as distribution, performance, and creation of derivative works; and they have not waived any such right.",
      "id": "ffc28f46-e302-450a-907b-c818f9eaf54f",
      "licenseVersion": "1.0",
      "name": "All rights reserved",
      "url": ""
    }
  ]
}

JSON-P API

This API allows you to load a javascript file on your site containing the subtitles or video metadata. This must include a callback function to be called on your site once the captions have loaded. This allows you to use in browser javascript to add subtitles

JSON-P Metadata

Path: https://dotsub.com/media/$UUID/md/js-metadata?callback=$functionName or https://dotsub.com/media/u/$username/$externalIdentifier/md/js-metadata?callback=$functionName

Method: GET

Fetches video metadata in a json format that calls the configured callback function.

Request Parameters

Name Description Required
callback The name of the javascript function to call. Yes

JSON-P Caption

Path: https://dotsub.com/media/$UUID/c/$languageCode/js?callback=$functionName or https://dotsub.com/media/u/$username/$externalIdentifier/c/$languageCode/js?callback=$functionName

Method: GET

Fetches video metadata in a json format that calls the configured callback function.

Request Parameters

Name Description Required
callback The name of the javascript function to call. Yes
language The language of the the requested captions. Yes

YouTube Sync API

Dotsub supports the ability to use its YouTube Publishing feature directly from our API. This allows you to manage your subtitles on YouTube directly from the Dotsub API.

Please note: In order to use this feature you must first link your Dotsub and YouTube Accounts. This can be done under My Account.

YouTube Push

Path: https://dotsub.com/api/media/$UUID/youtube/push or https://dotsub.com/api/user/$USERNAME/media/$externalIdentifier/youtube/push

Method: POST

Uploads a Dotsub video and its captions into your YouTube account.

YouTube Match

Path: https://dotsub.com/api/media/$UUID/youtube/match or https://dotsub.com/api/user/$USERNAME/media/$externalIdentifier/youtube/match

Method: POST

This will tell Dotsub to sync the captions of your Dotsub video to the video on YouTube with this YouTubeId. This request needs to only be sent once per video. Once a video is matched you can use the /sync API call.

Request Parameters

Name Description Required
youtubeId The id of this video in your YouTube account. Yes

YouTube Sync

Path: https://dotsub.com/api/media/$UUID/youtube/sync or https://dotsub.com/api/user/$USERNAME/media/$externalIdentifier/youtube/sync

Method: POST

Updates the video on YouTube subtitles. You have to have pushed or matched a video previously.

YouTube Clear

Path: https://dotsub.com/api/media/$UUID/youtube/clear or https://dotsub.com/api/user/$USERNAME/media/$externalIdentifier/youtube/clear

Method: POST

You can clear the YouTube state of a video using this call. This will break any link to YouTube that a video has on Dotsub. Note: This will NOT delete existing subtitles from YouTube.

YouTube Status

Path: https://dotsub.com/api/media/$UUID/youtube/status or https://dotsub.com/api/user/$USERNAME/media/$externalIdentifier/youtube/status

Method: GET

This will return a JSON object telling you the YouTube ID of a given video on Dotsub. If the video is not synced to YouTube the value of youtubeId in the returning JSON will be 'null'.

Sample Response

{
  "status": {
    "error": false,
    "code": 200,
    "youtubeId": 'zX52pONpD-Y'
  }
}

Extended API

Our extended API is available to our enterprise clients. It provides access to the order and project objects. If you'd like to become an enterprise client please contact us.

Media Workflow

Path: https://dotsub.com/api/media/$UUID/workflow or https://dotsub.com/api/user/$username/media/$externalIdentifier/workflow

Method: POST

Changes can be made to the workflow state of translations and transcriptions via this API.

Name Description Required
workflowStatus The status you want to change to. ["ASSIGNED", "TRANSLATED", "TRANSCRIBED", "REVISED", "PUBLISHED"] Yes
language The language of the subtitles you wish to change state. Yes
useTransition This defaults to 'false'. Set this to 'true' if you want Dotsub to use the workflow to change states. No

Example Response

{
  "status": {
    "message": "Workflow Status Set",
    "error": false,
    "code": 200
  }
}

Captioning API

The captioning API allows you to add/edit/remove items from a videos captions. This API can be used to create you own captioning experience.

Add Caption

Path: https://dotsub.com/api/media/$UUID/transcription/items

Method: POST

Adds an item to a transcription.

Name Description Required
start The time in millisecond when the caption is shown. Yes
duration How long the caption will be shown on the video. Yes
content The text content of the caption. Yes
startOfParagraph Denotes if this caption starts a new paragraph. (Default: false) No

Example Response

{
   "status":{
      "message":"Caption Added",
      "error":false,
      "code":200
   },
   "item":{
      "content":"A wonderful little caption",
      "duration":2000,
      "id":"2f720dd6-16a5-461b-af32-1f22a78605b7",
      "startOfParagraph":false,
      "startTime":0
   }
}

Edit Caption

Path: https://dotsub.com/api/media/$UUID/transcription/items/$captionId

Method: POST

Edits an existing item in a transcription.

Name Description Required
captionId The time ID of the caption to be edited. Yes
start The time in millisecond when the caption is shown. Yes
duration How long the caption will be shown on the video. Yes
content The text content of the caption. Yes
startOfParagraph Denotes if this caption starts a new paragraph. (Default: false) No

Example Response

{
   "status":{
      "message":"Caption Updated",
      "error":false,
      "code":200
   },
   "item":{
      "content":"A wonderful little edit",
      "duration":2000,
      "id":"2f720dd6-16a5-461b-af32-1f22a78605b7",
      "startOfParagraph":false,
      "startTime":0
   }
}

Delete Caption

Path: https://dotsub.com/api/media/$UUID/transcription/items/$captionId

Method: DELETE

Deletes an existing item in a transcription.

Name Description Required
captionId The time ID of the caption to be edited. Yes

Example Response

{
   "status":{
      "message":"Caption Deleted",
      "error":false,
      "code":200
   }
}

List Captions

Path: https://dotsub.com/api/media/$UUID/transcription/items

Method: GET

Lists all items in a transcription.

Example Response

{
   "items":[
      {
         "content":"You've seen the word, you've seen the websites,",
         "duration":2000,
         "id":"9991",
         "startOfParagraph":false,
         "startTime":0
      },
      {
         "content":"and you may even have one.",
         "duration":2000,
         "id":"9992",
         "startOfParagraph":false,
         "startTime":2000
      },
      {
         "content":"But have you ever wondered, what's the big deal about blogs?",
         "duration":3000,
         "id":"9993",
         "startOfParagraph":false,
         "startTime":4000
      }
   ]
}

Add Translation

Path: https://dotsub.com/api/media/$UUID/translation/$languageCode/items

Method: POST

Adds an item to a translation.

Name Description Required
captionId The caption you are translating. Yes
content The text content of the caption. Yes

Example Response

{
   "status":{
      "message":"Translation Item Added",
      "error":false,
      "code":200
   },
   "item":{
      "content":"Foo",
      "duration":2000,
      "id":"1a82ce49-5ed5-4935-a039-1d848c5f4c92",
      "locale":"fin",
      "startOfParagraph":false,
      "startTime":2000
   }
}

Edit Translation

Path: https://dotsub.com/api/media/$UUID/translation/$langaugeCode/items/$translationId

Method: POST

Edits an existing item in a translation.

Name Description Required
content The text content of the caption. Yes

Example Response

{
   "status":{
      "message":"Translation Item Updated",
      "error":false,
      "code":200
   },
   "item":{
      "content":"Foo",
      "duration":2000,
      "id":"1198adf8-30a1-4d54-9774-179c825cc80a",
      "locale":"fin",
      "startOfParagraph":false,
      "startTime":2000
   }
}

Delete Translation

Path: https://dotsub.com/api/media/$UUID/translation/$languageCode/items/$translationID

Method: DELETE

Deletes an existing item in a translation.

Example Response

{
   "status":{
      "message":"Translation Item Deleted",
      "error":false,
      "code":200
   }
}

List Translation

Path: https://dotsub.com/api/media/$UUID/translation/$langaugeCode/items

Method: GET

Lists all items in a translation.

Example Response

{
   "items":[
      {
         "content":"Hay millones d galaxias en el universo que vemos",
         "duration":3000,
         "id":"201",
         "locale":"spa",
         "startOfParagraph":false,
         "startTime":7000
      },
      {
         "content":"Y cada una de ellas contiene billones de estrellas",
         "duration":4000,
         "id":"202",
         "locale":"spa",
         "startOfParagraph":false,
         "startTime":10000
      },
      {
         "content":"En una de estas galaxias",
         "duration":2000,
         "id":"203",
         "locale":"spa",
         "startOfParagraph":false,
         "startTime":14000
      },
      {
         "content":"Orbitando una de estas estrellas",
         "duration":2000,
         "id":"204",
         "locale":"spa",
         "startOfParagraph":false,
         "startTime":16000
      },
      {
         "content":"Hay un planeta azul",
         "duration":2000,
         "id":"205",
         "locale":"spa",
         "startOfParagraph":false,
         "startTime":18000
      }
   ]
}

Project API

Project Listing

Path: https://dotsub.com/api/project

Method: GET

The project listing API will list all projects a user currently manages.

Example Response

{
  "projects": [
    {
      "id": "46f16bf2-84e7-11dd-8608-f3f9661facd6",
      "title": "Sample Project One"
    },
    {
      "id": "99e514b0-8b29-11dd-ad8b-0800200c9a66",
      "title": "Test Project Two"
    }
  ]
}

Project Media Listing

Path: https://dotsub.com/api/project/$projectId/media

Method: GET

The project media API will list all media in a given project.

Request Parameters

Name Description Required
limit The number of results per page. This defaults to 20. No
start The first result to return. This defaults to 0. No

Example Response

{
  "limit": 20,
  "sort": "dateCreated",
  "results": 2,
  "start": 0,
  "dir": "DESC",
  "media": [
    {
      "dateCreated": 1188320461138,
      "externalIdentifier": "",
      "id": "9f0e8151-f78a-4168-b712-9006f8b9e2dc",
      "language": "eng",
      "lastModified": 1219942861138,
      "numberOfTranslations": 0,
      "numberOfViews": 876,
      "title": "Conversion Failed",
      "workflowStatus": "PROCESSING_FAILED"
    },
    {
      "dateCreated": 1156957261138,
      "externalIdentifier": "625719",
      "id": "af0e8151-f78a-4168-8712-9cc6f8b9e2dc",
      "language": "eng",
      "lastModified": 1156957261138,
      "numberOfTranslations": 2,
      "numberOfViews": 82519,
      "title": "Test Video One",
      "workflowStatus": "READY"
    }
  ]
}

Add Media to Project

Path: https://dotsub.com/api/project/$projectId/media

Method: PUT

The project add media API allows you to add videos from your project on Dotsub.

Request Parameters

Name Description Required
uuid The uuid of the media to be added to the project. Yes

Example Response

{
  "status": {
    "message": "Media added to project",
    "error": false,
    "code": 200
  }
}

Remove Media from Project

Path: https://dotsub.com/api/project/$projectId/media

Method: DELETE

The project remove media API allows you to remove videos from your project on Dotsub.

Request Parameters

Name Description Required
uuid The uuid of the media to be added to the project. Yes

Example Response

{
  "status": {
    "message": "Media removed from project",
    "error": false,
    "code": 200
  }
}

Project Transcribers/Translators

Path: https://dotsub.com/api/project/$projectId/transcribers and https://dotsub.com/api/project/$projectId/translators

Method: GET

This API allows you to get the list of transcribers and translators working on your Dotsub project.

Request Parameters

Name Description Required
limit The number of results per page. This defaults to 20. No
start The first result to return. This defaults to 0. No

Example Response

{
  "results": 1,
  "users": [
    {
      "email": "test1@dotsub.com",
      "enabled": true,
      "firstName": "Joe",
      "fullName": "Joe User",
      "lastName": "User",
      "username": "user"
    }
  ]
}

Project Transcribers/Translators Details

Path: https://dotsub.com/api/project/$projectId/transcribers/$username and https://dotsub.com/api/project/$projectId/translators/$username

Method: GET

This API allows you to get the listing of the work for a single user in your project.

Example Response

{
  "translations": [
    {
      "actors": {
        "TRANSLATOR": {
          "email": "test1@dotsub.com",
          "enabled": true,
          "firstName": "Joe",
          "fullName": "Joe User",
          "lastName": "User",
          "username": "user"
        }
      },
      "languageCode": "spa",
      "languageName": "Spanish",
      "lastModified": 1188331261138,
      "level": "human",
      "mediaExtId": "",
      "mediaLength": "3:53",
      "mediaLengthValue": 233000,
      "mediaTitle": "Sample Video One",
      "mediaUuid": "af0e8151-f78a-4168-8712-9cc6f8b9e2dc",
      "percentageComplete": 0,
      "workflowStatus": null,
      "workflowStatusLastModified": 0
    },
    {
      "actors": {
        "TRANSLATOR": {
          "email": "test1@dotsub.com",
          "enabled": true,
          "firstName": "Joe",
          "fullName": "Joe User",
          "lastName": "User",
          "username": "user"
        }
      },
      "languageCode": "ara",
      "languageName": "Arabic",
      "lastModified": 1188417661138,
      "level": "",
      "mediaExtId": "",
      "mediaLength": "3:53",
      "mediaLengthValue": 233000,
      "mediaTitle": "Sample Video One",
      "mediaUuid": "af0e8151-f78a-4168-8712-9cc6f8b9e2dc",
      "percentageComplete": 0,
      "workflowStatus": null,
      "workflowStatusLastModified": 0
    }
  ]
}

Project Users

The project user API is a feature that can be enabled on Dotsub for your project. This will allow you to only assign work to the users you have added to a given project. Users can be added to a project via the dashboard or an API call.

Add/Update Project Users

Path: https://dotsub.com/api/project/$projectId/users

Method: POST

This call adds or updates a user. If a user already exists in a project this API call will update their list of languages, appending any new values. If they do not exist in the project they will be added.

Request Parameters

Name Description Required
username The username of the user to be added to the project. Yes
language The language code the user can work in. You can append multiple languages at a time by posting the parameter more than once in a request. Yes

Example Response

{
  "status": {
    "message": "User record added to project",
    "error": false,
    "code": 200
  }
}

Remove Project User

Path: https://dotsub.com/api/project/$projectId/users

Method: DELETE

This call removes a user from a project.

Request Parameters

Name Description Required
username The username of the user to be added to the project Yes

Example Response

{
  "status": {
    "message": "User record removed from project",
    "error": false,
    "code": 200
  }
}

Listing Project Users

Path: https://dotsub.com/api/project/$projectId/users

Method: GET

This API allows you to get the list of users and languages you have added to a project.

Request Parameters

Name Description Required
limit The number of results per page. This defaults to 20. No
start The first result to return. This defaults to 0. No

Example Response

{
  "limit": 20,
  "sort": "username",
  "projectUsers": [
    {
      "languageNames": [
        "Finnish",
        "Spanish"
      ],
      "languages": [
        "fin",
        "spa"
      ],
      "user": {
        "email": "test1@dotsub.com",
        "emailUser": true,
        "firstName": "Joe",
        "fullName": "Joe User",
        "lastName": "User",
        "username": "user"
      }
    },
    {
      "languageNames": [
        "Arabic",
        "Spanish"
      ],
      "languages": [
        "ara",
        "spa"
      ],
      "user": {
        "email": "test3@dotsub.com",
        "emailUser": true,
        "firstName": "Bill",
        "fullName": "Bill User",
        "lastName": "User",
        "username": "otheruser"
      }
    }
  ],
  "results": 2,
  "start": 0,
  "dir": "DESC"
}

Order API

Dotsub's order API allows you to send caption/translation orders to Dotsub. Any video already uploaded to your account/project can be used in an order. You can also use this API check the status of historical orders.

Order Listing

Path: https://dotsub.com/api/order

Method: GET

The orders listing API will list all orders for a user.

Request Parameters

Name Description Required
limit The number of results per page. This defaults to 20. No
start The first result to return. This defaults to 0. No
sort What field to sort the results by. This defaults to 'dateCreated'. No
dir The direction to sort in (ASC or DESC). THis defaults to DESC. No
orderStatus This filters the results to orders of a single status. This can be: PENDING, IN_PROGRESS, DELIVERED, COMPLETED, CANCELED No

Example Response

{
  "limit": 20,
  "orders": [
    {
      "completionDate": 1359741601138,
      "createdBy": "user",
      "dateCreated": 1358013601138,
      "discount": 0,
      "id": "674acc50-58e0-11e2-bcfd-0800200c9a66",
      "invoiceNumber": "",
      "orderItems": [
        {
          "completionDate": 1357834261138,
          "dateCreated": 1357575060138,
          "deliveryDate": 0,
          "id": "f5bfbba0-58e3-11e2-bcfd-0800200c9a66",
          "itemType": "TranslationOrderItem",
          "language": "fin",
          "languageName": "Finnish",
          "mediaExternalIdentifier": "625719",
          "mediaId": "af0e8151-f78a-4168-8712-9cc6f8b9e2dc",
          "mediaTitle": "Dance, Monkeys, Dance by Ernie Cline",
          "orderId": "674acc50-58e0-11e2-bcfd-0800200c9a66",
          "orderNumber": "242",
          "orderStatus": "PENDING",
          "percentageComplete": 0,
          "period": null,
          "price": 0,
          "subtitleSpecification": null,
          "videoMinutes": 4
        },
        {
          "completionDate": 1357834261138,
          "dateCreated": 1357575061138,
          "deliveryDate": 0,
          "id": "f5bfbba1-58e3-11e2-bcfd-0800200c9a66",
          "itemType": "TranslationOrderItem",
          "language": "dan",
          "languageName": "Danish",
          "mediaExternalIdentifier": "625719",
          "mediaId": "af0e8151-f78a-4168-8712-9cc6f8b9e2dc",
          "mediaTitle": "Dance, Monkeys, Dance by Ernie Cline",
          "orderId": "674acc50-58e0-11e2-bcfd-0800200c9a66",
          "orderNumber": "242",
          "orderStatus": "PENDING",
          "percentageComplete": 0,
          "period": null,
          "price": 0,
          "subtitleSpecification": null,
          "videoMinutes": 4
        }
      ],
      "orderNumber": 242,
      "orderSource": null,
      "orderStatus": "PENDING",
      "price": 0,
      "projectId": "46f16bf2-84e7-11dd-8608-f3f9661facd6",
      "projectName": "Sample Project One",
      "totalItems": 2,
      "videoMinutes": 8
    }
  ],
  "sort": "dateCreated",
  "results": 1,
  "start": 0,
  "dir": "DESC"
}

Create Order

Path: https://dotsub.com/api/order

Method: POST

This call allows you to create an order.

Request Parameters

Name Description Required
items The items contained in this order. See Order Items for details Yes
useExternalIdentifier False if using Dotsub Id to identify items, set this to true if you are using your external identifier to reference videos (Default: False) Yes
notes A text field for any additional information about this order. Yes

Example Response

{
  "order": {
    "completionDate": 1359987982322,
    "createdBy": "user",
    "dateCreated": 1359469582270,
    "id": "fb54467a-08d8-4072-a5e6-8d3612559d2d",
    "orderItems": [
      {
        "completionDate": 1359555982322,
        "dateCreated": 1359469582274,
        "id": "f4d737dc-58de-499e-ba2d-6af9baae3982",
        "itemType": "TranscriptionOrderItem",
        "language": "eng",
        "languageName": "English",
        "mediaExternalIdentifier": "",
        "mediaId": "44c79590-42d9-11dd-ae16-0800200c9a66",
        "mediaTitle": "Dotsub Google Translate screencast",
        "orderId": "fb54467a-08d8-4072-a5e6-8d3612559d2d",
        "orderStatus": "PENDING",
        "videoMinutes": 2
      },
      {
        "completionDate": 1359987982322,
        "dateCreated": 1359469582275,
        "id": "3a96f239-7a1c-4992-9cc6-2f24de09e093",
        "itemType": "TranslationOrderItem",
        "language": "ger",
        "languageName": "German",
        "mediaExternalIdentifier": "",
        "mediaId": "44c79590-42d9-11dd-ae16-0800200c9a66",
        "mediaTitle": "Dotsub Google Translate screencast",
        "orderId": "fb54467a-08d8-4072-a5e6-8d3612559d2d",
        "orderStatus": "PENDING",
        "videoMinutes": 2
      }
    ],
    "orderStatus": "PENDING",
    "projectId": "",
    "projectName": "",
    "totalItems": 2,
    "videoMinutes": 4
  }
}

Order Details

Path: https://dotsub.com/api/order/$UUID

Method: GET

This call allows you to create an order.

Example Response

{
  "order": {
    "completionDate": 1359987982322,
    "createdBy": "user",
    "dateCreated": 1359469582270,
    "id": "fb54467a-08d8-4072-a5e6-8d3612559d2d",
    "orderItems": [
      {
        "completionDate": 1359555982322,
        "dateCreated": 1359469582274,
        "id": "f4d737dc-58de-499e-ba2d-6af9baae3982",
        "itemType": "TranscriptionOrderItem",
        "language": "eng",
        "languageName": "English",
        "mediaExternalIdentifier": "",
        "mediaId": "44c79590-42d9-11dd-ae16-0800200c9a66",
        "mediaTitle": "Dotsub Google Translate screencast",
        "orderId": "fb54467a-08d8-4072-a5e6-8d3612559d2d",
        "orderStatus": "PENDING",
        "videoMinutes": 2
      },
      {
        "completionDate": 1359987982322,
        "dateCreated": 1359469582275,
        "id": "3a96f239-7a1c-4992-9cc6-2f24de09e093",
        "itemType": "TranslationOrderItem",
        "language": "ger",
        "languageName": "German",
        "mediaExternalIdentifier": "",
        "mediaId": "44c79590-42d9-11dd-ae16-0800200c9a66",
        "mediaTitle": "Dotsub Google Translate screencast",
        "orderId": "fb54467a-08d8-4072-a5e6-8d3612559d2d",
        "orderStatus": "PENDING",
        "videoMinutes": 2
      }
    ],
    "orderStatus": "PENDING",
    "projectId": "",
    "projectName": "",
    "totalItems": 2,
    "videoMinutes": 4
  }
}

Cancel Order

Path: https://dotsub.com/api/order/$UUID/cancel

Method: POST

This call allows you to cancel an order. Only pending orders can be canceled from the API. To cancel orders in any other status, please contact our production team.

Example Response

{
  "status": {
    "message": "Order successfully canceled",
    "error": false,
    "code": 200
  }
}

Order Items

An order contains one or more 'Order Items'. These are the transcriptions/translations in the order. These are sent to the server in the following format

<type>,<id>,<language>

Parameters

Name Description
type The item type. Possible values are transcription, translation, review, machineTranslation, burnin and softsub.
id The ID of the video. This can be Dotsub's UUID or the user configured external identifier if useExternalIdentifier is set to true.
language This field's value can vary depending on the type of item.
Item Type Language Value
transcription Not required.
translation The language of the requested translation.
review The language of the requested professional review.
burnin The language of the burn in.
softsub Comma separated language codes to be included in the file.
machineTranslation The language of the requested machine translation.

Downloading Items

Path: https://dotsub.com/api/order/$orderId/items/$orderItemId/download

Method: GET

You can get the download URL for your order items by using the download API. This will return a redirect to the requested content. This method is supported for Caption/Translation and File items.

Parameters

Name Description
type The type of subtitle file to download. This parameter is not required and if empty defaults to 'srt'. This is only used for Transcription and Translation file items.
Format Description
srt A SRT file.
tt A DFXP/Timed Text file.
vtt A WebVTT file.
txt A text file. (no timing included)
csv A Comman Seperated Values file.

Automatic Translator Assignment

The automatic translator assignment API allows you to assign work to reputable translation resources. To have this feature enable on your Dotsub account please contact your account manager.

The settings that define a reputable user can be found under 'Project Settings' → 'Auto Assign Settings'. There are two types of configuration 'Simple' and 'Advanced'. Simple configuration takes into account both translations and revisions, advanced configuration allows you to configure these independently.

Simple Auto Assign Configuration

The field 'Required Items' denotes how many completed items a use must have to be considered reputable. 'Maximum Items' allow you to set a limit on the number of uncompleted items a user has.

Advanced Auto Assign Configuration

The field 'Translations Required' denotes how many completed translations a use must have to be considered reputable. 'Maximum Translations' allow you to set a limit on the number of uncompleted translations a user has. The field 'Revisions Required' denotes how many completed revisions a use must have to be considered reputable. 'Maximum Revisions' allow you to set a limit on the number of uncompleted revisions a user has.

Assignment API

Path: https://dotsub.com/api/media/$UUID/autoAssign

Method: GET

Name Description Required
language The language to assign this user Yes
username The username of the user this work will be assigned to. Yes
role The role to assign the user. Possible Values:
"TRANSLATOR": Assign this user as a translator
"TRANSCRIBER": Assign this user as the transcriber
"REVISOR": Assign this user as a revisor
Yes

Example Response

{
  "status": {
    "message": "User successfully assigned",
    "error": false,
    "code": 200
  }
}

Un-Assignment API

Path: https://dotsub.com/api/media/$UUID/unassign

Method: GET

A user can be un-assigned to a language/role only if the current media workflow status is set to "ASSIGNED".

Name Description Required
language The language for which we want to remove the assignment. Yes
role The role for which we want to remove the assignment. Possible Values:
"TRANSLATOR"
"TRANSCRIBER"
"REVISOR"
Yes

Example Response

{
  "status": {
    "message": "User successfully unassigned",
    "error": false,
    "code": 200
  }
}

Translation Offers

Translation offers allow you to have users volunteer to complete translations. These offers appear in the project dashboard under 'Translation Offers'. Videos must me public to use this API. Public but not 'publicly listed' listed videos can also use this API.

Note: This API does not return JSON.

This API allows you to construct a URL to volunteer for a translation or revision. When a user access this URL, they will be asked to log into Dotsub. If you do not include a redirect location they will be shown a thankyou page on Dotsub. If you do provide a redirect URL the user will be sent to this page on completion.

Translation Offer API

Path: https://dotsub.com/offer/$UUID/$languageCode/$type or https://dotsub.com/offer/user/$externalIdentifier/$languageCode/$type

Method: GET

Name Description Required
language The language this user is offering to translate into. Yes
type The type of offer this is. Possible Values:
"TRANSLATOR": A offer to translate a video.
"REVISOR": An offer to revise a video.
Yes
location A redirect location for when a user has completed there offer request. This must be URL encoded. No

Ping Notifications

Dotsub can ping you when the state of a media's transcription/translation changes or when an order has changed status. This allows you to instantly know when changes have been made. This feature is available to our enterprise users.

Configuring Ping Addresses

Ping addresses are configured per Project under 'Project Settings' → 'Ping API Settings'. The address should be a location on your system where Dotsub and issue a HTTP Post. The media ping can contain the UUID of a media or your configured external identifier. Some example ping addresses:

http://yoursite.com/callback
http://yoursite.com/callback/${media.id} http://yoursite.com/callback/${media.externalIdentifier}

Similarly, the order ping URL can contain the Id of the order: http://yoursite.com/callback/${order.id}

Media Ping

The media ping request will be sent to the configured URL as a HTTP Post. This contains information on what media and what state change has taken place.

Media Ping Types

Name Description
TRANSLATION_ASSIGNED This ping is sent when a translation has a translator assigned.
TRANSLATION_TRANSLATED This ping is sent when a translator marks a translation translated.
TRANSLATION_REVISOR_ASSIGNED This ping is sent when a revisor is assigned and the translation is ready to be reviewed.
TRANSLATION_REVISED This ping is sent when a revisor marks a translation revised.
TRANSLATION_PUBLISHED This ping is sent when an manager marks a translation published.
TRANSLATION_UNPUBLISHED This ping is sent when an manager un-publishes a translation.
TRANSLATION_REFRESH The translation has been updated but the metadata has changed.
TRANSCRIPTION_ASSIGNED This ping is sent when a transcriber is assigned to a video.
TRANSCRIPTION_TRANSCRIBED This ping is sent when a transcriber marks a transcription transcribed.
TRANSCRIPTION_REVISOR_ASSIGNED This ping is sent when a revisor is assigned to a transcription and it is ready to be reviewed.
TRANSCRIPTION_REVISED This ping is sent when a revisor marks a transcription revised.
TRANSCRIPTION_PUBLISHED This ping is sent when a transcription is published by a manager.
TRANSCRIPTION_UNPUBLISHED This ping is sent when a transcription is un-published by a manager.
TRANSCRIPTION_REFRESH The transcription has been updated but the workflow status has not been changed.
VIDEO_CONVERSION_FINISHED The video has been converted and is now playable.
VIDEO_CONVERSION_STARTED The video is now being processed by the system.
VIDEO_CONVERSION_FAILED The video could not be processed but the system.

Posted Media Fields

Name Description
uuid The internal identifier used by Dotsub
externalIdentifier The external identifier configured on the media
language The language which has changed state
state The ping type being sent. See 'Ping Types' for a listing of possible values.

Order Ping

The order ping request will be sent to the configured URL as a HTTP Post. This contains information on what order or order item and what state change has taken place.

Order Ping Types

Name Description
PENDING This ping is sent when an order is set to 'pending'
IN_PROGRESS This ping is sent when an order is set to 'in progress'
DELIVERED This ping is sent when the order is ready to be reviewed by the client.
COMPLETED This ping is sent when your order has been completed.
CANCELED This ping is sent when your order has been canceled.
ORDER_UPDATE This ping is sent when the completion date of your order has changed.
ITEM_PENDING This ping is sent when an order item is set to 'pending'
ITEM_IN_PROGRESS This ping is sent when an order item is set to 'in progress'
ITEM_DELIVERED This ping is sent when the item is ready to be reviewed by the client.
ITEM_COMPLETE This ping is sent when an order item has been completed.
ITEM_CANCELED This ping is sent when an order item has been canceled.
ITEM_UPDATE This ping is sent when the completion date of your item has changed.

Posted Order Fields

Name Description
orderId The Id of the Dotsub order.
itemId The Id of the order item updated. Only included for order item pings.
language The language which has changed state. Only included for order item pings

Language

Language information is returned via the Language API and in parts of the Media API. Below is a listing of the fields that can be part of the reply.

Name Description
direction The writing direction of the language. This can be 'rtl' or 'ltr'. 'rtl' denotes language written right to left, while 'ltr' denotes a language written left to right.
languageName The name of the language localized in English.
languageNameLocalized The name of the language in its native tongue. (ex: Español, Français)
iso2Code The ISO-693-2 code for this language on Dotsub.
iso3Code The ISO-693-3 code for this language on Dotsub.
legacyCodes A listing of language codes used by legacy integrations with Dotsub (before 2008).

Media

Media information is returned via the Media API, Project API and is contained in the Media Ping callbacks. Below is a listing of the fields that can be part of the reply.

Name Description
uuid The Dotsub unique identifier (ID) of this video.
title The title of this video.
description A description of this video. This can not be more than 800 characters.
type The type of video. This can be LocalMedia which are files uploaded to Dotsub or YouTubeMedia which are videos stored on YouTube but subtitled on Dotsub.
language The source language of the video. This is the 3 letter ISO code that can be found using the languages API call.
license The license of this video. Please see 'License Return' for field descriptions
genre The genre of this video.
producer The producer of this video.
director The director of this video.
isPublic This value determines if the video is publicly listed on Dotsub. This value defaults to false.
externalIdentifier The external ID of this video.
numberOfViews The number of view this video has.
numberOfLanguages The number languages this video is in.
numberOfTranslations The number translations this video has.
languages Information on the languages available for a video. See Media Language info for more detail.
workflowStatus The current status of a video. This can be NEW, PROCESSING, PROCESSING_FAILED or READY.
transcriptionStatus The current status of a video. This can be NEW, COMPLETED.
duration The runtime of the video in milliseconds.
dateCreated The time and date this video was created. This is represented as milliseconds since the epoch.
lastModified The time and date this video was last changed. This is represented as milliseconds since the epoch.
transcriptionCompletion The estimated completion of a videos transcription.
user The username of the user that posted this video.
displayURI The URI of the page that displays this video on Dotsub.
screenshotURI A URI that returns the videos thumbmail preview.
translateURIPattern The URI for translation interface. Appending the language code at the end of this will load a translation interface

Media Language

Media language information is returned via the Media API. It is a nested property of the media object.

Name Description
languageCode The Dotsub language code of this language.
direction The writing direction of the language. This can be 'rtl' or 'ltr'. 'rtl' denotes language written right to left, while 'ltr' denotes a language written left to right.
languageName The name of the language localized in English.
languageNameLocalized The name of the language in it's native tongue. (ex: Español, Français)
title The title of this video in this language.
description A description of this video in this language
dateCreated The time and date this video was created. This is represented as milliseconds since the epoch.
lastModified The time and date this video was last changed. This is represented as milliseconds since the epoch.
workflowStatusLastModified The time and date this videos workflowStatus was changed. This is represented as milliseconds since the epoch.
workflowStatus The work status of a language. This can be one of: NONE, ASSIGNED, TRANSLATED, TRANSCRIBED, REVISED, PUBLISHED. This is only available to enterprise clients.
percentageComplete How complete a given translation is.
actors The list of people working on this language. This returns a map of usernames.
level The quality level of a given item. This is only available to enterprise clients.
properties Legacy property. No longer used but still returned for existing integrations

Caption

Captions are returned by the captions API. Captions are always returned as a JSON array of caption items.

Name Description
content The text of a given caption
startTime The start time in milliseconds when this caption should begin displaying.
duration The duration of this caption in milliseconds.
startOfParagraph Denote if this caption is the start of a paragraph.

License

Licenses are returned by the License API and as part of the media object.

Name Description
id The unique identifier of a license.
name The name of a given license
description The description of a liense.
active If this license can still be used on Dotsub.
licenseVersion The version of a given license
url A URL where you can read more information about this license.

Project

Project are returned by the Project API. They are containers that hold a group of media.

Name Description
id The unique identifier of a project.
title The title of a project.

Order

Orders are returned by the Order API. These contain information on the content you have ordered from Dotsub.

Name Description
id The unique identifier of the order.
orderNumber The numerical order number of this order.
createdBy The username of the user who created this order.
dateCreated The time and date this order was created. This is represented as milliseconds since the epoch.
completionDate The time and date the order is expected to be completed. In the case of a completed order, this is the time and date it was completed. This is represented as milliseconds since the epoch.
orderItems The items contained in this order. Please see 'Order Items' for details
invoiceNumber For enterprise clients only. This is the Dotsub invoice number this order was billed on.
orderStatus The current status of an order: PENDING, IN_PROGRESS, DELIVERED, COMPLETED, CANCELED
orderSource How this order was added to Dotsub this can be any of the following: E_COMMERCE, SELF_SERVE, SYSTEM, API, or ADMIN.
projectId The ID of the project for this order.
projectName The display name of the project for this order
totalItems The number of items in this order
videoMinutes The total video minutes of captioing/translation in this order. Note: File and Machine Translations to do not count towards this total.
price The cost of this order.

Order Items

Orders items are returned by the Order API. This is a nested property of the order object.

Name Description
id The unique identifier of the order item.
orderNumber The numerical order number that contains this order item.
dateCreated The time and date this order item was created. This is represented as milliseconds since the epoch.
completionDate The time and date the order item is expected to be completed. In the case of a completed order, this is the time and date it was completed. This is represented as milliseconds since the epoch.
deliveryDate The time and date the order was delivered for review. This is represented as milliseconds since the epoch.
orderStatus The current status of an order item: PENDING, IN_PROGRESS, DELIVERED, COMPLETED, CANCELED
mediaId The ID of the media of this order item.
mediaTitle The title of the media of this order item.
mediaExternalIdentifier The external identifier of the media of this order item.
language The language code of this order item
languageName The language name for display of this order item
videoMinutes The total video minutes of captioning/translation for this item. Note: File and Machine Translations will have a value of zero.
price The cost of this order item.