{"_id":"54afb7180cf42a0b001d5bf4","project":"54ad6c769219922100751763","title":"Getting Started","type":"basic","excerpt":"","hidden":false,"githubsync":"","sync_unique":"","__v":37,"body":"The Unbabel API allows you to translate large volumes of content. \nThis high scalability is achieved by our unique blend of machine-translation and human editors (our community of translators).\n\nThe following diagram illustrates Unbabel's translation process:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/7375743-unbabel-translation-pipeline.png\",\n        \"unbabel-translation-pipeline.png\",\n        3280,\n        1336,\n        \"#3c44d4\"\n      ]\n    }\n  ]\n}\n[/block]\nIt's important to understand that each translation request involves human processing. For this reason, all translation outputs are asynchronous.\n[block:api-header]\n{\n  \"title\": \"Brand\"\n}\n[/block]\nAt Unbabel we know that some customers need to **manage multiple brands** (or products and services), so we’ve made it easy to manage these under one Unbabel account.\n\nAll Unbabel accounts will now have a default **Brand**, with the ability to add more. Each Brand can have its own Tones, Instructions and Glossaries on a **per language** basis.\n\nIf you have multiple Brands and request a translation without specifying which one to use, then we will use the default Brand, so please make sure you select the correct one.\n\n**PLEASE NOTE:** Currently, Brands can only be configured by our Customer Success team. Please email them at **[[email protected]](mailto:[email protected])** for more information.ore information.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Tone, Topics and Translation Instructions\"\n}\n[/block]\nTo help Unbabel Editors translate your content in the best possible way, each translation request should have as much context as possible. This context is set by filling-in the following fields of each request:\n\n* **tone** that Unbabel Editors should take into account when working on the translation, you can select one of the following: \"Informal\", \"Formal\"\n\n* **topics** to help Unbabel choose the more appropriate Editors for your type of content, examples are \"travel\", \"technology\" or \"sports\" \n\n* **instructions** to be shown to Editors while they are working on your translation, examples are \"This is a product description for an e-commerce website\", \"This is a customer support ticket for a travel website\" or \"Please open www.example.com for reference\"\n\n**It's very important** that you provide as much of this information as possible on each translation request.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Glossary and Style Guide\"\n}\n[/block]\nAre there any terms, like brands or product features, that should not be translated? Should the communication be formal or informal? For this reason, each Unbabel account has associated one or more **Brands**, where at least one of them will be checked as default and each brand has Glossary.\n\nDepending on your type of content, our Customer Success Team may ask you for sample content or references that can be used to speed up the creation of the Glossary and Style Guide.\n\nPlease note that **translation requests done before this onboarding process** may result in the wrong translation of brand or product terms. Our team at **[[email protected]](mailto:[email protected])** will help on this process.","link_external":false,"link_url":"","parentDoc":null,"slug":"getting-integrated","updates":[],"user":"54ad6c239219922100751762","category":"54afb7170cf42a0b001d5bf1","order":0,"version":"54afb7160cf42a0b001d5bf0","api":{"params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"code":"{}","name":"","status":400,"language":"json"}]},"settings":"","url":"","auth":"required"},"createdAt":"2015-01-07T17:27:19.700Z","isReference":false,"next":{"description":"","pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

Getting Started


The Unbabel API allows you to translate large volumes of content. This high scalability is achieved by our unique blend of machine-translation and human editors (our community of translators). The following diagram illustrates Unbabel's translation process: [block:image] { "images": [ { "image": [ "https://files.readme.io/7375743-unbabel-translation-pipeline.png", "unbabel-translation-pipeline.png", 3280, 1336, "#3c44d4" ] } ] } [/block] It's important to understand that each translation request involves human processing. For this reason, all translation outputs are asynchronous. [block:api-header] { "title": "Brand" } [/block] At Unbabel we know that some customers need to **manage multiple brands** (or products and services), so we’ve made it easy to manage these under one Unbabel account. All Unbabel accounts will now have a default **Brand**, with the ability to add more. Each Brand can have its own Tones, Instructions and Glossaries on a **per language** basis. If you have multiple Brands and request a translation without specifying which one to use, then we will use the default Brand, so please make sure you select the correct one. **PLEASE NOTE:** Currently, Brands can only be configured by our Customer Success team. Please email them at **[[email protected]](mailto:[email protected])** for more information.ore information. [block:api-header] { "type": "basic", "title": "Tone, Topics and Translation Instructions" } [/block] To help Unbabel Editors translate your content in the best possible way, each translation request should have as much context as possible. This context is set by filling-in the following fields of each request: * **tone** that Unbabel Editors should take into account when working on the translation, you can select one of the following: "Informal", "Formal" * **topics** to help Unbabel choose the more appropriate Editors for your type of content, examples are "travel", "technology" or "sports" * **instructions** to be shown to Editors while they are working on your translation, examples are "This is a product description for an e-commerce website", "This is a customer support ticket for a travel website" or "Please open www.example.com for reference" **It's very important** that you provide as much of this information as possible on each translation request. [block:api-header] { "type": "basic", "title": "Glossary and Style Guide" } [/block] Are there any terms, like brands or product features, that should not be translated? Should the communication be formal or informal? For this reason, each Unbabel account has associated one or more **Brands**, where at least one of them will be checked as default and each brand has Glossary. Depending on your type of content, our Customer Success Team may ask you for sample content or references that can be used to speed up the creation of the Glossary and Style Guide. Please note that **translation requests done before this onboarding process** may result in the wrong translation of brand or product terms. Our team at **[[email protected]](mailto:[email protected])** will help on this process.
The Unbabel API allows you to translate large volumes of content. This high scalability is achieved by our unique blend of machine-translation and human editors (our community of translators). The following diagram illustrates Unbabel's translation process: [block:image] { "images": [ { "image": [ "https://files.readme.io/7375743-unbabel-translation-pipeline.png", "unbabel-translation-pipeline.png", 3280, 1336, "#3c44d4" ] } ] } [/block] It's important to understand that each translation request involves human processing. For this reason, all translation outputs are asynchronous. [block:api-header] { "title": "Brand" } [/block] At Unbabel we know that some customers need to **manage multiple brands** (or products and services), so we’ve made it easy to manage these under one Unbabel account. All Unbabel accounts will now have a default **Brand**, with the ability to add more. Each Brand can have its own Tones, Instructions and Glossaries on a **per language** basis. If you have multiple Brands and request a translation without specifying which one to use, then we will use the default Brand, so please make sure you select the correct one. **PLEASE NOTE:** Currently, Brands can only be configured by our Customer Success team. Please email them at **[[email protected]](mailto:[email protected])** for more information.ore information. [block:api-header] { "type": "basic", "title": "Tone, Topics and Translation Instructions" } [/block] To help Unbabel Editors translate your content in the best possible way, each translation request should have as much context as possible. This context is set by filling-in the following fields of each request: * **tone** that Unbabel Editors should take into account when working on the translation, you can select one of the following: "Informal", "Formal" * **topics** to help Unbabel choose the more appropriate Editors for your type of content, examples are "travel", "technology" or "sports" * **instructions** to be shown to Editors while they are working on your translation, examples are "This is a product description for an e-commerce website", "This is a customer support ticket for a travel website" or "Please open www.example.com for reference" **It's very important** that you provide as much of this information as possible on each translation request. [block:api-header] { "type": "basic", "title": "Glossary and Style Guide" } [/block] Are there any terms, like brands or product features, that should not be translated? Should the communication be formal or informal? For this reason, each Unbabel account has associated one or more **Brands**, where at least one of them will be checked as default and each brand has Glossary. Depending on your type of content, our Customer Success Team may ask you for sample content or references that can be used to speed up the creation of the Glossary and Style Guide. Please note that **translation requests done before this onboarding process** may result in the wrong translation of brand or product terms. Our team at **[[email protected]](mailto:[email protected])** will help on this process.
{"_id":"566ed43e95fe82170035ed6d","createdAt":"2015-12-14T14:37:50.599Z","project":"54ad6c769219922100751763","slug":"2-use-cases","sync_unique":"","title":"Use Cases","user":"5669472c08f90021008e887d","api":{"auth":"required","params":[],"results":{"codes":[{"language":"json","code":"{}","name":"","status":200},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"githubsync":"","order":1,"excerpt":"","hidden":false,"link_external":false,"parentDoc":null,"version":"54afb7160cf42a0b001d5bf0","__v":16,"body":"The following table summarises common use cases of the Unbabel API and the corresponding formats that should be set on the `text_format` field.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Use Case\",\n    \"h-1\": \"Format\",\n    \"0-0\": \"Product Descriptions\",\n    \"0-1\": \"`xliff`\",\n    \"1-0\": \"User Generated Content\",\n    \"1-1\": \"`text` or `xliff`\",\n    \"2-0\": \"Subtitles\",\n    \"2-1\": \"`srt`\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Product Descriptions\"\n}\n[/block]\nOne of the best use cases for the Unbabel API is maintaining multilingual versions of product descriptions. In this way you'll automatically reach new markets in a seamless way.\n\nThis type of content is typically made of multiple parts like:\n* product title\n* product summary\n* product description\n\nTo maintain consistency in the translation, these parts should be grouped using the [XLIFF format](http://docs.oasis-open.org/xliff/xliff-core/xliff-core.html). For example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?xml version='1.0' encoding='utf-8'?>\\n<xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'>\\n  <file original='' source-language='en' datatype='TEXT'>\\n    <header/>\\n    <body>\\n      <trans-unit id='title'>\\n        <source>Product Title</source>\\n      </trans-unit>\\n      <trans-unit id='summary'>\\n        <source>The product summary</source>\\n      </trans-unit>\\n      <trans-unit id='description'>\\n        <source>The product description</source>\\n      </trans-unit>\\n    </body>\\n  </file>\\n</xliff>\",\n      \"language\": \"xml\",\n      \"name\": \"Product Description XLIFF\"\n    }\n  ]\n}\n[/block]\nThis XLIFF should then be used to set the text field of the translation request. Here's an example of how the complete request could look:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"text\\\" : \\\"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='title'><source>Product Title</source></trans-unit><trans-unit id='description'><source>The product summary</source></trans-unit><trans-unit id='description'><source>The product description</source></trans-unit></body></file></xliff>\\\",\\n  \\\"source_language\\\" : \\\"en\\\",\\n  \\\"target_language\\\" : \\\"pt\\\",\\n  \\\"text_format\\\" : \\\"xliff\\\"\\n  \\\"uid\\\" : \\\"1\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Product Description Translation Request\"\n    }\n  ]\n}\n[/block]\n**It's very important** that the field `text_format` is set to `xliff`.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"User Generated Content\"\n}\n[/block]\nUser Generated Content is a perfect fit for Unbabel's scalable translation API, extending its global reach and bringing new audience. In this case, the `text_format` field should be set to `xliff` or `text`, depending if the content has multiple parts or just one. Here's an example request for the latter\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"text\\\" : \\\"This text was written by a user\\\",\\n  \\\"source_language\\\" : \\\"en\\\",\\n  \\\"target_language\\\" : \\\"pt\\\",\\n  \\\"text_format\\\" : \\\"text\\\"\\n  \\\"uid\\\" : \\\"1\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"User Generated Content Translation Request\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Subtitles\"\n}\n[/block]\nThe Unbabel API also supports the [SRT format](http://matroska.org/technical/specs/subtitles/srt.html) so that you can easily automate the translation of subtitles. In this case, the `text_format` field should be set to `srt`. Here's an example of a request to translate 2 subtitles\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"text\\\" : \\\"1\\\\n00:02:17,440 --> 00:02:20,375\\\\nWhat is the use of a book\\\\nwithout pictures or conversation?\\\\n\\\\n2\\\\n00:02:20,476 --> 00:02:22,501\\\\nOh dear! Oh dear! I shall be late!\\\",\\n  \\\"source_language\\\" : \\\"en\\\",,\\n  \\\"target_language\\\" : \\\"pt\\\",\\n  \\\"text_format\\\" : \\\"srt\\\"\\n  \\\"uid\\\" : \\\"1\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Subtitles Translation Request\"\n    }\n  ]\n}\n[/block]","updates":[],"category":"54afb7170cf42a0b001d5bf1","link_url":"","type":"basic","isReference":false,"next":{"description":"","pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

Use Cases


The following table summarises common use cases of the Unbabel API and the corresponding formats that should be set on the `text_format` field. [block:parameters] { "data": { "h-0": "Use Case", "h-1": "Format", "0-0": "Product Descriptions", "0-1": "`xliff`", "1-0": "User Generated Content", "1-1": "`text` or `xliff`", "2-0": "Subtitles", "2-1": "`srt`" }, "cols": 2, "rows": 3 } [/block] [block:api-header] { "type": "basic", "title": "Product Descriptions" } [/block] One of the best use cases for the Unbabel API is maintaining multilingual versions of product descriptions. In this way you'll automatically reach new markets in a seamless way. This type of content is typically made of multiple parts like: * product title * product summary * product description To maintain consistency in the translation, these parts should be grouped using the [XLIFF format](http://docs.oasis-open.org/xliff/xliff-core/xliff-core.html). For example: [block:code] { "codes": [ { "code": "<?xml version='1.0' encoding='utf-8'?>\n<xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'>\n <file original='' source-language='en' datatype='TEXT'>\n <header/>\n <body>\n <trans-unit id='title'>\n <source>Product Title</source>\n </trans-unit>\n <trans-unit id='summary'>\n <source>The product summary</source>\n </trans-unit>\n <trans-unit id='description'>\n <source>The product description</source>\n </trans-unit>\n </body>\n </file>\n</xliff>", "language": "xml", "name": "Product Description XLIFF" } ] } [/block] This XLIFF should then be used to set the text field of the translation request. Here's an example of how the complete request could look: [block:code] { "codes": [ { "code": "{\n \"text\" : \"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='title'><source>Product Title</source></trans-unit><trans-unit id='description'><source>The product summary</source></trans-unit><trans-unit id='description'><source>The product description</source></trans-unit></body></file></xliff>\",\n \"source_language\" : \"en\",\n \"target_language\" : \"pt\",\n \"text_format\" : \"xliff\"\n \"uid\" : \"1\"\n}", "language": "json", "name": "Product Description Translation Request" } ] } [/block] **It's very important** that the field `text_format` is set to `xliff`. [block:api-header] { "type": "basic", "title": "User Generated Content" } [/block] User Generated Content is a perfect fit for Unbabel's scalable translation API, extending its global reach and bringing new audience. In this case, the `text_format` field should be set to `xliff` or `text`, depending if the content has multiple parts or just one. Here's an example request for the latter [block:code] { "codes": [ { "code": "{\n \"text\" : \"This text was written by a user\",\n \"source_language\" : \"en\",\n \"target_language\" : \"pt\",\n \"text_format\" : \"text\"\n \"uid\" : \"1\"\n}", "language": "json", "name": "User Generated Content Translation Request" } ] } [/block] [block:api-header] { "type": "basic", "title": "Subtitles" } [/block] The Unbabel API also supports the [SRT format](http://matroska.org/technical/specs/subtitles/srt.html) so that you can easily automate the translation of subtitles. In this case, the `text_format` field should be set to `srt`. Here's an example of a request to translate 2 subtitles [block:code] { "codes": [ { "code": "{\n \"text\" : \"1\\n00:02:17,440 --> 00:02:20,375\\nWhat is the use of a book\\nwithout pictures or conversation?\\n\\n2\\n00:02:20,476 --> 00:02:22,501\\nOh dear! Oh dear! I shall be late!\",\n \"source_language\" : \"en\",,\n \"target_language\" : \"pt\",\n \"text_format\" : \"srt\"\n \"uid\" : \"1\"\n}", "language": "json", "name": "Subtitles Translation Request" } ] } [/block]
The following table summarises common use cases of the Unbabel API and the corresponding formats that should be set on the `text_format` field. [block:parameters] { "data": { "h-0": "Use Case", "h-1": "Format", "0-0": "Product Descriptions", "0-1": "`xliff`", "1-0": "User Generated Content", "1-1": "`text` or `xliff`", "2-0": "Subtitles", "2-1": "`srt`" }, "cols": 2, "rows": 3 } [/block] [block:api-header] { "type": "basic", "title": "Product Descriptions" } [/block] One of the best use cases for the Unbabel API is maintaining multilingual versions of product descriptions. In this way you'll automatically reach new markets in a seamless way. This type of content is typically made of multiple parts like: * product title * product summary * product description To maintain consistency in the translation, these parts should be grouped using the [XLIFF format](http://docs.oasis-open.org/xliff/xliff-core/xliff-core.html). For example: [block:code] { "codes": [ { "code": "<?xml version='1.0' encoding='utf-8'?>\n<xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'>\n <file original='' source-language='en' datatype='TEXT'>\n <header/>\n <body>\n <trans-unit id='title'>\n <source>Product Title</source>\n </trans-unit>\n <trans-unit id='summary'>\n <source>The product summary</source>\n </trans-unit>\n <trans-unit id='description'>\n <source>The product description</source>\n </trans-unit>\n </body>\n </file>\n</xliff>", "language": "xml", "name": "Product Description XLIFF" } ] } [/block] This XLIFF should then be used to set the text field of the translation request. Here's an example of how the complete request could look: [block:code] { "codes": [ { "code": "{\n \"text\" : \"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='title'><source>Product Title</source></trans-unit><trans-unit id='description'><source>The product summary</source></trans-unit><trans-unit id='description'><source>The product description</source></trans-unit></body></file></xliff>\",\n \"source_language\" : \"en\",\n \"target_language\" : \"pt\",\n \"text_format\" : \"xliff\"\n \"uid\" : \"1\"\n}", "language": "json", "name": "Product Description Translation Request" } ] } [/block] **It's very important** that the field `text_format` is set to `xliff`. [block:api-header] { "type": "basic", "title": "User Generated Content" } [/block] User Generated Content is a perfect fit for Unbabel's scalable translation API, extending its global reach and bringing new audience. In this case, the `text_format` field should be set to `xliff` or `text`, depending if the content has multiple parts or just one. Here's an example request for the latter [block:code] { "codes": [ { "code": "{\n \"text\" : \"This text was written by a user\",\n \"source_language\" : \"en\",\n \"target_language\" : \"pt\",\n \"text_format\" : \"text\"\n \"uid\" : \"1\"\n}", "language": "json", "name": "User Generated Content Translation Request" } ] } [/block] [block:api-header] { "type": "basic", "title": "Subtitles" } [/block] The Unbabel API also supports the [SRT format](http://matroska.org/technical/specs/subtitles/srt.html) so that you can easily automate the translation of subtitles. In this case, the `text_format` field should be set to `srt`. Here's an example of a request to translate 2 subtitles [block:code] { "codes": [ { "code": "{\n \"text\" : \"1\\n00:02:17,440 --> 00:02:20,375\\nWhat is the use of a book\\nwithout pictures or conversation?\\n\\n2\\n00:02:20,476 --> 00:02:22,501\\nOh dear! Oh dear! I shall be late!\",\n \"source_language\" : \"en\",,\n \"target_language\" : \"pt\",\n \"text_format\" : \"srt\"\n \"uid\" : \"1\"\n}", "language": "json", "name": "Subtitles Translation Request" } ] } [/block]
{"_id":"566edcaa7ffa002300c3cafe","isReference":false,"slug":"tutorial","link_external":false,"order":2,"user":"5669472c08f90021008e887d","__v":33,"createdAt":"2015-12-14T15:13:46.625Z","excerpt":"","githubsync":"","hidden":false,"category":"54afb7170cf42a0b001d5bf1","parentDoc":null,"project":"54ad6c769219922100751763","title":"Tutorials","version":"54afb7160cf42a0b001d5bf0","type":"basic","updates":[],"api":{"params":[],"results":{"codes":[{"name":"","status":200,"language":"json","code":"{}"},{"language":"json","code":"{}","name":"","status":400}]},"settings":"","url":"","auth":"required"},"body":"You can try out the Unbabel API for free using its sandbox. In sandbox mode, each request is processed automatically using machine translation with no involvement of Unbabel Editors (otherwise, we would have to pay for their work time). To simulate production behavior, we hold the translation for 2 minutes and then post it to the defined callback endpoint.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Setting Up a Sandbox Account\"\n}\n[/block]\nThe first step to setup your sandbox is to request a Sandbox API Key by submitting [this form](https://unbabel.com/request-demo/).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Translating \\\"Hello, World!\\\"\"\n}\n[/block]\nOnce you have setup your sandbox, requesting a translation is very simple. You just need to do a HTTP request to the `translation` endpoint. Using a tool like cURL (learn more at [http://curl.haxx.se](http://curl.haxx.se)) is super easy. If this tool is not familiar to you, you can read a short intro about it with examples at [http://blogs.plexibus.com/2009/01/15/rest-esting-with-curl](http://blogs.plexibus.com/2009/01/15/rest-esting-with-curl). An alternative to cURL is [POSTMAN](https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en), an easy-to-use Chrome extension for making HTTP requests. You can also use one of our SDKs described in the SDKs sections.\n\nUsing cURL, translating \"Hello, world!\" would be done by executing:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: ApiKey username:apikey\\\" -H \\\"Content-Type: application/json\\\" -X POST https://sandbox.unbabel.com/tapi/v2/translation/ -d '{\\\"text\\\" : \\\"Hello, world!\\\", \\\"source_language\\\" : \\\"en\\\", \\\"target_language\\\" : \\\"pt\\\", \\\"text_format\\\" : \\\"text\\\"}'\",\n      \"language\": \"shell\",\n      \"name\": \"Request\"\n    }\n  ]\n}\n[/block]\nIn response you would have:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"balance\\\": 99943.0,\\n  \\\"client\\\": \\\"username\\\",\\n  \\\"price\\\": 6.0,\\n  \\\"source_language\\\": \\\"en\\\",\\n  \\\"status\\\": \\\"new\\\",\\n  \\\"target_language\\\": \\\"pt\\\",\\n  \\\"text\\\": \\\"Hello, world!\\\",\\n  \\\"text_format\\\": \\\"text\\\",\\n  \\\"uid\\\": \\\"ac1a53a264\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nTo check the translation status you would use the returned job `uid` and do:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: ApiKey username:apikey\\\" -H \\\"Content-Type: application/json\\\" -X GET https://sandbox.unbabel.com/tapi/v2/translation/ac1a53a264/\",\n      \"language\": \"shell\",\n      \"name\": \"Request\"\n    }\n  ]\n}\n[/block]\nPlease note that the \"/\" after the job uid is mandatory. Depending on the elapsed time between the two requests, you could get something like:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"balance\\\": 99937.0,\\n  \\\"client\\\": \\\"username\\\",\\n  \\\"price\\\": 6.0,\\n  \\\"source_language\\\": \\\"en\\\",\\n  \\\"status\\\": \\\"translating\\\",\\n  \\\"target_language\\\": \\\"pt\\\",\\n  \\\"text\\\": \\\"Hello, world!\\\",\\n  \\\"text_format\\\": \\\"text\\\",\\n  \\\"uid\\\": \\\"ac1a53a264\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response: translation in progress\"\n    }\n  ]\n}\n[/block]\nOr, immediately, the translation itself:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"balance\\\": 99937.0,\\n\\t\\\"client\\\": \\\"username\\\",\\n\\t\\\"price\\\": 6.0,\\n\\t\\\"source_language\\\": \\\"en\\\",\\n\\t\\\"status\\\": \\\"completed\\\",\\n\\t\\\"target_language\\\": \\\"pt\\\",\\n\\t\\\"text\\\": \\\"Hello, world!\\\",\\n\\t\\\"text_format\\\": \\\"text\\\",\\n\\t\\\"translated_text\\\": \\\"Olá Mundo!\\\",\\n\\t\\\"uid\\\": \\\"ac1a53a264\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response: translation completed\"\n    }\n  ]\n}\n[/block]\nThese two possible responses depend on the time the translation takes to be completed. Since this relies on human processing, it may range from a few minutes to hours.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Translating a Product Description\"\n}\n[/block]\nA product description is typically made of multiple parts like: product name, summary and description.  As described in [Use Cases](doc:2-use-cases), you should always use the XLIFF format for this kind of content, sending all content parts in a single translation request. Splitting content parts in different translation requests could lead to inconsistencies in the translation.\n\nLet's use as an example the following product:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Product Name\",\n    \"h-1\": \"Product Description\",\n    \"0-0\": \"Alice In Wonderland teapot\",\n    \"0-1\": \"Beautiful porcelain tea pot with Alice and the Cheshire cat\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\nIn XLIFF format this product could be represented like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?xml version='1.0' encoding='utf-8'?>\\n<xliff xmlns=\\\"urn:oasis:names:tc:xliff:document:1.2\\\" version=\\\"1.2\\\">\\n  <file original=\\\"\\\" source-language=\\\"en\\\" datatype=\\\"TEXT\\\">\\n    <header/>\\n    <body>\\n      <trans-unit id=\\\"name\\\" >\\n        <source>Alice In Wonderland teapot</source>\\n      </trans-unit>\\n      <trans-unit id=\\\"description\\\">\\n        <source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source>\\n      </trans-unit>\\n    </body>\\n  </file>\\n</xliff>\",\n      \"language\": \"xml\",\n      \"name\": \"Product Description XLIFF\"\n    }\n  ]\n}\n[/block]\nUsing cURL, you can translate this product description by doing:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: ApiKey username:apikey\\\" -H \\\"Content-Type: application/json\\\" -X POST https://sandbox.unbabel.com/tapi/v2/translation/ -d \\\"{\\\\\\\"text\\\\\\\" : \\\\\\\"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='name'><source>Alice In Wonderland teapot</source></trans-unit><trans-unit id='description'><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source></trans-unit></body></file></xliff>\\\\\\\", \\\\\\\"source_language\\\\\\\" : \\\\\\\"en\\\\\\\", \\\\\\\"target_language\\\\\\\" : \\\\\\\"pt\\\\\\\", \\\\\\\"text_format\\\\\\\" : \\\\\\\"xliff\\\\\\\"}\\\"\",\n      \"language\": \"shell\",\n      \"name\": \"Request\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"balance\\\": 99922.0,\\n  \\\"client\\\": \\\"username\\\",\\n  \\\"price\\\": 42.0,\\n  \\\"source_language\\\": \\\"en\\\",\\n  \\\"status\\\": \\\"new\\\",\\n  \\\"target_language\\\": \\\"pt\\\",\\n  \\\"text_format\\\": \\\"xliff\\\",\\n  \\\"uid\\\": \\\"937faff2b5\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nTo check the translation status, you would do:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: ApiKey username:apikey\\\" -H \\\"Content-Type: application/json\\\" -X GET https://sandbox.unbabel.com/tapi/v2/translation/937faff2b5/\",\n      \"language\": \"shell\",\n      \"name\": \"Request\"\n    }\n  ]\n}\n[/block]\nIn case the translation process has finished, the response would be:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"balance\\\": 99880.0,\\n  \\\"client\\\": \\\"username\\\",\\n  \\\"price\\\": 42.0,\\n  \\\"source_language\\\": \\\"en\\\",\\n  \\\"status\\\": \\\"completed\\\",\\n  \\\"target_language\\\": \\\"pt\\\",\\n  \\\"text\\\": \\\"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='name'><source>Alice In Wonderland teapot</source></trans-unit><trans-unit id='description'><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source></trans-unit></body></file></xliff>\\\",\\n  \\\"text_format\\\": \\\"xliff\\\",\\n  \\\"translated_text\\\": \\\"<?xml version=\\\\\\\"1.0\\\\\\\" encoding=\\\\\\\"utf-8\\\\\\\"?><xliff xmlns=\\\\\\\"urn:oasis:names:tc:xliff:document:1.2\\\\\\\" version=\\\\\\\"1.2\\\\\\\"><file original=\\\\\\\"\\\\\\\" source-language=\\\\\\\"en\\\\\\\" datatype=\\\\\\\"TEXT\\\\\\\"><header/><body><trans-unit id=\\\\\\\"name\\\\\\\"><source>Alice In Wonderland teapot</source><target>Alice In Wonderland bule</target></trans-unit><trans-unit id=\\\\\\\"description\\\\\\\"><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source><target>Bule de chá de porcelana bonita com Alice e o gato de Cheshire</target></trans-unit></body></file></xliff>\\\",\\n        \\\"uid\\\": \\\"937faff2b5\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Setting Tone and Topics\"\n}\n[/block]\nAs mentioned in [Getting Started](doc:getting-integrated), it's very important that you give as much context as possible about your content. Only in this way,  Unbabel Editors will understand translation preferences like the tone that should be used (eg: informal or formal) and the type of content — translating a product description is quite different from translating user generated content. The fields `tone` and `topics` are used to associate this information with the translation request.\n\nLet's use as an example the translation of product descriptions for an e-commerce website (of crafts and technology). Using cURL, you could translate a product description giving context about it by doing:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: ApiKey username:apikey\\\" -H \\\"Content-Type: application/json\\\" -X POST https://sandbox.unbabel.com/tapi/v2/translation/ -d \\\"{\\\\\\\"text\\\\\\\" : \\\\\\\"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='name'><source>Alice In Wonderland teapot</source></trans-unit><trans-unit id='description'><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source></trans-unit></body></file></xliff>\\\\\\\", \\\\\\\"source_language\\\\\\\" : \\\\\\\"en\\\\\\\", \\\\\\\"target_language\\\\\\\" : \\\\\\\"pt\\\\\\\", \\\\\\\"text_format\\\\\\\" : \\\\\\\"xliff\\\\\\\", \\\\\\\"tone\\\\\\\" : \\\\\\\"Formal\\\\\\\", \\\\\\\"topics\\\\\\\" : [\\\\\\\"tech\\\\\\\", \\\\\\\"crafts\\\\\\\"]}\\\"\",\n      \"language\": \"shell\",\n      \"name\": \"Request\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"balance\\\": 99880.0,\\n  \\\"client\\\": \\\"pdimas\\\",\\n  \\\"price\\\": 42.0,\\n  \\\"source_language\\\": \\\"en\\\",\\n  \\\"status\\\": \\\"new\\\",\\n  \\\"target_language\\\": \\\"pt\\\",\\n  \\\"tone\\\": \\\"Formal\\\",\\n  \\\"topics\\\": [\\\"tech\\\", \\\"crafts\\\"],\\n  \\\"uid\\\": \\\"8926cbec74\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nYou can check the list of possible tones using cURL by doing:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: ApiKey username:apikey\\\" -H \\\"Content-Type: application/json\\\" -X GET https://sandbox.unbabel.com/tapi/v2/tone/\",\n      \"language\": \"shell\",\n      \"name\": \"Request\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"objects\\\": [{\\n\\t\\t\\\"tone\\\": {\\n\\t\\t\\t\\\"description\\\": \\\"Informal style\\\",\\n\\t\\t\\t\\\"name\\\": \\\"Informal\\\"\\n\\t\\t}\\n\\t}, {\\n\\t\\t\\\"tone\\\": {\\n\\t\\t\\t\\\"description\\\": \\\"Formal style\\\",\\n\\t\\t\\t\\\"name\\\": \\\"Formal\\\"\\n\\t\\t}\\n\\t}]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nAnd, to check the list of possible topics, you can do:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: ApiKey username:apikey\\\" -H \\\"Content-Type: application/json\\\" -X GET https://sandbox.unbabel.com/tapi/v2/topic/\",\n      \"language\": \"shell\",\n      \"name\": \"Request\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"objects\\\": [{\\n\\t\\t\\\"topic\\\": {\\n\\t\\t\\t\\\"name\\\": \\\"politics\\\"\\n\\t\\t}\\n\\t}, {\\n\\t\\t\\\"topic\\\": {\\n\\t\\t\\t\\\"name\\\": \\\"gossip\\\"\\n\\t\\t}\\n\\t}, {\\n\\t\\t\\\"topic\\\": {\\n\\t\\t\\t\\\"name\\\": \\\"sex & relationships\\\"\\n\\t\\t}\\n\\t}, {\\n\\t\\t\\\"topic\\\": {\\n\\t\\t\\t\\\"name\\\": \\\"crafts\\\"\\n\\t\\t}\\n\\t}, {\\n\\t\\t\\\"topic\\\": {\\n\\t\\t\\t\\\"name\\\": \\\"parenting\\\"\\n\\t\\t}\\n\\t}, {\\n\\t\\t\\\"topic\\\": {\\n\\t\\t\\t\\\"name\\\": \\\"startups\\\"\\n\\t\\t}\\n\\t}, {\\n\\t\\t\\\"topic\\\": {\\n\\t\\t\\t\\\"name\\\": \\\"tech\\\"\\n\\t\\t}\\n\\t}, {\\n\\t\\t\\\"topic\\\": {\\n\\t\\t\\t\\\"name\\\": \\\"sports\\\"\\n\\t\\t}\\n\\t}]\\nhttps://dash.readme.io/legacy/}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]","link_url":"","sync_unique":"","next":{"description":"","pages":[]},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

Tutorials


You can try out the Unbabel API for free using its sandbox. In sandbox mode, each request is processed automatically using machine translation with no involvement of Unbabel Editors (otherwise, we would have to pay for their work time). To simulate production behavior, we hold the translation for 2 minutes and then post it to the defined callback endpoint. [block:api-header] { "type": "basic", "title": "Setting Up a Sandbox Account" } [/block] The first step to setup your sandbox is to request a Sandbox API Key by submitting [this form](https://unbabel.com/request-demo/). [block:api-header] { "type": "basic", "title": "Translating \"Hello, World!\"" } [/block] Once you have setup your sandbox, requesting a translation is very simple. You just need to do a HTTP request to the `translation` endpoint. Using a tool like cURL (learn more at [http://curl.haxx.se](http://curl.haxx.se)) is super easy. If this tool is not familiar to you, you can read a short intro about it with examples at [http://blogs.plexibus.com/2009/01/15/rest-esting-with-curl](http://blogs.plexibus.com/2009/01/15/rest-esting-with-curl). An alternative to cURL is [POSTMAN](https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en), an easy-to-use Chrome extension for making HTTP requests. You can also use one of our SDKs described in the SDKs sections. Using cURL, translating "Hello, world!" would be done by executing: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X POST https://sandbox.unbabel.com/tapi/v2/translation/ -d '{\"text\" : \"Hello, world!\", \"source_language\" : \"en\", \"target_language\" : \"pt\", \"text_format\" : \"text\"}'", "language": "shell", "name": "Request" } ] } [/block] In response you would have: [block:code] { "codes": [ { "code": "{\n \"balance\": 99943.0,\n \"client\": \"username\",\n \"price\": 6.0,\n \"source_language\": \"en\",\n \"status\": \"new\",\n \"target_language\": \"pt\",\n \"text\": \"Hello, world!\",\n \"text_format\": \"text\",\n \"uid\": \"ac1a53a264\"\n}", "language": "json", "name": "Response" } ] } [/block] To check the translation status you would use the returned job `uid` and do: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X GET https://sandbox.unbabel.com/tapi/v2/translation/ac1a53a264/", "language": "shell", "name": "Request" } ] } [/block] Please note that the "/" after the job uid is mandatory. Depending on the elapsed time between the two requests, you could get something like: [block:code] { "codes": [ { "code": "{\n \"balance\": 99937.0,\n \"client\": \"username\",\n \"price\": 6.0,\n \"source_language\": \"en\",\n \"status\": \"translating\",\n \"target_language\": \"pt\",\n \"text\": \"Hello, world!\",\n \"text_format\": \"text\",\n \"uid\": \"ac1a53a264\"\n}", "language": "json", "name": "Response: translation in progress" } ] } [/block] Or, immediately, the translation itself: [block:code] { "codes": [ { "code": "{\n\t\"balance\": 99937.0,\n\t\"client\": \"username\",\n\t\"price\": 6.0,\n\t\"source_language\": \"en\",\n\t\"status\": \"completed\",\n\t\"target_language\": \"pt\",\n\t\"text\": \"Hello, world!\",\n\t\"text_format\": \"text\",\n\t\"translated_text\": \"Olá Mundo!\",\n\t\"uid\": \"ac1a53a264\"\n}", "language": "json", "name": "Response: translation completed" } ] } [/block] These two possible responses depend on the time the translation takes to be completed. Since this relies on human processing, it may range from a few minutes to hours. [block:api-header] { "type": "basic", "title": "Translating a Product Description" } [/block] A product description is typically made of multiple parts like: product name, summary and description. As described in [Use Cases](doc:2-use-cases), you should always use the XLIFF format for this kind of content, sending all content parts in a single translation request. Splitting content parts in different translation requests could lead to inconsistencies in the translation. Let's use as an example the following product: [block:parameters] { "data": { "h-0": "Product Name", "h-1": "Product Description", "0-0": "Alice In Wonderland teapot", "0-1": "Beautiful porcelain tea pot with Alice and the Cheshire cat" }, "cols": 2, "rows": 1 } [/block] In XLIFF format this product could be represented like this: [block:code] { "codes": [ { "code": "<?xml version='1.0' encoding='utf-8'?>\n<xliff xmlns=\"urn:oasis:names:tc:xliff:document:1.2\" version=\"1.2\">\n <file original=\"\" source-language=\"en\" datatype=\"TEXT\">\n <header/>\n <body>\n <trans-unit id=\"name\" >\n <source>Alice In Wonderland teapot</source>\n </trans-unit>\n <trans-unit id=\"description\">\n <source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source>\n </trans-unit>\n </body>\n </file>\n</xliff>", "language": "xml", "name": "Product Description XLIFF" } ] } [/block] Using cURL, you can translate this product description by doing: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X POST https://sandbox.unbabel.com/tapi/v2/translation/ -d \"{\\\"text\\\" : \\\"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='name'><source>Alice In Wonderland teapot</source></trans-unit><trans-unit id='description'><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source></trans-unit></body></file></xliff>\\\", \\\"source_language\\\" : \\\"en\\\", \\\"target_language\\\" : \\\"pt\\\", \\\"text_format\\\" : \\\"xliff\\\"}\"", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"balance\": 99922.0,\n \"client\": \"username\",\n \"price\": 42.0,\n \"source_language\": \"en\",\n \"status\": \"new\",\n \"target_language\": \"pt\",\n \"text_format\": \"xliff\",\n \"uid\": \"937faff2b5\"\n}", "language": "json", "name": "Response" } ] } [/block] To check the translation status, you would do: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X GET https://sandbox.unbabel.com/tapi/v2/translation/937faff2b5/", "language": "shell", "name": "Request" } ] } [/block] In case the translation process has finished, the response would be: [block:code] { "codes": [ { "code": "{\n \"balance\": 99880.0,\n \"client\": \"username\",\n \"price\": 42.0,\n \"source_language\": \"en\",\n \"status\": \"completed\",\n \"target_language\": \"pt\",\n \"text\": \"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='name'><source>Alice In Wonderland teapot</source></trans-unit><trans-unit id='description'><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source></trans-unit></body></file></xliff>\",\n \"text_format\": \"xliff\",\n \"translated_text\": \"<?xml version=\\\"1.0\\\" encoding=\\\"utf-8\\\"?><xliff xmlns=\\\"urn:oasis:names:tc:xliff:document:1.2\\\" version=\\\"1.2\\\"><file original=\\\"\\\" source-language=\\\"en\\\" datatype=\\\"TEXT\\\"><header/><body><trans-unit id=\\\"name\\\"><source>Alice In Wonderland teapot</source><target>Alice In Wonderland bule</target></trans-unit><trans-unit id=\\\"description\\\"><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source><target>Bule de chá de porcelana bonita com Alice e o gato de Cheshire</target></trans-unit></body></file></xliff>\",\n \"uid\": \"937faff2b5\"\n}", "language": "json", "name": "Response" } ] } [/block] [block:api-header] { "type": "basic", "title": "Setting Tone and Topics" } [/block] As mentioned in [Getting Started](doc:getting-integrated), it's very important that you give as much context as possible about your content. Only in this way, Unbabel Editors will understand translation preferences like the tone that should be used (eg: informal or formal) and the type of content — translating a product description is quite different from translating user generated content. The fields `tone` and `topics` are used to associate this information with the translation request. Let's use as an example the translation of product descriptions for an e-commerce website (of crafts and technology). Using cURL, you could translate a product description giving context about it by doing: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X POST https://sandbox.unbabel.com/tapi/v2/translation/ -d \"{\\\"text\\\" : \\\"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='name'><source>Alice In Wonderland teapot</source></trans-unit><trans-unit id='description'><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source></trans-unit></body></file></xliff>\\\", \\\"source_language\\\" : \\\"en\\\", \\\"target_language\\\" : \\\"pt\\\", \\\"text_format\\\" : \\\"xliff\\\", \\\"tone\\\" : \\\"Formal\\\", \\\"topics\\\" : [\\\"tech\\\", \\\"crafts\\\"]}\"", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"balance\": 99880.0,\n \"client\": \"pdimas\",\n \"price\": 42.0,\n \"source_language\": \"en\",\n \"status\": \"new\",\n \"target_language\": \"pt\",\n \"tone\": \"Formal\",\n \"topics\": [\"tech\", \"crafts\"],\n \"uid\": \"8926cbec74\"\n}", "language": "json", "name": "Response" } ] } [/block] You can check the list of possible tones using cURL by doing: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X GET https://sandbox.unbabel.com/tapi/v2/tone/", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n\t\"objects\": [{\n\t\t\"tone\": {\n\t\t\t\"description\": \"Informal style\",\n\t\t\t\"name\": \"Informal\"\n\t\t}\n\t}, {\n\t\t\"tone\": {\n\t\t\t\"description\": \"Formal style\",\n\t\t\t\"name\": \"Formal\"\n\t\t}\n\t}]\n}", "language": "json", "name": "Response" } ] } [/block] And, to check the list of possible topics, you can do: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X GET https://sandbox.unbabel.com/tapi/v2/topic/", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n\t\"objects\": [{\n\t\t\"topic\": {\n\t\t\t\"name\": \"politics\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"gossip\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"sex & relationships\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"crafts\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"parenting\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"startups\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"tech\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"sports\"\n\t\t}\n\t}]\nhttps://dash.readme.io/legacy/}", "language": "json", "name": "Response" } ] } [/block]
You can try out the Unbabel API for free using its sandbox. In sandbox mode, each request is processed automatically using machine translation with no involvement of Unbabel Editors (otherwise, we would have to pay for their work time). To simulate production behavior, we hold the translation for 2 minutes and then post it to the defined callback endpoint. [block:api-header] { "type": "basic", "title": "Setting Up a Sandbox Account" } [/block] The first step to setup your sandbox is to request a Sandbox API Key by submitting [this form](https://unbabel.com/request-demo/). [block:api-header] { "type": "basic", "title": "Translating \"Hello, World!\"" } [/block] Once you have setup your sandbox, requesting a translation is very simple. You just need to do a HTTP request to the `translation` endpoint. Using a tool like cURL (learn more at [http://curl.haxx.se](http://curl.haxx.se)) is super easy. If this tool is not familiar to you, you can read a short intro about it with examples at [http://blogs.plexibus.com/2009/01/15/rest-esting-with-curl](http://blogs.plexibus.com/2009/01/15/rest-esting-with-curl). An alternative to cURL is [POSTMAN](https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en), an easy-to-use Chrome extension for making HTTP requests. You can also use one of our SDKs described in the SDKs sections. Using cURL, translating "Hello, world!" would be done by executing: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X POST https://sandbox.unbabel.com/tapi/v2/translation/ -d '{\"text\" : \"Hello, world!\", \"source_language\" : \"en\", \"target_language\" : \"pt\", \"text_format\" : \"text\"}'", "language": "shell", "name": "Request" } ] } [/block] In response you would have: [block:code] { "codes": [ { "code": "{\n \"balance\": 99943.0,\n \"client\": \"username\",\n \"price\": 6.0,\n \"source_language\": \"en\",\n \"status\": \"new\",\n \"target_language\": \"pt\",\n \"text\": \"Hello, world!\",\n \"text_format\": \"text\",\n \"uid\": \"ac1a53a264\"\n}", "language": "json", "name": "Response" } ] } [/block] To check the translation status you would use the returned job `uid` and do: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X GET https://sandbox.unbabel.com/tapi/v2/translation/ac1a53a264/", "language": "shell", "name": "Request" } ] } [/block] Please note that the "/" after the job uid is mandatory. Depending on the elapsed time between the two requests, you could get something like: [block:code] { "codes": [ { "code": "{\n \"balance\": 99937.0,\n \"client\": \"username\",\n \"price\": 6.0,\n \"source_language\": \"en\",\n \"status\": \"translating\",\n \"target_language\": \"pt\",\n \"text\": \"Hello, world!\",\n \"text_format\": \"text\",\n \"uid\": \"ac1a53a264\"\n}", "language": "json", "name": "Response: translation in progress" } ] } [/block] Or, immediately, the translation itself: [block:code] { "codes": [ { "code": "{\n\t\"balance\": 99937.0,\n\t\"client\": \"username\",\n\t\"price\": 6.0,\n\t\"source_language\": \"en\",\n\t\"status\": \"completed\",\n\t\"target_language\": \"pt\",\n\t\"text\": \"Hello, world!\",\n\t\"text_format\": \"text\",\n\t\"translated_text\": \"Olá Mundo!\",\n\t\"uid\": \"ac1a53a264\"\n}", "language": "json", "name": "Response: translation completed" } ] } [/block] These two possible responses depend on the time the translation takes to be completed. Since this relies on human processing, it may range from a few minutes to hours. [block:api-header] { "type": "basic", "title": "Translating a Product Description" } [/block] A product description is typically made of multiple parts like: product name, summary and description. As described in [Use Cases](doc:2-use-cases), you should always use the XLIFF format for this kind of content, sending all content parts in a single translation request. Splitting content parts in different translation requests could lead to inconsistencies in the translation. Let's use as an example the following product: [block:parameters] { "data": { "h-0": "Product Name", "h-1": "Product Description", "0-0": "Alice In Wonderland teapot", "0-1": "Beautiful porcelain tea pot with Alice and the Cheshire cat" }, "cols": 2, "rows": 1 } [/block] In XLIFF format this product could be represented like this: [block:code] { "codes": [ { "code": "<?xml version='1.0' encoding='utf-8'?>\n<xliff xmlns=\"urn:oasis:names:tc:xliff:document:1.2\" version=\"1.2\">\n <file original=\"\" source-language=\"en\" datatype=\"TEXT\">\n <header/>\n <body>\n <trans-unit id=\"name\" >\n <source>Alice In Wonderland teapot</source>\n </trans-unit>\n <trans-unit id=\"description\">\n <source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source>\n </trans-unit>\n </body>\n </file>\n</xliff>", "language": "xml", "name": "Product Description XLIFF" } ] } [/block] Using cURL, you can translate this product description by doing: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X POST https://sandbox.unbabel.com/tapi/v2/translation/ -d \"{\\\"text\\\" : \\\"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='name'><source>Alice In Wonderland teapot</source></trans-unit><trans-unit id='description'><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source></trans-unit></body></file></xliff>\\\", \\\"source_language\\\" : \\\"en\\\", \\\"target_language\\\" : \\\"pt\\\", \\\"text_format\\\" : \\\"xliff\\\"}\"", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"balance\": 99922.0,\n \"client\": \"username\",\n \"price\": 42.0,\n \"source_language\": \"en\",\n \"status\": \"new\",\n \"target_language\": \"pt\",\n \"text_format\": \"xliff\",\n \"uid\": \"937faff2b5\"\n}", "language": "json", "name": "Response" } ] } [/block] To check the translation status, you would do: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X GET https://sandbox.unbabel.com/tapi/v2/translation/937faff2b5/", "language": "shell", "name": "Request" } ] } [/block] In case the translation process has finished, the response would be: [block:code] { "codes": [ { "code": "{\n \"balance\": 99880.0,\n \"client\": \"username\",\n \"price\": 42.0,\n \"source_language\": \"en\",\n \"status\": \"completed\",\n \"target_language\": \"pt\",\n \"text\": \"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='name'><source>Alice In Wonderland teapot</source></trans-unit><trans-unit id='description'><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source></trans-unit></body></file></xliff>\",\n \"text_format\": \"xliff\",\n \"translated_text\": \"<?xml version=\\\"1.0\\\" encoding=\\\"utf-8\\\"?><xliff xmlns=\\\"urn:oasis:names:tc:xliff:document:1.2\\\" version=\\\"1.2\\\"><file original=\\\"\\\" source-language=\\\"en\\\" datatype=\\\"TEXT\\\"><header/><body><trans-unit id=\\\"name\\\"><source>Alice In Wonderland teapot</source><target>Alice In Wonderland bule</target></trans-unit><trans-unit id=\\\"description\\\"><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source><target>Bule de chá de porcelana bonita com Alice e o gato de Cheshire</target></trans-unit></body></file></xliff>\",\n \"uid\": \"937faff2b5\"\n}", "language": "json", "name": "Response" } ] } [/block] [block:api-header] { "type": "basic", "title": "Setting Tone and Topics" } [/block] As mentioned in [Getting Started](doc:getting-integrated), it's very important that you give as much context as possible about your content. Only in this way, Unbabel Editors will understand translation preferences like the tone that should be used (eg: informal or formal) and the type of content — translating a product description is quite different from translating user generated content. The fields `tone` and `topics` are used to associate this information with the translation request. Let's use as an example the translation of product descriptions for an e-commerce website (of crafts and technology). Using cURL, you could translate a product description giving context about it by doing: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X POST https://sandbox.unbabel.com/tapi/v2/translation/ -d \"{\\\"text\\\" : \\\"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='name'><source>Alice In Wonderland teapot</source></trans-unit><trans-unit id='description'><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source></trans-unit></body></file></xliff>\\\", \\\"source_language\\\" : \\\"en\\\", \\\"target_language\\\" : \\\"pt\\\", \\\"text_format\\\" : \\\"xliff\\\", \\\"tone\\\" : \\\"Formal\\\", \\\"topics\\\" : [\\\"tech\\\", \\\"crafts\\\"]}\"", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"balance\": 99880.0,\n \"client\": \"pdimas\",\n \"price\": 42.0,\n \"source_language\": \"en\",\n \"status\": \"new\",\n \"target_language\": \"pt\",\n \"tone\": \"Formal\",\n \"topics\": [\"tech\", \"crafts\"],\n \"uid\": \"8926cbec74\"\n}", "language": "json", "name": "Response" } ] } [/block] You can check the list of possible tones using cURL by doing: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X GET https://sandbox.unbabel.com/tapi/v2/tone/", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n\t\"objects\": [{\n\t\t\"tone\": {\n\t\t\t\"description\": \"Informal style\",\n\t\t\t\"name\": \"Informal\"\n\t\t}\n\t}, {\n\t\t\"tone\": {\n\t\t\t\"description\": \"Formal style\",\n\t\t\t\"name\": \"Formal\"\n\t\t}\n\t}]\n}", "language": "json", "name": "Response" } ] } [/block] And, to check the list of possible topics, you can do: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X GET https://sandbox.unbabel.com/tapi/v2/topic/", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n\t\"objects\": [{\n\t\t\"topic\": {\n\t\t\t\"name\": \"politics\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"gossip\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"sex & relationships\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"crafts\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"parenting\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"startups\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"tech\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"sports\"\n\t\t}\n\t}]\nhttps://dash.readme.io/legacy/}", "language": "json", "name": "Response" } ] } [/block]
{"_id":"566eeb0e7ffa002300c3cb26","type":"basic","excerpt":"","hidden":false,"link_external":false,"link_url":"","body":"To easily check the status of translation requests, you can access [http://sandbox.unbabel.com](http://sandbox.unbabel.com). After signing-in using your email and Sandbox API Key, you'll see the list of sent translation requests:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/2MBWOrtYQe6B8C7V4jJB_unbabel_api_sandbox_screenshot_20151214.png\",\n        \"unbabel_api_sandbox_screenshot_20151214.png\",\n        \"1018\",\n        \"119\",\n        \"#638391\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]","parentDoc":null,"updates":[],"order":3,"project":"54ad6c769219922100751763","slug":"sandbox-status-page","title":"Sandbox Status Page","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"category":"54afb7170cf42a0b001d5bf1","createdAt":"2015-12-14T16:15:10.224Z","githubsync":"","user":"5669472c08f90021008e887d","__v":1,"sync_unique":"","version":"54afb7160cf42a0b001d5bf0","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

Sandbox Status Page


To easily check the status of translation requests, you can access [http://sandbox.unbabel.com](http://sandbox.unbabel.com). After signing-in using your email and Sandbox API Key, you'll see the list of sent translation requests: [block:image] { "images": [ { "image": [ "https://files.readme.io/2MBWOrtYQe6B8C7V4jJB_unbabel_api_sandbox_screenshot_20151214.png", "unbabel_api_sandbox_screenshot_20151214.png", "1018", "119", "#638391", "" ] } ] } [/block]
To easily check the status of translation requests, you can access [http://sandbox.unbabel.com](http://sandbox.unbabel.com). After signing-in using your email and Sandbox API Key, you'll see the list of sent translation requests: [block:image] { "images": [ { "image": [ "https://files.readme.io/2MBWOrtYQe6B8C7V4jJB_unbabel_api_sandbox_screenshot_20151214.png", "unbabel_api_sandbox_screenshot_20151214.png", "1018", "119", "#638391", "" ] } ] } [/block]
{"_id":"566eeb81c1b00f1900ffd3c1","category":"54afb7170cf42a0b001d5bf1","excerpt":"","isReference":false,"sync_unique":"","title":"Getting a Production API Key","updates":[],"user":"5669472c08f90021008e887d","__v":2,"version":"54afb7160cf42a0b001d5bf0","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":4,"parentDoc":null,"type":"basic","body":"After having your code tested on the free API Sandbox, you may proceed to the production environment to benefit from Unbabel's scalable human quality translation.\n\nIf you have not yet created an account at Unbabel you'll now need to do it at: [https://unbabel.com/customer/signup](https://unbabel.com/customer/signup).\n\nOn your Dashboard, you can find the Production API Key on the API Access tab. You can also view it directly opening [https://unbabel.com/customer/dashboard/api_access/](https://unbabel.com/customer/dashboard/api_access/).\n\nPlease note that instead of **https://sandbox.unbabel.com** you should now use the production endpoint **https://api.unbabel.com**.","project":"54ad6c769219922100751763","createdAt":"2015-12-14T16:17:05.765Z","next":{"description":"","pages":[]},"slug":"getting-a-production-api-key","api":{"settings":"","url":"","auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]}},"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

Getting a Production API Key


After having your code tested on the free API Sandbox, you may proceed to the production environment to benefit from Unbabel's scalable human quality translation. If you have not yet created an account at Unbabel you'll now need to do it at: [https://unbabel.com/customer/signup](https://unbabel.com/customer/signup). On your Dashboard, you can find the Production API Key on the API Access tab. You can also view it directly opening [https://unbabel.com/customer/dashboard/api_access/](https://unbabel.com/customer/dashboard/api_access/). Please note that instead of **https://sandbox.unbabel.com** you should now use the production endpoint **https://api.unbabel.com**.
After having your code tested on the free API Sandbox, you may proceed to the production environment to benefit from Unbabel's scalable human quality translation. If you have not yet created an account at Unbabel you'll now need to do it at: [https://unbabel.com/customer/signup](https://unbabel.com/customer/signup). On your Dashboard, you can find the Production API Key on the API Access tab. You can also view it directly opening [https://unbabel.com/customer/dashboard/api_access/](https://unbabel.com/customer/dashboard/api_access/). Please note that instead of **https://sandbox.unbabel.com** you should now use the production endpoint **https://api.unbabel.com**.
{"_id":"566eebb746acce17000c88b6","next":{"description":"","pages":[]},"order":5,"updates":[],"excerpt":"","hidden":false,"isReference":false,"link_url":"","parentDoc":null,"slug":"api-usage-notes","__v":1,"category":"54afb7170cf42a0b001d5bf1","createdAt":"2015-12-14T16:17:59.404Z","link_external":false,"title":"API Usage Notes","user":"5669472c08f90021008e887d","version":"54afb7160cf42a0b001d5bf0","api":{"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"name":"","status":400,"language":"json","code":"{}"}]},"settings":"","auth":"required","params":[]},"body":"When using the Unbabel API:\n\n* all paths are prefixed with https://api.unbabel.com or https://sandbox.unbabel.com\n\n* all data sent to non-GET endpoints is in the JSON format\n\n* all responses are in the JSON format\n\n* for all endpoints, you MUST use the trailing /\n\n* all prices and balances are in USD cents","githubsync":"","project":"54ad6c769219922100751763","sync_unique":"","type":"basic","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

API Usage Notes


When using the Unbabel API: * all paths are prefixed with https://api.unbabel.com or https://sandbox.unbabel.com * all data sent to non-GET endpoints is in the JSON format * all responses are in the JSON format * for all endpoints, you MUST use the trailing / * all prices and balances are in USD cents
When using the Unbabel API: * all paths are prefixed with https://api.unbabel.com or https://sandbox.unbabel.com * all data sent to non-GET endpoints is in the JSON format * all responses are in the JSON format * for all endpoints, you MUST use the trailing / * all prices and balances are in USD cents
{"_id":"54afcb5aed9ada1400afbf5d","version":"54afb7160cf42a0b001d5bf0","body":"We currently have several SDKs in various stages of development. If your preferred language's SDK needs development or does not exist, please get in touch with us at [email protected]! We are always looking for an excuse to work on our SDKs! \n\nCurrently, we have SDKs in [python](https://github.com/Unbabel/unbabel-py), [ruby](https://github.com/Unbabel/unbabel-ruby), and [php](https://github.com/Unbabel/unbabel-php).\n\nIn your [Unbabel Dashboard](https://unbabel.com/customer/dashboard/api_access/) make a note of your production username and API key.\n\nUsing these credentials and your SDK you are now ready to fully integrate Unbabel into your application or service.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Python\"\n}\n[/block]\nThis is the most developed and maintained repo since we use python here at Unbabel and make heavy use of this SDK.\n\n## Installation\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"pip install unbabel-py\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n# import it and get set up\n\nDo this before all the following examples\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"from unbabel.api import UnbabelApi\\n\\nuapi = UnbabelApi(unbabel_username, unbabel_api_key, \\n                  sandbox=in_test_mode)\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n# post single translation\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"to_translate = 'This is a test'\\ntarget_language = 'pt'\\ncallback_url = 'http://my_awesome_app.com/unbabel_callback/'\\n\\nuapi.post_translations(text=to_translate, target_language=target_language,\\n                       callback_url=callback_url)\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Ruby\"\n}\n[/block]\nWe created the ruby SDK in collaboration with [jobbox](jobbox.io) with two [/translation/](doc:tapiv2translation) endpoints. They are on Rails, so the following is the examples are from their use case.\n\n## Installation\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# place this in your Gemfile\\n\\ngem 'unbabel-ruby', github: 'Unbabel/unbabel-ruby', require:’unbabel’\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\n## Import and get set up\n\nBefore requesting translation, get credentials and instantiate \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# No need to import, the entry in the Gemfile takes care of it\\n# as long as you are in a Rails project\\n\\n# In production, you will want to keep the username / password\\n# as an environment variable or in a config file\\nusername = ENV['UNBABEL_USER_ID']\\napikey = ENV['UNBABEL_API_KEY']\\n\\nub = Unbabel.new(username, apikey)\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\n## Request a translation\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"to_translate = 'This is a test'\\ntarget_language = 'pt'\\n\\nub.post_translations(to_translate, target_language, \\n  \\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\ttext_format: :html, \\n  \\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\tcallback_url: callback_url)\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\n## Check on the status of the translation\n\nUsing the translation id from the initial request, check on the status.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"response = ub.query_translation(uid)\\n# This JSON.parse calls should probably be done from within\\n# the SDK so you don't have to use it every time.\\npayload = JSON.parse response.body\\nstatus = payload['status'].to_sym\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"PHP\"\n}\n[/block]\nThis SDK is in very early-stage development. Suggestions are welcome!\n\n## Installation\n\nYou can install via composer with the following `composer.json` file\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"require\\\": {\\n        \\\"unbabel/unbabel-php\\\": \\\"dev-master\\\"\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## Import and setup\n\nIf installed via composer, require and instantiate\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\nrequire 'vendor/autoload.php';\\n\\n$unbabel_username = getenv('UNBABEL_USERNAME');\\n$unbabel_apikey = getenv('UNBABEL_APIKEY');\\n\\n$unbabel = new Unbabel($unbabel_username, $unbabel_apikey, \\n                       $sandbox = false);\\n\\n?>\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]\n## Now request a translation\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\n\\n$text = 'This is a test';\\n$target_language = 'pt';\\n\\n$resp = $unbabel->submitTranslation($text, $target_language);\\n\\n?>\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]","createdAt":"2015-01-09T12:36:42.204Z","githubsync":"","hidden":false,"link_external":false,"slug":"sdks","title":"SDKs","__v":8,"category":"54afb7170cf42a0b001d5bf1","order":6,"parentDoc":null,"project":"54ad6c769219922100751763","user":"54ad6c239219922100751762","api":{"auth":"required","params":[],"results":{"codes":[{"language":"json","code":"{}","name":"","status":200},{"code":"{}","name":"","status":400,"language":"json"}]},"settings":"","url":""},"link_url":"","updates":[],"excerpt":"","sync_unique":"","type":"basic","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

SDKs


We currently have several SDKs in various stages of development. If your preferred language's SDK needs development or does not exist, please get in touch with us at [email protected]! We are always looking for an excuse to work on our SDKs! Currently, we have SDKs in [python](https://github.com/Unbabel/unbabel-py), [ruby](https://github.com/Unbabel/unbabel-ruby), and [php](https://github.com/Unbabel/unbabel-php). In your [Unbabel Dashboard](https://unbabel.com/customer/dashboard/api_access/) make a note of your production username and API key. Using these credentials and your SDK you are now ready to fully integrate Unbabel into your application or service. [block:api-header] { "type": "basic", "title": "Python" } [/block] This is the most developed and maintained repo since we use python here at Unbabel and make heavy use of this SDK. ## Installation [block:code] { "codes": [ { "code": "pip install unbabel-py", "language": "python" } ] } [/block] # import it and get set up Do this before all the following examples [block:code] { "codes": [ { "code": "from unbabel.api import UnbabelApi\n\nuapi = UnbabelApi(unbabel_username, unbabel_api_key, \n sandbox=in_test_mode)", "language": "python" } ] } [/block] # post single translation [block:code] { "codes": [ { "code": "to_translate = 'This is a test'\ntarget_language = 'pt'\ncallback_url = 'http://my_awesome_app.com/unbabel_callback/'\n\nuapi.post_translations(text=to_translate, target_language=target_language,\n callback_url=callback_url)", "language": "python" } ] } [/block] [block:api-header] { "type": "basic", "title": "Ruby" } [/block] We created the ruby SDK in collaboration with [jobbox](jobbox.io) with two [/translation/](doc:tapiv2translation) endpoints. They are on Rails, so the following is the examples are from their use case. ## Installation [block:code] { "codes": [ { "code": "# place this in your Gemfile\n\ngem 'unbabel-ruby', github: 'Unbabel/unbabel-ruby', require:’unbabel’", "language": "ruby" } ] } [/block] ## Import and get set up Before requesting translation, get credentials and instantiate [block:code] { "codes": [ { "code": "# No need to import, the entry in the Gemfile takes care of it\n# as long as you are in a Rails project\n\n# In production, you will want to keep the username / password\n# as an environment variable or in a config file\nusername = ENV['UNBABEL_USER_ID']\napikey = ENV['UNBABEL_API_KEY']\n\nub = Unbabel.new(username, apikey)", "language": "ruby" } ] } [/block] ## Request a translation [block:code] { "codes": [ { "code": "to_translate = 'This is a test'\ntarget_language = 'pt'\n\nub.post_translations(to_translate, target_language, \n \t\t\t\t\t\t\t\t\t\t\t\t\t\t\ttext_format: :html, \n \t\t\t\t\t\t\t\t\t\t\t\t\t\t\tcallback_url: callback_url)", "language": "ruby" } ] } [/block] ## Check on the status of the translation Using the translation id from the initial request, check on the status. [block:code] { "codes": [ { "code": "response = ub.query_translation(uid)\n# This JSON.parse calls should probably be done from within\n# the SDK so you don't have to use it every time.\npayload = JSON.parse response.body\nstatus = payload['status'].to_sym", "language": "ruby" } ] } [/block] [block:api-header] { "type": "basic", "title": "PHP" } [/block] This SDK is in very early-stage development. Suggestions are welcome! ## Installation You can install via composer with the following `composer.json` file [block:code] { "codes": [ { "code": "{\n \"require\": {\n \"unbabel/unbabel-php\": \"dev-master\"\n }\n}", "language": "json" } ] } [/block] ## Import and setup If installed via composer, require and instantiate [block:code] { "codes": [ { "code": "<?php\nrequire 'vendor/autoload.php';\n\n$unbabel_username = getenv('UNBABEL_USERNAME');\n$unbabel_apikey = getenv('UNBABEL_APIKEY');\n\n$unbabel = new Unbabel($unbabel_username, $unbabel_apikey, \n $sandbox = false);\n\n?>", "language": "php" } ] } [/block] ## Now request a translation [block:code] { "codes": [ { "code": "<?php\n\n$text = 'This is a test';\n$target_language = 'pt';\n\n$resp = $unbabel->submitTranslation($text, $target_language);\n\n?>", "language": "php" } ] } [/block]
We currently have several SDKs in various stages of development. If your preferred language's SDK needs development or does not exist, please get in touch with us at [email protected]! We are always looking for an excuse to work on our SDKs! Currently, we have SDKs in [python](https://github.com/Unbabel/unbabel-py), [ruby](https://github.com/Unbabel/unbabel-ruby), and [php](https://github.com/Unbabel/unbabel-php). In your [Unbabel Dashboard](https://unbabel.com/customer/dashboard/api_access/) make a note of your production username and API key. Using these credentials and your SDK you are now ready to fully integrate Unbabel into your application or service. [block:api-header] { "type": "basic", "title": "Python" } [/block] This is the most developed and maintained repo since we use python here at Unbabel and make heavy use of this SDK. ## Installation [block:code] { "codes": [ { "code": "pip install unbabel-py", "language": "python" } ] } [/block] # import it and get set up Do this before all the following examples [block:code] { "codes": [ { "code": "from unbabel.api import UnbabelApi\n\nuapi = UnbabelApi(unbabel_username, unbabel_api_key, \n sandbox=in_test_mode)", "language": "python" } ] } [/block] # post single translation [block:code] { "codes": [ { "code": "to_translate = 'This is a test'\ntarget_language = 'pt'\ncallback_url = 'http://my_awesome_app.com/unbabel_callback/'\n\nuapi.post_translations(text=to_translate, target_language=target_language,\n callback_url=callback_url)", "language": "python" } ] } [/block] [block:api-header] { "type": "basic", "title": "Ruby" } [/block] We created the ruby SDK in collaboration with [jobbox](jobbox.io) with two [/translation/](doc:tapiv2translation) endpoints. They are on Rails, so the following is the examples are from their use case. ## Installation [block:code] { "codes": [ { "code": "# place this in your Gemfile\n\ngem 'unbabel-ruby', github: 'Unbabel/unbabel-ruby', require:’unbabel’", "language": "ruby" } ] } [/block] ## Import and get set up Before requesting translation, get credentials and instantiate [block:code] { "codes": [ { "code": "# No need to import, the entry in the Gemfile takes care of it\n# as long as you are in a Rails project\n\n# In production, you will want to keep the username / password\n# as an environment variable or in a config file\nusername = ENV['UNBABEL_USER_ID']\napikey = ENV['UNBABEL_API_KEY']\n\nub = Unbabel.new(username, apikey)", "language": "ruby" } ] } [/block] ## Request a translation [block:code] { "codes": [ { "code": "to_translate = 'This is a test'\ntarget_language = 'pt'\n\nub.post_translations(to_translate, target_language, \n \t\t\t\t\t\t\t\t\t\t\t\t\t\t\ttext_format: :html, \n \t\t\t\t\t\t\t\t\t\t\t\t\t\t\tcallback_url: callback_url)", "language": "ruby" } ] } [/block] ## Check on the status of the translation Using the translation id from the initial request, check on the status. [block:code] { "codes": [ { "code": "response = ub.query_translation(uid)\n# This JSON.parse calls should probably be done from within\n# the SDK so you don't have to use it every time.\npayload = JSON.parse response.body\nstatus = payload['status'].to_sym", "language": "ruby" } ] } [/block] [block:api-header] { "type": "basic", "title": "PHP" } [/block] This SDK is in very early-stage development. Suggestions are welcome! ## Installation You can install via composer with the following `composer.json` file [block:code] { "codes": [ { "code": "{\n \"require\": {\n \"unbabel/unbabel-php\": \"dev-master\"\n }\n}", "language": "json" } ] } [/block] ## Import and setup If installed via composer, require and instantiate [block:code] { "codes": [ { "code": "<?php\nrequire 'vendor/autoload.php';\n\n$unbabel_username = getenv('UNBABEL_USERNAME');\n$unbabel_apikey = getenv('UNBABEL_APIKEY');\n\n$unbabel = new Unbabel($unbabel_username, $unbabel_apikey, \n $sandbox = false);\n\n?>", "language": "php" } ] } [/block] ## Now request a translation [block:code] { "codes": [ { "code": "<?php\n\n$text = 'This is a test';\n$target_language = 'pt';\n\n$resp = $unbabel->submitTranslation($text, $target_language);\n\n?>", "language": "php" } ] } [/block]
{"_id":"5f29a196c66a0b00617dcbcf","metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"code":"{}","name":"","status":400,"language":"json"}]},"settings":""},"next":{"description":"","pages":[]},"title":"Getting Started","type":"basic","slug":"getting-started","excerpt":"","body":"The Unbabel API allows you to translate large volumes of content. \nThis high scalability is achieved by our unique blend of machine-translation and human editors (our community of translators).\n\nThe following diagram illustrates Unbabel's translation process:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/7375743-unbabel-translation-pipeline.png\",\n        \"unbabel-translation-pipeline.png\",\n        3280,\n        1336,\n        \"#3c44d4\"\n      ]\n    }\n  ]\n}\n[/block]\nIt's important to understand that each translation request involves human processing. For this reason, all translation outputs are asynchronous.\n[block:api-header]\n{\n  \"title\": \"Brand\"\n}\n[/block]\nAt Unbabel we know that some customers need to **manage multiple brands** (or products and services), so we’ve made it easy to manage these under one Unbabel account.\n\nAll Unbabel accounts will now have a default **Brand**, with the ability to add more. Each Brand can have its own Tones, Instructions and Glossaries on a **per language** basis.\n\nIf you have multiple Brands and request a translation without specifying which one to use, then we will use the default Brand, so please make sure you select the correct one.\n\n**PLEASE NOTE:** Currently, Brands can only be configured by our Customer Success team. Please email them at **[[email protected]](mailto:[email protected])** for more information.ore information.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Tone, Topics and Translation Instructions\"\n}\n[/block]\nTo help Unbabel Editors translate your content in the best possible way, each translation request should have as much context as possible. This context is set by filling-in the following fields of each request:\n\n* **tone** that Unbabel Editors should take into account when working on the translation, you can select one of the following: \"Informal\", \"Formal\"\n\n* **topics** to help Unbabel choose the more appropriate Editors for your type of content, examples are \"travel\", \"technology\" or \"sports\" \n\n* **instructions** to be shown to Editors while they are working on your translation, examples are \"This is a product description for an e-commerce website\", \"This is a customer support ticket for a travel website\" or \"Please open www.example.com for reference\"\n\n**It's very important** that you provide as much of this information as possible on each translation request.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Glossary and Style Guide\"\n}\n[/block]\nAre there any terms, like brands or product features, that should not be translated? Should the communication be formal or informal? For this reason, each Unbabel account has associated one or more **Brands**, where at least one of them will be checked as default and each brand has Glossary.\n\nDepending on your type of content, our Customer Success Team may ask you for sample content or references that can be used to speed up the creation of the Glossary and Style Guide.\n\nPlease note that **translation requests done before this onboarding process** may result in the wrong translation of brand or product terms. Our team at **[[email protected]](mailto:[email protected])** will help on this process.","updates":[],"order":7,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"createdAt":"2020-08-04T17:57:42.527Z","user":"5f27f8c862e7f203d4755386","category":"54afb7170cf42a0b001d5bf1","version":"54afb7160cf42a0b001d5bf0","project":"54ad6c769219922100751763","__v":0,"parentDoc":null,"childrenPages":[]}

Getting Started


The Unbabel API allows you to translate large volumes of content. This high scalability is achieved by our unique blend of machine-translation and human editors (our community of translators). The following diagram illustrates Unbabel's translation process: [block:image] { "images": [ { "image": [ "https://files.readme.io/7375743-unbabel-translation-pipeline.png", "unbabel-translation-pipeline.png", 3280, 1336, "#3c44d4" ] } ] } [/block] It's important to understand that each translation request involves human processing. For this reason, all translation outputs are asynchronous. [block:api-header] { "title": "Brand" } [/block] At Unbabel we know that some customers need to **manage multiple brands** (or products and services), so we’ve made it easy to manage these under one Unbabel account. All Unbabel accounts will now have a default **Brand**, with the ability to add more. Each Brand can have its own Tones, Instructions and Glossaries on a **per language** basis. If you have multiple Brands and request a translation without specifying which one to use, then we will use the default Brand, so please make sure you select the correct one. **PLEASE NOTE:** Currently, Brands can only be configured by our Customer Success team. Please email them at **[[email protected]](mailto:[email protected])** for more information.ore information. [block:api-header] { "type": "basic", "title": "Tone, Topics and Translation Instructions" } [/block] To help Unbabel Editors translate your content in the best possible way, each translation request should have as much context as possible. This context is set by filling-in the following fields of each request: * **tone** that Unbabel Editors should take into account when working on the translation, you can select one of the following: "Informal", "Formal" * **topics** to help Unbabel choose the more appropriate Editors for your type of content, examples are "travel", "technology" or "sports" * **instructions** to be shown to Editors while they are working on your translation, examples are "This is a product description for an e-commerce website", "This is a customer support ticket for a travel website" or "Please open www.example.com for reference" **It's very important** that you provide as much of this information as possible on each translation request. [block:api-header] { "type": "basic", "title": "Glossary and Style Guide" } [/block] Are there any terms, like brands or product features, that should not be translated? Should the communication be formal or informal? For this reason, each Unbabel account has associated one or more **Brands**, where at least one of them will be checked as default and each brand has Glossary. Depending on your type of content, our Customer Success Team may ask you for sample content or references that can be used to speed up the creation of the Glossary and Style Guide. Please note that **translation requests done before this onboarding process** may result in the wrong translation of brand or product terms. Our team at **[[email protected]](mailto:[email protected])** will help on this process.
The Unbabel API allows you to translate large volumes of content. This high scalability is achieved by our unique blend of machine-translation and human editors (our community of translators). The following diagram illustrates Unbabel's translation process: [block:image] { "images": [ { "image": [ "https://files.readme.io/7375743-unbabel-translation-pipeline.png", "unbabel-translation-pipeline.png", 3280, 1336, "#3c44d4" ] } ] } [/block] It's important to understand that each translation request involves human processing. For this reason, all translation outputs are asynchronous. [block:api-header] { "title": "Brand" } [/block] At Unbabel we know that some customers need to **manage multiple brands** (or products and services), so we’ve made it easy to manage these under one Unbabel account. All Unbabel accounts will now have a default **Brand**, with the ability to add more. Each Brand can have its own Tones, Instructions and Glossaries on a **per language** basis. If you have multiple Brands and request a translation without specifying which one to use, then we will use the default Brand, so please make sure you select the correct one. **PLEASE NOTE:** Currently, Brands can only be configured by our Customer Success team. Please email them at **[[email protected]](mailto:[email protected])** for more information.ore information. [block:api-header] { "type": "basic", "title": "Tone, Topics and Translation Instructions" } [/block] To help Unbabel Editors translate your content in the best possible way, each translation request should have as much context as possible. This context is set by filling-in the following fields of each request: * **tone** that Unbabel Editors should take into account when working on the translation, you can select one of the following: "Informal", "Formal" * **topics** to help Unbabel choose the more appropriate Editors for your type of content, examples are "travel", "technology" or "sports" * **instructions** to be shown to Editors while they are working on your translation, examples are "This is a product description for an e-commerce website", "This is a customer support ticket for a travel website" or "Please open www.example.com for reference" **It's very important** that you provide as much of this information as possible on each translation request. [block:api-header] { "type": "basic", "title": "Glossary and Style Guide" } [/block] Are there any terms, like brands or product features, that should not be translated? Should the communication be formal or informal? For this reason, each Unbabel account has associated one or more **Brands**, where at least one of them will be checked as default and each brand has Glossary. Depending on your type of content, our Customer Success Team may ask you for sample content or references that can be used to speed up the creation of the Glossary and Style Guide. Please note that **translation requests done before this onboarding process** may result in the wrong translation of brand or product terms. Our team at **[[email protected]](mailto:[email protected])** will help on this process.
{"_id":"54afc0d4ed9ada1400afbf52","link_url":"","parentDoc":null,"sync_unique":"","version":"54afb7160cf42a0b001d5bf0","createdAt":"2015-01-09T11:51:48.744Z","excerpt":"Fetch all language pairs supported by Unbabel.","hidden":false,"isReference":false,"order":0,"project":"54ad6c769219922100751763","updates":["5902a868c669170f006645a1","5e787ac13d0519003c3e852f","5e787b08c28a7b00114d8352","5e9fa852b4e303003e065a83","607d47f0f13e66006f272a80","60b872f737de99000f450ace"],"user":"54ad6c239219922100751762","category":"55a8e8e1c8bd450d000dd0ec","githubsync":"","next":{"description":"","pages":[]},"__v":12,"api":{"examples":{"codes":[{"language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://api.unbabel.com/tapi/v2/language_pair/","name":"curl"}]},"method":"get","params":[],"results":{"codes":[{"language":"json","code":"{\n  \"objects\": [\n  \t{\n      \"lang_pair\": {\n       \"source_language\": {\n         \"name\": \"Portuguese\", \n         \"shortname\": \"pt\"\n       }, \n      \"target_language\": {\n        \"name\": \"English\", \n        \"shortname\": \"en\"}\n      }\n    }, (...)\n }","name":"","status":200},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"/language_pair/","auth":"required"},"body":"You can use this call to verify if the languages of the translation you are about to request are supported by Unbabel. If they are, you can use the shortnames as the `source_language` and `target_language` fields in the `/translation/` resource.","title":"/language_pair/","link_external":false,"slug":"language_pair","type":"get","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

get/language_pair/

Fetch all language pairs supported by Unbabel.

You can use this call to verify if the languages of the translation you are about to request are supported by Unbabel. If they are, you can use the shortnames as the `source_language` and `target_language` fields in the `/translation/` resource.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



You can use this call to verify if the languages of the translation you are about to request are supported by Unbabel. If they are, you can use the shortnames as the `source_language` and `target_language` fields in the `/translation/` resource.
{"_id":"60118112655ee400187da9b9","metadata":{"image":[],"title":"","description":""},"api":{"url":"/v2/chats/messages","auth":"required","settings":"5b7e91941bf4b60003e65fc6","results":{"codes":[{"name":"","code":"{\n  \"chat\": {\n    \"id\": \"59142b06684059a779224563\",\n    \"agent_external_id\": \"[email protected]\",\n    \"brand\": \"default-brand\",\n    \"creation_date\": \"2021-01-22T18:37:08.185156\",\n    \"external_id\": \"1\"\n  },\n  \"message\": {\n    \"id\": \"598c26f86840598e7614faac\",\n    \"author_external_id\": \"[email protected]\",\n    \"callback_url\": \"https://a-service.com/unbabel-webhook\",\n    \"chat_id\": \"59142b06684059a779224563\",\n    \"creation_date\": \"2021-01-22T18:37:08.185199\",\n    \"external_id\": \"1\",\n    \"is_inbound\": false,\n    \"source_language\": \"pt\",\n    \"status\": \"mt_init\",\n    \"target_language\": \"en\",\n    \"text\": \"Hello world\",\n    \"text_format\": \"text\"\n  }\n}","language":"json","status":200},{"name":"","code":"{\"error\": \"Missing or incorrect authentication credentials.\"}","language":"json","status":401}]},"params":[{"name":"chat_external_id","type":"string","default":"","desc":"Chat ID on the source platform.","required":true,"in":"body","ref":"","_id":"6011824a067b3100739411fb"},{"name":"source_language","type":"string","default":"","desc":"Source language of the message.","required":true,"in":"body","ref":"","_id":"6011824a067b3100739411fc"},{"name":"target_language","type":"string","default":"","desc":"Target language to translate the message to.","required":true,"in":"body","ref":"","_id":"6011824a067b3100739411fd"},{"name":"text","type":"string","default":"","desc":"The message text to translate. The format of this field should conform with text_format.","required":true,"in":"body","ref":"","_id":"6011844dc297280011f0d4d6"},{"name":"text_format","type":"string","default":"","desc":"Format of the message text. Either html or text.","required":true,"in":"body","ref":"","_id":"6011844dc297280011f0d4d7"},{"name":"external_id","type":"string","default":"","desc":"Message ID in the source platform. This has to identify the message uniquely within the chat.","required":true,"in":"body","ref":"","_id":"6011844dc297280011f0d4d8"},{"name":"callback_url","type":"string","default":"","desc":"URL to where the response is sent.","required":false,"in":"body","ref":"","_id":"6011844dc297280011f0d4d9"},{"name":"brand","type":"string","default":"","desc":"Optional. Brand ID on the source platform.","required":false,"in":"body","ref":"","_id":"6011844dc297280011f0d4da"},{"name":"brand_external_name","type":"string","default":"","desc":"Optional. A human readable name for the brand provided","required":false,"in":"body","ref":"","_id":"6092ece9ec838f006c7d7b83"},{"name":"agent_external_id","type":"string","default":"","desc":"Optional. ID of the agent serving the chat on the source platform. Should be the email of the agent.","required":false,"in":"body","ref":"","_id":"6011844dc297280011f0d4db"},{"name":"is_inbound","type":"boolean","default":"","desc":"Optional.  Indicates if a message is inbound to an agent. The message direction in relation to the agent is defined by the author of the message, as such a message created by an agent is outbound (field must be false.) A message created by a customer is inbound (field must be true).","required":false,"in":"body","ref":"","_id":"6011844dc297280011f0d4dc"},{"name":"author_external_id","type":"string","default":"","desc":"Optional.  User ID of the author of the message. Maps to the external ID of the agent for outbound messages or the customer for inbound messages. When an agent should be the email of the agent.","required":false,"in":"body","ref":"","_id":"6011844dc297280011f0d4dd"}],"examples":{"codes":[{"code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X POST https://chat-api.unbabel.com/v2/chats/messages \\\n        -d '{\n                \"chat_external_id\": \"1\",\n                \"source_language\": \"en\",\n                \"target_language\": \"pt\",\n                \"text\": \"Hello world\",\n                \"text_format\": \"text\",\n                \"external_id\": \"1\",\n                \"callback_url\": \"https://a-service.com/unbabel-webhook\",\n                \"brand\": \"default-brand\",\n                \"agent_external_id\": \"[email protected].com\",\n                \"is_inbound\": false,\n                \"author_external_id\": \"[email protected]\"\n\t\t\t\t\t\t}'","language":"shell"}]},"method":"post"},"next":{"description":"","pages":[]},"title":"/v2/chats/messages","type":"post","slug":"v2chatsmessages","excerpt":"","body":"# Request a Chat Translation\n\nA translation is only possible over a message, which must belong to a chat. As such, a chat must have one or more messages, and messages must have one translation. All of them are created using this endpoint.\n\nChats are created whenever the `chat_external_id` is new, and messages are created when the `external_id` is new for a specific chat. Check the example below:\n\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"chat_external_id\",\n    \"h-1\": \"external_id\",\n    \"h-2\": \"Actions\",\n    \"h-3\": \"Status code\",\n    \"0-0\": \"1\",\n    \"1-0\": \"1\",\n    \"2-0\": \"1\",\n    \"3-0\": \"2\",\n    \"0-1\": \"1\",\n    \"1-1\": \"2\",\n    \"2-1\": \"2\",\n    \"3-1\": \"1\",\n    \"0-2\": \"Chat and message are created\",\n    \"1-2\": \"Message is created, and associated with chat 1\",\n    \"2-2\": \"Chat and message are not created\",\n    \"3-2\": \"Chat and message are created, but the chat is different from above\",\n    \"0-3\": \"201\",\n    \"1-3\": \"201\",\n    \"2-3\": \"200\",\n    \"3-3\": \"201\"\n  },\n  \"cols\": 4,\n  \"rows\": 4\n}\n[/block]\nThis means that this endpoint is idempotent. You can reuse the same call to request translations and to check them (and the chat and message entities).\n\nThe source language or a translation refers to the original language of the text to be translated, while the target language indicates the language to translate to.\n\nThe source and target languages are tied to the message direction (inbound vs outbound):\n* for an inbound message, the customer language will be the source and the agent language will be the target;\n* for an outbound message, the agent language will be the source and the customer language will be the target.\n\nThis endpoint will only get or create the chat and message entities, and not updating them. \n\n## Scenarios\n\n_Successful scenarios_\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Scenario\",\n    \"h-1\": \"Status code\",\n    \"0-1\": \"201\",\n    \"1-1\": \"201\",\n    \"2-1\": \"200\",\n    \"0-0\": \"New chat and message\",\n    \"1-0\": \"Existing chat and new message\",\n    \"2-0\": \"Existing chat and message\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n_Failure scenarios_\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Scenario\",\n    \"h-1\": \"Status code\",\n    \"h-2\": \"Error\",\n    \"h-3\": \"How to recover\",\n    \"0-0\": \"Invalid payload\",\n    \"1-0\": \"Invalid subscription\",\n    \"2-0\": \"Server error\",\n    \"0-1\": \"400\",\n    \"1-1\": \"402\",\n    \"2-1\": \"5xx\",\n    \"0-2\": \"`validation_error`\",\n    \"1-2\": \"`invalid_subscription`\",\n    \"2-2\": \"`server_error`\",\n    \"0-3\": \"Check the payload. Error message should have more information.\",\n    \"2-3\": \"Repeat the call, since this endpoint is idempotent you can retry safely.\"\n  },\n  \"cols\": 4,\n  \"rows\": 3\n}\n[/block]\n## Receiving the translation\n\nYou can receive the translation in two ways:\n1. Through a callback URL that is used upon translation complete  **(recommended)**\n2. Long pooling the message using this endpoint or any other that where you can retrieve the message\n\n### Through a webhook\n\nThe service receiving the translations must return a response with the status code on the `2xx` range.\n\n_Sample call made when delivering:_\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"> curl -X POST \\\\\\\\\\n    \\\"https://a-service.com/unbabel-webhook\\\" \\\\ \\n    -H \\\"content-type: application/json\\\" \\\\\\n    -H \\\"ce-type: com.unbabel.chat-api.v2\\\" \\\\\\n    -H \\\"ce-time: 2021-01-01T10:00:00.263865\\\" \\\\\\n    -H \\\"ce-specversion: 1.0\\\" \\\\\\n    -H \\\"ce-source: https://chat-api.unbabel.com\\\" \\\\\\n    -H \\\"ce-id: chatapi-6037f8cccfc375315c29266b\\\" \\\\\\n    -H \\\"ce-datacontenttype: application/json\\\" \\\\\\n    --data-binary '{\\n      \\\"chat\\\": {\\n        \\\"id\\\": \\\"6037f8cccfc375315c292660\\\",\\n        \\\"creation_date\\\": \\\"2021-01-01T10:00:00\\\",\\n        \\\"external_id\\\": \\\"1\\\",\\n        \\\"agent_external_id\\\": null,\\n        \\\"brand\\\": null\\n      },\\n      \\\"message\\\": {\\n        \\\"id\\\": \\\"6037f8cccfc375315c29266b\\\",\\n        \\\"author_external_id\\\": null,\\n        \\\"callback_url\\\": \\\"https://a-service.com/unbabel-webhook\\\",\\n        \\\"chat_id\\\": \\\"6037f8cccfc375315c292660\\\",\\n        \\\"completion_date\\\": \\\"2021-01-01T10:00:00.589829\\\",\\n        \\\"creation_date\\\": \\\"2021-01-01T10:00:01.867000\\\",\\n        \\\"external_id\\\": \\\"1\\\",\\n        \\\"translated_text\\\": \\\"Olá, mundo\\\",\\n        \\\"is_inbound\\\": null,\\n        \\\"source_language\\\": \\\"en\\\",\\n        \\\"status\\\": \\\"deliver_init\\\",\\n        \\\"target_language\\\": \\\"pt\\\",\\n        \\\"text\\\": \\\"hello world\\\",\\n        \\\"text_format\\\": \\\"text\\\",\\n        \\\"translation_uid\\\": \\\"chatapi-6037f8cccfc375315c29266b\\\"\\n      }\\n    }'\\n\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]","updates":[],"order":0,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"createdAt":"2021-01-27T15:04:50.952Z","user":"5f2035316dda9a0045002588","category":"5b7e90665a0e4e0003a41e68","version":"54afb7160cf42a0b001d5bf0","project":"54ad6c769219922100751763","__v":12,"parentDoc":null,"childrenPages":[]}

post/v2/chats/messages


Body Params

chat_external_id:
required
string
Chat ID on the source platform.
source_language:
required
string
Source language of the message.
target_language:
required
string
Target language to translate the message to.
text:
required
string
The message text to translate. The format of this field should conform with text_format.
text_format:
required
string
Format of the message text. Either html or text.
external_id:
required
string
Message ID in the source platform. This has to identify the message uniquely within the chat.
callback_url:
string
URL to where the response is sent.
brand:
string
Optional. Brand ID on the source platform.
brand_external_name:
string
Optional. A human readable name for the brand provided
agent_external_id:
string
Optional. ID of the agent serving the chat on the source platform. Should be the email of the agent.
is_inbound:
boolean
Optional. Indicates if a message is inbound to an agent. The message direction in relation to the agent is defined by the author of the message, as such a message created by an agent is outbound (field must be false.) A message created by a customer is inbound (field must be true).
author_external_id:
string
Optional. User ID of the author of the message. Maps to the external ID of the agent for outbound messages or the customer for inbound messages. When an agent should be the email of the agent.
# Request a Chat Translation A translation is only possible over a message, which must belong to a chat. As such, a chat must have one or more messages, and messages must have one translation. All of them are created using this endpoint. Chats are created whenever the `chat_external_id` is new, and messages are created when the `external_id` is new for a specific chat. Check the example below: [block:parameters] { "data": { "h-0": "chat_external_id", "h-1": "external_id", "h-2": "Actions", "h-3": "Status code", "0-0": "1", "1-0": "1", "2-0": "1", "3-0": "2", "0-1": "1", "1-1": "2", "2-1": "2", "3-1": "1", "0-2": "Chat and message are created", "1-2": "Message is created, and associated with chat 1", "2-2": "Chat and message are not created", "3-2": "Chat and message are created, but the chat is different from above", "0-3": "201", "1-3": "201", "2-3": "200", "3-3": "201" }, "cols": 4, "rows": 4 } [/block] This means that this endpoint is idempotent. You can reuse the same call to request translations and to check them (and the chat and message entities). The source language or a translation refers to the original language of the text to be translated, while the target language indicates the language to translate to. The source and target languages are tied to the message direction (inbound vs outbound): * for an inbound message, the customer language will be the source and the agent language will be the target; * for an outbound message, the agent language will be the source and the customer language will be the target. This endpoint will only get or create the chat and message entities, and not updating them. ## Scenarios _Successful scenarios_ [block:parameters] { "data": { "h-0": "Scenario", "h-1": "Status code", "0-1": "201", "1-1": "201", "2-1": "200", "0-0": "New chat and message", "1-0": "Existing chat and new message", "2-0": "Existing chat and message" }, "cols": 2, "rows": 3 } [/block] _Failure scenarios_ [block:parameters] { "data": { "h-0": "Scenario", "h-1": "Status code", "h-2": "Error", "h-3": "How to recover", "0-0": "Invalid payload", "1-0": "Invalid subscription", "2-0": "Server error", "0-1": "400", "1-1": "402", "2-1": "5xx", "0-2": "`validation_error`", "1-2": "`invalid_subscription`", "2-2": "`server_error`", "0-3": "Check the payload. Error message should have more information.", "2-3": "Repeat the call, since this endpoint is idempotent you can retry safely." }, "cols": 4, "rows": 3 } [/block] ## Receiving the translation You can receive the translation in two ways: 1. Through a callback URL that is used upon translation complete **(recommended)** 2. Long pooling the message using this endpoint or any other that where you can retrieve the message ### Through a webhook The service receiving the translations must return a response with the status code on the `2xx` range. _Sample call made when delivering:_ [block:code] { "codes": [ { "code": "> curl -X POST \\\\\n \"https://a-service.com/unbabel-webhook\" \\ \n -H \"content-type: application/json\" \\\n -H \"ce-type: com.unbabel.chat-api.v2\" \\\n -H \"ce-time: 2021-01-01T10:00:00.263865\" \\\n -H \"ce-specversion: 1.0\" \\\n -H \"ce-source: https://chat-api.unbabel.com\" \\\n -H \"ce-id: chatapi-6037f8cccfc375315c29266b\" \\\n -H \"ce-datacontenttype: application/json\" \\\n --data-binary '{\n \"chat\": {\n \"id\": \"6037f8cccfc375315c292660\",\n \"creation_date\": \"2021-01-01T10:00:00\",\n \"external_id\": \"1\",\n \"agent_external_id\": null,\n \"brand\": null\n },\n \"message\": {\n \"id\": \"6037f8cccfc375315c29266b\",\n \"author_external_id\": null,\n \"callback_url\": \"https://a-service.com/unbabel-webhook\",\n \"chat_id\": \"6037f8cccfc375315c292660\",\n \"completion_date\": \"2021-01-01T10:00:00.589829\",\n \"creation_date\": \"2021-01-01T10:00:01.867000\",\n \"external_id\": \"1\",\n \"translated_text\": \"Olá, mundo\",\n \"is_inbound\": null,\n \"source_language\": \"en\",\n \"status\": \"deliver_init\",\n \"target_language\": \"pt\",\n \"text\": \"hello world\",\n \"text_format\": \"text\",\n \"translation_uid\": \"chatapi-6037f8cccfc375315c29266b\"\n }\n }'\n", "language": "shell" } ] } [/block]

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



# Request a Chat Translation A translation is only possible over a message, which must belong to a chat. As such, a chat must have one or more messages, and messages must have one translation. All of them are created using this endpoint. Chats are created whenever the `chat_external_id` is new, and messages are created when the `external_id` is new for a specific chat. Check the example below: [block:parameters] { "data": { "h-0": "chat_external_id", "h-1": "external_id", "h-2": "Actions", "h-3": "Status code", "0-0": "1", "1-0": "1", "2-0": "1", "3-0": "2", "0-1": "1", "1-1": "2", "2-1": "2", "3-1": "1", "0-2": "Chat and message are created", "1-2": "Message is created, and associated with chat 1", "2-2": "Chat and message are not created", "3-2": "Chat and message are created, but the chat is different from above", "0-3": "201", "1-3": "201", "2-3": "200", "3-3": "201" }, "cols": 4, "rows": 4 } [/block] This means that this endpoint is idempotent. You can reuse the same call to request translations and to check them (and the chat and message entities). The source language or a translation refers to the original language of the text to be translated, while the target language indicates the language to translate to. The source and target languages are tied to the message direction (inbound vs outbound): * for an inbound message, the customer language will be the source and the agent language will be the target; * for an outbound message, the agent language will be the source and the customer language will be the target. This endpoint will only get or create the chat and message entities, and not updating them. ## Scenarios _Successful scenarios_ [block:parameters] { "data": { "h-0": "Scenario", "h-1": "Status code", "0-1": "201", "1-1": "201", "2-1": "200", "0-0": "New chat and message", "1-0": "Existing chat and new message", "2-0": "Existing chat and message" }, "cols": 2, "rows": 3 } [/block] _Failure scenarios_ [block:parameters] { "data": { "h-0": "Scenario", "h-1": "Status code", "h-2": "Error", "h-3": "How to recover", "0-0": "Invalid payload", "1-0": "Invalid subscription", "2-0": "Server error", "0-1": "400", "1-1": "402", "2-1": "5xx", "0-2": "`validation_error`", "1-2": "`invalid_subscription`", "2-2": "`server_error`", "0-3": "Check the payload. Error message should have more information.", "2-3": "Repeat the call, since this endpoint is idempotent you can retry safely." }, "cols": 4, "rows": 3 } [/block] ## Receiving the translation You can receive the translation in two ways: 1. Through a callback URL that is used upon translation complete **(recommended)** 2. Long pooling the message using this endpoint or any other that where you can retrieve the message ### Through a webhook The service receiving the translations must return a response with the status code on the `2xx` range. _Sample call made when delivering:_ [block:code] { "codes": [ { "code": "> curl -X POST \\\\\n \"https://a-service.com/unbabel-webhook\" \\ \n -H \"content-type: application/json\" \\\n -H \"ce-type: com.unbabel.chat-api.v2\" \\\n -H \"ce-time: 2021-01-01T10:00:00.263865\" \\\n -H \"ce-specversion: 1.0\" \\\n -H \"ce-source: https://chat-api.unbabel.com\" \\\n -H \"ce-id: chatapi-6037f8cccfc375315c29266b\" \\\n -H \"ce-datacontenttype: application/json\" \\\n --data-binary '{\n \"chat\": {\n \"id\": \"6037f8cccfc375315c292660\",\n \"creation_date\": \"2021-01-01T10:00:00\",\n \"external_id\": \"1\",\n \"agent_external_id\": null,\n \"brand\": null\n },\n \"message\": {\n \"id\": \"6037f8cccfc375315c29266b\",\n \"author_external_id\": null,\n \"callback_url\": \"https://a-service.com/unbabel-webhook\",\n \"chat_id\": \"6037f8cccfc375315c292660\",\n \"completion_date\": \"2021-01-01T10:00:00.589829\",\n \"creation_date\": \"2021-01-01T10:00:01.867000\",\n \"external_id\": \"1\",\n \"translated_text\": \"Olá, mundo\",\n \"is_inbound\": null,\n \"source_language\": \"en\",\n \"status\": \"deliver_init\",\n \"target_language\": \"pt\",\n \"text\": \"hello world\",\n \"text_format\": \"text\",\n \"translation_uid\": \"chatapi-6037f8cccfc375315c29266b\"\n }\n }'\n", "language": "shell" } ] } [/block]
{"_id":"6070a9615442d50041d40fab","metadata":{"image":[],"title":"","description":""},"api":{"url":"/v2/chats/:chat_id/messages/:message_id","auth":"required","settings":"5b7e91941bf4b60003e65fc6","results":{"codes":[{"name":"","code":"{\n  \"chat\": {\n    \"id\": \"59142b06684059a779224563\",\n    \"agent_external_id\": \"[email protected]\",\n    \"brand\": \"default-brand\",\n    \"creation_date\": \"2021-01-22T18:37:08.185156\",\n    \"external_id\": \"1\"\n  },\n  \"message\": {\n    \"id\": \"598c26f86840598e7614faac\",\n    \"author_external_id\": \"[email protected]\",\n    \"callback_url\": \"https://a-service.com/unbabel-webhook\",\n    \"chat_id\": \"59142b06684059a779224563\",\n    \"creation_date\": \"2021-01-22T18:37:08.185199\",\n    \"completion_date\": \"2021-01-22T18:37:09.589829\",\n    \"external_id\": \"1\",\n    \"is_inbound\": false,\n    \"source_language\": \"pt\",\n    \"status\": \"deliver_complete\",\n    \"target_language\": \"en\",\n    \"text\": \"Hello world\",\n    \"text_format\": \"text\",\n    \"translated_text\": \"Olá, mundo\",\n    \"translation_uid\": \"chatapi-598c26f86840598e7614faac\"\n  }\n}","language":"json","status":200},{"name":"","code":"{\"error\": \"Missing or incorrect authentication credentials.\"}","language":"json","status":401},{"code":"","language":"text","status":403},{"code":"","language":"text","status":404}]},"params":[{"name":"chat_id","type":"string","default":"","desc":"ID of the chat returned from the original POST to create a chat and a message","required":true,"in":"path","ref":"","_id":"6070a9615442d50041d40fac"},{"name":"message_id","type":"string","default":"","desc":"ID of the message returned from the original POST to create a chat and a message","required":true,"in":"path","ref":"","_id":"6070a9615442d50041d40fad"}],"examples":{"codes":[{"code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://chat-api.unbabel.com/v2/chats/:chat_id/messages/:message_id","language":"shell"}]},"method":"get"},"next":{"description":"","pages":[]},"title":"/v2/chats/:chat_id/messages/:message_id","type":"get","slug":"v2chatschat_idmessagesmessage_id","excerpt":"","body":"# Retrieve message\n\nYou can use this endpoint to retrieve a single message based on its id.\n\nThis endpoint will only return the message entity.","updates":[],"order":1,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"createdAt":"2021-04-09T19:22:09.757Z","user":"5f2035316dda9a0045002588","category":"5b7e90665a0e4e0003a41e68","version":"54afb7160cf42a0b001d5bf0","project":"54ad6c769219922100751763","__v":1,"parentDoc":null,"childrenPages":[]}

get/v2/chats/:chat_id/messages/:message_id


Path Params

chat_id:
required
string
ID of the chat returned from the original POST to create a chat and a message
message_id:
required
string
ID of the message returned from the original POST to create a chat and a message
# Retrieve message You can use this endpoint to retrieve a single message based on its id. This endpoint will only return the message entity.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



# Retrieve message You can use this endpoint to retrieve a single message based on its id. This endpoint will only return the message entity.
{"_id":"60a40ebc340ca8000fb6d34b","metadata":{"image":[],"title":"","description":""},"api":{"url":"/v2/chats/:chat_id/messages","auth":"required","settings":"5b7e91941bf4b60003e65fc6","results":{"codes":[{"name":"","code":"{\n  \"next_page\": null,\n  \"messages\": [\n    {\n    \t\"id\": \"598c26f86840598e7614faac\",\n    \t\"author_external_id\": \"[email protected]\",\n    \t\"callback_url\": \"https://a-service.com/unbabel-webhook\",\n    \t\"chat_id\": \"59142b06684059a779224563\",\n    \t\"creation_date\": \"2021-01-22T18:37:08.185199\",\n    \t\"completion_date\": \"2021-01-22T18:37:09.589829\",\n    \t\"external_id\": \"1\",\n    \t\"is_inbound\": false,\n    \t\"source_language\": \"pt\",\n    \t\"status\": \"deliver_complete\",\n    \t\"target_language\": \"en\",\n    \t\"text\": \"Hello world\",\n    \t\"text_format\": \"text\",\n    \t\"translated_text\": \"Olá, mundo\",\n    \t\"translation_uid\": \"chatapi-598c26f86840598e7614faac\"\n  \t}\n\t]\n}","language":"json","status":200},{"name":"","code":"{\"error\": \"Missing or incorrect authentication credentials.\"}","language":"json","status":401},{"code":"","language":"text","status":403},{"code":"","language":"text","status":404}]},"params":[{"name":"chat_id","type":"string","default":"","desc":"Chat ID on the source platform or the ID of the chat returned from the original POST to create a chat and a message.","required":true,"in":"path","ref":"","_id":"6070a9615442d50041d40fac"},{"name":"created_at__lte","type":"datetime","default":"","desc":"Optional. Use this to filter messages based on their creation date. This parameter is used for pagination.","required":false,"in":"query","ref":"","_id":"60a40ebc340ca8000fb6d34d"}],"examples":{"codes":[{"code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://chat-api.unbabel.com/v2/chats/:chat_id/messages","language":"shell"}]},"method":"get"},"next":{"description":"","pages":[]},"title":"/v2/chats/:chat_id/messages","type":"get","slug":"v2chatschat_idmessages","excerpt":"","body":"# List chat translations\n\nYou can use this endpoint to list all the translations for a chat.\n\nThe listing is paginated, using the created datetime as the cursor (you can\nuse the `next_page` field to navigate to the next page) and a\nmaximum number of 25 results are returned at each iteration.","updates":[],"order":2,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"createdAt":"2021-05-18T19:00:12.246Z","user":"5f2035316dda9a0045002588","category":"5b7e90665a0e4e0003a41e68","version":"54afb7160cf42a0b001d5bf0","project":"54ad6c769219922100751763","__v":4,"parentDoc":null,"childrenPages":[]}

get/v2/chats/:chat_id/messages


Path Params

chat_id:
required
string
Chat ID on the source platform or the ID of the chat returned from the original POST to create a chat and a message.

Query Params

created_at__lte:
datetime
Optional. Use this to filter messages based on their creation date. This parameter is used for pagination.
# List chat translations You can use this endpoint to list all the translations for a chat. The listing is paginated, using the created datetime as the cursor (you can use the `next_page` field to navigate to the next page) and a maximum number of 25 results are returned at each iteration.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



# List chat translations You can use this endpoint to list all the translations for a chat. The listing is paginated, using the created datetime as the cursor (you can use the `next_page` field to navigate to the next page) and a maximum number of 25 results are returned at each iteration.
{"_id":"5b7eb3a6b3e2d40003c97d0b","project":"54ad6c769219922100751763","version":"54afb7160cf42a0b001d5bf0","category":"5b7e90665a0e4e0003a41e68","user":"5b7e81a6b3e2d40003c97887","updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-08-23T13:16:22.826Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"method":"post","examples":{"codes":[{"language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X POST https://chat-api.unbabel.com/chats \\\n        -d '{\n                \"brand\": \"default-brand\" (optional),\n                \"external_id\": \"external-id\" (optional),\n                \"agent_external_id\": \"[email protected]\" (optional)\n            }'\n"}]},"results":{"codes":[{"status":200,"language":"json","code":"{\n    \"chat_id\":\"59142b06684059a779224563\",\n    \"created_at\": \"2017-05-15 23:20:09\",\n    \"external_id\": \"external-id\",\n    \"agent_external_id\": \"[email protected]\"\n}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"5b7e91941bf4b60003e65fc6","auth":"required","params":[{"name":"brand","type":"string","default":"","desc":"Brand ID on the source platform.","required":false,"in":"body","ref":"","_id":"5f84a57e6b0e27006159bd77"},{"name":"brand_external_name","type":"string","default":"","desc":"A human readable name for the brand provided.","required":false,"in":"body","ref":"","_id":"6092ed343eb057006d3df7a6"},{"name":"external_id","type":"string","default":"","desc":"Chat ID on the source platform.","required":false,"in":"body","ref":"","_id":"5f9afd7999e8d50018f3e6e5"},{"name":"agent_external_id","type":"string","default":"","desc":"ID of the agent serving the chat on the source platform. Should be the email of the agent.","required":false,"in":"body","ref":"","_id":"5f9afd7999e8d50018f3e6e4"}],"url":"/chats"},"isReference":false,"order":3,"body":"","excerpt":"Create a chat","slug":"chats","type":"post","title":"/chats/","__v":5,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

post/chats/

Create a chat

Body Params

brand:
string
Brand ID on the source platform.
brand_external_name:
string
A human readable name for the brand provided.
external_id:
string
Chat ID on the source platform.
agent_external_id:
string
ID of the agent serving the chat on the source platform. Should be the email of the agent.

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"_id":"5b7ebf4347fe1c00035456d5","project":"54ad6c769219922100751763","version":"54afb7160cf42a0b001d5bf0","category":"5b7e90665a0e4e0003a41e68","user":"5b7e81a6b3e2d40003c97887","updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-08-23T14:05:55.985Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"method":"get","examples":{"codes":[{"language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://chat-api.unbabel.com/chats/:chat_id/messages"}]},"results":{"codes":[{"status":200,"language":"json","code":"{\n    \"length\": <number of chat messages>,\n\t  \"messages\": [\n      <list of messages of the chat>\n    ],\n    \"index\": 1,\n    \"limit\": 50\n}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"5b7e91941bf4b60003e65fc6","auth":"required","params":[{"name":":limit","type":"int","default":"50","desc":"Limit the number of results","required":false,"in":"query","ref":"","_id":"5b7ec0368326280003545459"},{"name":":index","type":"int","default":"1","desc":"Results from a certain index","required":false,"in":"query","ref":"","_id":"5b7ec0368326280003545458"},{"name":":chat_id","type":"string","default":"","desc":"ID returned from the original POST to create a chat","required":true,"in":"path","ref":"","_id":"5b7ec4c41bf4b60003e665eb"}],"url":"/chats/:chat_id/messages"},"isReference":false,"order":4,"body":"","excerpt":"List chat messages","slug":"chatschat_idmessages","type":"get","title":"/chats/:chat_id/messages","__v":12,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

get/chats/:chat_id/messages

List chat messages

Path Params

chat_id:
required
string
ID returned from the original POST to create a chat

Query Params

limit:
integer50
Limit the number of results
index:
integer1
Results from a certain index

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"_id":"5b7ec6c947fe1c0003545765","project":"54ad6c769219922100751763","version":"54afb7160cf42a0b001d5bf0","category":"5b7e90665a0e4e0003a41e68","user":"5b7e81a6b3e2d40003c97887","updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-08-23T14:38:01.356Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"method":"post","examples":{"codes":[{"language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X POST https://chat-api.unbabel.com/chats/:chat_id/messages \\\n        -d '{\n                \"text\": \"Hello world\",\n                \"source_language\": \"en\",\n                \"target_language\": \"pt\",\n                \"callback_url\": \"https://callback.com\",\n                \"max_time_out\": 100,\n                \"uid\": \"unique-identifier\" (optional),\n                \"text_format\": \"text\" (optional),\n                \"external_id\": \"external-id\" (optional),\n                \"author_external_id\": \"[email protected]\" (optional),\n                \"is_inbound\": false (optional)\n\t\t\t\t\t\t}'"}]},"results":{"codes":[{"status":200,"language":"json","code":"{\n    \"status\": \"mt_init\",\n    \"text\": \"Third message\",\n    \"source_language\": \"en\",\n    \"qe_value\": 1,\n    \"message_id\": \"598c26f86840598e7614faac\",\n    \"creation_date\": \"2017-08-10 09:27:20.569000\",\n    \"callback\": \"https://callback.com\",\n    \"chat_id\": \"598c26686840598e7614faa9\",\n    \"original_number_words\": 2,\n    \"sla\": \"2017-08-11 09:27:20.569000\",\n    \"target_language\": \"pt\",\n    \"external_id\": \"external-id\",\n    \"author_external_id\": \"[email protected]\",\n    \"is_inbound\": false\n}","name":""},{"status":400,"language":"json","code":"{\"error\": \"Message does not belong to chat\"}","name":""},{"status":401,"language":"text","code":"{\"error\": \"Missing or incorrect authentication credentials.\"}"},{"status":403,"language":"text","code":"{\"error\": \"Unauthorized access\"}"},{"status":404,"language":"shell","code":"{\"error\": \"Resource not found\"}"}]},"settings":"5b7e91941bf4b60003e65fc6","auth":"required","params":[{"name":":chat_id","type":"string","default":"","desc":"ID returned from the original POST to create a chat","required":true,"in":"path","ref":"","_id":"5b7ec6c947fe1c000354576f"},{"name":"text","type":"string","default":"","desc":"Message Text","required":true,"in":"body","ref":"","_id":"5b7ec6c947fe1c000354576c"},{"name":"source_language","type":"string","default":"","desc":"Source language of the message","required":true,"in":"body","ref":"","_id":"5b7ec6c947fe1c000354576b"},{"name":"target_language","type":"string","default":"","desc":"Target language to translate the message to","required":true,"in":"body","ref":"","_id":"5b7ec6c947fe1c000354576a"},{"name":"callback_url","type":"string","default":"","desc":"URL to where the response is sent","required":true,"in":"body","ref":"","_id":"5b7ec6c947fe1c0003545769"},{"name":"max_time_out","type":"int","default":"","desc":"Maximum time (in seconds) to translate for an eventual automatic upgraded message","required":true,"in":"body","ref":"","_id":"5b7ec6c947fe1c0003545768"},{"name":"uid","type":"string","default":"","desc":"UID of message","required":false,"in":"body","ref":"","_id":"5b7ec6c947fe1c0003545766"},{"name":"text_format","type":"string","default":"","desc":"Format of the message text. Either `html` or `text`","required":false,"in":"body","ref":"","_id":"5f84a3d94a4556022cc5b2b5"},{"name":"external_id","type":"string","default":"","desc":"Message ID in the source platform","required":false,"in":"body","ref":"","_id":"5f9afe2a7f6fb2005c6a68ce"},{"name":"author_external_id","type":"string","default":"","desc":"User ID of the author of the message. Maps to the external ID of the agent for outbound messages or the customer for inbound messages. When an agent should be the email of the agent","required":false,"in":"body","ref":"","_id":"5faae2fe8d1cec0035cc4e6c"},{"name":"is_inbound","type":"boolean","default":"","desc":"Indicates if a message is inbound. The direction is defined by the author of the message, as such a message created by an agent is outbound (field must be `false`). A message created by a customer is inbound (field must be `true`)","required":false,"in":"body","ref":"","_id":"5faae2fe8d1cec0035cc4e6b"}],"url":"/chats/:chat_id/messages"},"isReference":false,"order":5,"body":"","excerpt":"Create a message on the given chat","slug":"chatschat_idmessages-1","type":"post","title":"/chats/:chat_id/messages","__v":18,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

post/chats/:chat_id/messages

Create a message on the given chat

Path Params

chat_id:
required
string
ID returned from the original POST to create a chat

Body Params

text:
required
string
Message Text
source_language:
required
string
Source language of the message
target_language:
required
string
Target language to translate the message to
callback_url:
required
string
URL to where the response is sent
max_time_out:
required
integer
Maximum time (in seconds) to translate for an eventual automatic upgraded message
uid:
string
UID of message
text_format:
string
Format of the message text. Either `html` or `text`
external_id:
string
Message ID in the source platform
author_external_id:
string
User ID of the author of the message. Maps to the external ID of the agent for outbound messages or the customer for inbound messages. When an agent should be the email of the agent
is_inbound:
boolean
Indicates if a message is inbound. The direction is defined by the author of the message, as such a message created by an agent is outbound (field must be `false`). A message created by a customer is inbound (field must be `true`)

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"_id":"5b7ec77c1bf4b60003e66627","project":"54ad6c769219922100751763","version":"54afb7160cf42a0b001d5bf0","category":"5b7e90665a0e4e0003a41e68","user":"5b7e81a6b3e2d40003c97887","updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-08-23T14:41:00.806Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{\n    \"status\": \"deliver_complete\",\n    \"message_id\": \"5a38faa9684059a54cca5b17\",\n    \"machine_translation\": \"Olá Mundo\",\n    \"text\": \"Hello world\",\n    \"qe_threshold\": 0.7,\n    \"source_language\": \"en\",\n    \"qe_value\": 1,\n    \"completion_date\": \"2017-12-19 11:40:29.263000\",\n    \"creation_date\": \"2017-12-19 11:40:25.393000\",\n    \"final_text\": \"Olá Mundo\",\n    \"callback\": \"https://callback.com\",\n    \"translation_uid\": \"73e8639064\",\n    \"translation_type\": \"mt\",\n    \"chat_id\": \"5a38fa5f684059a2f51671df\",\n    \"ht_timed_out\": false,\n    \"original_number_words\": 2,\n    \"sla\": \"2017-12-19 11:42:05.393000\",\n    \"target_language\": \"pt\",\n    \"external_id\": \"external-id\",\n    \"author_external_id\": \"[email protected]\",\n    \"is_inbound\": false\n}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"5b7e91941bf4b60003e65fc6","auth":"required","params":[{"name":":chat_id","type":"string","default":"","desc":"ID returned from the original POST to create a chat","required":true,"in":"path","ref":"","_id":"5b7ec8a48326280003545543"},{"name":":message_id","type":"string","default":"","desc":"ID returned from the original POST to create a message","required":true,"in":"path","ref":"","_id":"5b7ec8a48326280003545542"}],"url":"/chats/:chat_id/messages/:message_id","examples":{"codes":[{"language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://chat-api.unbabel.com/chats/:chat_id/messages/:message_id"}]},"method":"get"},"isReference":false,"order":6,"body":"","excerpt":"Get the given message from the chat","slug":"chatschat_idmessagesmessage_id","type":"get","title":"/chats/:chat_id/messages/:message_id","__v":6,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

get/chats/:chat_id/messages/:message_id

Get the given message from the chat

Path Params

chat_id:
required
string
ID returned from the original POST to create a chat
message_id:
required
string
ID returned from the original POST to create a message

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"_id":"5eaab24c9e6d46004bee9da5","metadata":{"image":[],"title":"","description":""},"api":{"url":"/tickets/translate","auth":"required","settings":"5eaab1568ee37d00209d5c89","results":{"codes":[{"name":"","code":"{\n  \"ticket\": {\n    \"id\": \"02b82af8-24b2-41e6-a73b-ec38aa929c2e\",\n    \"external_id\": \"1\",\n    \"created_at\": \"2020-02-06T18:37:08.185156\",\n    \"updated_at\": \"2020-02-06T18:37:08.202556\",\n    \"brand_external_id\": \"1\",\n    \"agent_language_id\": \"en\",\n    \"agent_external_id\": \"843\",\n    \"active\": true,\n    \"customer_language_id\": \"pt\"\n  },\n  \"message\": {\n    \"id\": \"c7f32b37-2bdc-460a-ac16-d4e7445dda5b\",\n    \"ticket_id\": \"02b82af8-24b2-41e6-a73b-ec38aa929c2e\",\n    \"external_id\": \"1\",\n    \"body\": \"Hello world\",\n    \"inbound\": true,\n    \"body_format\": \"text\",\n    \"subject\": null,\n    \"language_id\": \"pt\",\n    \"author_external_id\": \"678320\",\n    \"created_at\": \"2020-05-04T09:08:06.558922\",\n    \"updated_at\": \"2020-05-04T09:08:06.567889\"\n  },\n  \"translation\": {\n    \"id\": \"b2e0b583-2052-4f5f-a725-4aa23154da13\",\n    \"message_id\": \"c7f32b37-2bdc-460a-ac16-d4e7445dda5b\",\n    \"source_language_id\": \"pt\",\n    \"target_language_id\": \"en\",\n    \"mode\": \"mt\",\n    \"state\": \"delivered\",\n    \"subject\": null,\n    \"body\": \"Olá mundo\",\n    \"upgraded_from_id\": null,\n    \"created_at\": \"2020-05-04T09:08:06.572751\",\n    \"updated_at\": \"2020-05-04T09:08:08.455628\"\n  }\n}","language":"json","status":200},{"code":"{\n  \"ticket\": {\n    \"id\": \"02b82af8-24b2-41e6-a73b-ec38aa929c2e\",\n    \"external_id\": \"1\",\n    \"created_at\": \"2020-02-06T18:37:08.185156\",\n    \"updated_at\": \"2020-02-06T18:37:08.202556\",\n    \"brand_external_id\": \"1\",\n    \"agent_language_id\": \"en\",\n    \"agent_external_id\": \"843\",\n    \"active\": true,\n    \"customer_language_id\": \"pt\"\n  },\n  \"message\": {\n    \"id\": \"c7f32b37-2bdc-460a-ac16-d4e7445dda5b\",\n    \"ticket_id\": \"02b82af8-24b2-41e6-a73b-ec38aa929c2e\",\n    \"external_id\": \"1\",\n    \"body\": \"Hello world\",\n    \"inbound\": true,\n    \"body_format\": \"text\",\n    \"subject\": null,\n    \"language_id\": \"pt\",\n    \"author_external_id\": \"678320\",\n    \"created_at\": \"2020-05-04T09:08:06.558922\",\n    \"updated_at\": \"2020-05-04T09:08:06.567889\"\n  },\n  \"translation\": {\n    \"id\": \"b2e0b583-2052-4f5f-a725-4aa23154da13\",\n    \"message_id\": \"c7f32b37-2bdc-460a-ac16-d4e7445dda5b\",\n    \"source_language_id\": \"pt\",\n    \"target_language_id\": \"en\",\n    \"mode\": \"mt\",\n    \"state\": \"translating\",\n    \"subject\": null,\n    \"body\": null,\n    \"upgraded_from_id\": null,\n    \"created_at\": \"2020-05-04T09:08:06.572751\",\n    \"updated_at\": \"2020-05-04T09:08:06.572751\"\n  }\n}","language":"json","status":201},{"code":"{\n  \"error\": \"validation_error\",\n  \"description\": \"Invalid payload\",\n  \"localized_description\": \"Invalid payload\",\n  \"details\": [\n    {\n      \"type\": \"value_error.missing\",\n      \"location\": [\n        \"agent_language_id\"\n      ],\n      \"description\": \"field required\"\n    }\n  ]\n}","language":"json","status":422,"name":"Validation Error"},{"code":"{\n  \"error\": \"inactive_ticket\",\n  \"description\": \"Translation requests are only possible on active tickets\",\n  \"localized_description\": \"Translation requests are only possible on active tickets\",\n  \"details\": null\n}","language":"json","status":400,"name":"Inactive ticket"},{"code":"{\n  \"error\": \"invalid_subscription\",\n  \"description\": \"You don't have a valid subscription to request this translation\",\n  \"localized_description\": \"You don't have a valid subscription to request this translation\",\n  \"details\": [\n    {\n      \"source_language_id\": \"pt\",\n      \"target_language_id\": \"en\"\n    }\n  ]\n}","language":"json","status":402,"name":"Invalid subscription"},{"code":"{\n  \"error\": \"unauthorized\",\n  \"description\": \"Unauthorized authentication\",\n  \"localized_description\": \"Unauthorized authentication\",\n  \"details\": null\n}","language":"json","status":401},{"code":"{\n  \"error\": \"missing_authentication\",\n  \"description\": \"Authentication credentials were not found\",\n  \"localized_description\": \"Authentication credentials were not found\",\n  \"details\": null\n}","language":"json","status":403}]},"params":[{"name":"ticket_external_id","type":"string","default":"","desc":"Required. Ticket ID on the source platform.","required":false,"in":"body","ref":"","_id":"5eaab61306be540060a31f28"},{"name":"brand_external_id","type":"string","default":"","desc":"Required. Brand ID on the source platform.","required":false,"in":"body","ref":"","_id":"5eaab61306be540060a31f27"},{"name":"brand_external_name","type":"string","default":"\"\"","desc":"Optional. A human readable name for the brand_external_id provided","required":false,"in":"body","ref":"","_id":"5ffc31eb3a0d1900474485b6"},{"name":"agent_external_id","type":"string","default":"","desc":"Required. ID of the agent serving the ticket on the source platform. Should be the email of the agent.","required":false,"in":"body","ref":"","_id":"5eaab61306be540060a31f26"},{"name":"message_body","type":"string","default":"","desc":"Required. The message body to translate. The format of this field should conform with `message_body_format`.","required":false,"in":"body","ref":"","_id":"5eaab61306be540060a31f24"},{"name":"message_body_format","type":"string","default":"","desc":"Required. Format of the message body. Either `xliff`, `html` or `text`","required":false,"in":"body","ref":"","_id":"5eaab61306be540060a31f23"},{"name":"message_inbound","type":"string","default":"","desc":"Required. Indicates if a message is inbound. The direction is defined by the author of the message, as such a message created by an agent is **outbound** (field must be `false`.) A message created by a customer is **inbound** (field must be `true`)","required":false,"in":"body","ref":"","_id":"5eaab61306be540060a31f22"},{"name":"message_author_external_id","type":"string","default":"","desc":"Required. User ID of the author of the message. Maps to the external ID of **the agent for outbound** messages or **the customer for inbound** messages. When an agent should be the email of the agent","required":false,"in":"body","ref":"","_id":"5eaab61306be540060a31f21"},{"name":"message_external_id","type":"string","default":"","desc":"Required. Message ID in the source platform. This has to identify the message uniquely within the ticket","required":false,"in":"body","ref":"","_id":"5eaab61306be540060a31f20"},{"name":"agent_language_id","type":"string","default":"","desc":"Optional. Language that the agent is speaking. This field is optional for new outbound messages, in this case the agent language will be identified.  For **inbound messages, this field is required**.","required":false,"in":"body","ref":"","_id":"5eaab61306be540060a31f25"},{"name":"customer_language_id","type":"string","default":"","desc":"Optional. Language that the customer is speaking. This field is optional for new tickets created from inbound messages, in this case the customer language will be identified.  For **tickets created from outbound messages, this field is required**.  For existing tickets the customer language to use will be the one of the ticket.","required":false,"in":"body","ref":"","_id":"5eaab61306be540060a31f1f"},{"name":"message_template_external_id","type":"string","default":"","desc":"Optional. References to the template that generated the message/translation request","required":false,"in":"body","ref":"","_id":"5eaab61306be540060a31f1e"},{"name":"message_subject","type":"string","default":"","desc":"Optional. as not all platforms support messages with subjects. When provided it'll be used for language detection (when applicable,) and will be used translated","required":false,"in":"body","ref":"","_id":"5eaab61306be540060a31f1d"},{"name":"installation_id","type":"string","default":"\"\"","desc":"Use this field to specify an installation. Typically a platform unique URL such as \"unbabel.zendesk.com\" or \"unbabel.freshdesk.com\"","required":false,"in":"body","ref":"","_id":"5fbbd76377abcb00335fdef7"}],"examples":{"codes":[{"code":"#!/bin/bash\ncurl \"https://tickets.unbabel.com/api/v1/tickets/translate\" \\\n    -X POST \\\n    -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n    -H \"Content-Type: application/json\" \\\n    --data '{\n      \"installation_id\": \"crm.unbabel.com\",\n    \t\"ticket_external_id\": \"1\",\n      \"brand_external_id\": \"customer-facing-brand\",\n      \"agent_external_id\": \"[email protected]\",\n      \"agent_language_id\": \"en\",\n      \"message_body\": \"this is a test\",\n      \"message_body_format\": \"text\",\n      \"message_inbound\": true,\n      \"message_author_external_id\": \"678320\",\n      \"message_external_id\": \"1\"\n    }'","language":"shell"}]},"method":"post"},"next":{"description":"","pages":[]},"title":"/tickets/translate","type":"post","slug":"ticket_translate","excerpt":"","body":"# Request a Ticket Translation\n\nA translation is only possible over a message, which must belong to a ticket. As such, a ticket must have one or more messages, and messages must have one or more translations. All of them are created using this endpoint.\n\nTickets are created whenever the `ticket_external_id` is new, and messages are created when the `message_external_id` is new for a specific ticket. Check the example below\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"ticket_external_id\",\n    \"h-1\": \"message_external_id\",\n    \"h-2\": \"Actions\",\n    \"h-3\": \"Status code\",\n    \"0-0\": \"1\",\n    \"0-1\": \"1\",\n    \"1-0\": \"1\",\n    \"1-1\": \"2\",\n    \"2-0\": \"1\",\n    \"2-1\": \"2\",\n    \"3-0\": \"2\",\n    \"3-1\": \"1\",\n    \"0-2\": \"Ticket and message are created\",\n    \"1-2\": \"Message is created, and associated with ticket 1\",\n    \"2-2\": \"Ticket and message are not created\",\n    \"3-2\": \"Ticket and message are created, but the ticket is different from above\",\n    \"0-3\": \"201\",\n    \"1-3\": \"201\",\n    \"2-3\": \"200\",\n    \"3-3\": \"201\"\n  },\n  \"cols\": 4,\n  \"rows\": 4\n}\n[/block]\nThis means that **this endpoint is idempotent**. **You can reuse the same call to request translations and to check them (and the ticket and message entities.)**\n\nTranslation entities are idempotent too. For each message, there can only be one translation for a certain source and target language. The **source language** or a translation refers to the original language of the text to be translated, while the **target language** indicates the language to translate to.\n\n\nThe source and target languages are tied to the message direction (inbound vs outbound:)\n- for an **inbound message**, the customer language will be the source and the agent language will be the target;\n- for an **outbound message**, the agent language will be the source and the customer language will be the target.\n\nThis endpoint will only get or create the ticket, message and translation entities, and not updating them. Certain fields (marked with required) must always be provided but, some of them (such as `agent_language_id` and `customer_language_id`,) will only be used upon creation, even if there was a change in between calls.\n\nThis means that the agent and customer languages that will be used for every translation request will be set on the first translation request, or after you update the customer and agent language of the ticket. Check the [Partially Update a Ticket Section.]()\n\n\n### Detecting the language of a ticket message\n\nIf the `customer_language_id` is not known in advance, you can omit or set the field to `null` and we'll perform language identification over the source content. \n\nThis action is accurate, but fallible. Specially for short or ambiguous content. If the language is misidentified, you can update the ticket's customer language, for that check the `PATCH /tickets/:ticket_id`.\n\n## Scenarios\n\n_Successful scenarios_\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Scenario\",\n    \"h-1\": \"Status code\",\n    \"0-0\": \"New ticket, message, and translation\",\n    \"0-1\": \"201\",\n    \"1-0\": \"Existing ticket and message, new translation\",\n    \"1-1\": \"201\",\n    \"2-0\": \"Existing ticket, new message and translation\",\n    \"2-1\": \"201\",\n    \"3-0\": \"Existing ticket, message, and translation\",\n    \"3-1\": \"200\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n_Failure scenarios_\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Scenario\",\n    \"h-1\": \"Status code\",\n    \"h-2\": \"Error\",\n    \"h-3\": \"How to recover\",\n    \"0-0\": \"Invalid payload\",\n    \"0-1\": \"422\",\n    \"0-2\": \"`validation_error`\",\n    \"0-3\": \"Check the payload. `details` and `description` should have more information\",\n    \"1-0\": \"Customer language wasn’t provided, or couldn’t be inferred\",\n    \"1-1\": \"400\",\n    \"1-2\": \"`client_error`\",\n    \"1-3\": \"Provide a customer language\",\n    \"2-0\": \"Translation of an inactive ticket\",\n    \"2-1\": \"400\",\n    \"2-2\": \"`inactive_error`\",\n    \"2-3\": \"If necessary, update ticket (`active=true`) and repeat the call\",\n    \"3-0\": \"Invalid subscription\",\n    \"3-1\": \"402\",\n    \"3-2\": \"`invalid_subscription`\",\n    \"3-3\": \"\",\n    \"4-0\": \"Server error\",\n    \"4-1\": \"5xx\",\n    \"4-2\": \"`server_error`\",\n    \"4-3\": \"Repeat the call, since this endpoint is idempotent you can retry safely\"\n  },\n  \"cols\": 4,\n  \"rows\": 5\n}\n[/block]\n## Receiving the translation\n\nYou can receive the translation in two ways:\n1. Through a webhook that is fired upon translation complete **(recommended)**\n2. Long pooling the translation using this endpoint or any other that where you can retrieve the translation\n\n### Through a webhook\nThe webhook needs to be registered beforehand using the [/configurations](https://developers.unbabel.com/docs/configurations-1) endpoint. There you're able to specify a callback endpoint. No templating is yet allowed on the URL.\n\nThe service receiving the translations must return a response with the status code on the `2xx` range.\n\nYou can provide a shared key which we’ll use to sign the payload (HMAC’s SHA1) and send the signature on the header (`X-Signature`).\n\n_Sample call from made when delivering:_\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"> curl -X POST \\\\\\\\\\n    \\\"https://a-service.com/unbabel-webhook\\\" \\\\\\n    -H \\\"X-Signature: ...\\\" \\\\\\n    -H \\\"Content-Type: application/json\\\" \\\\\\n    --data-binary '{\\n      \\\"topic\\\": \\\"translation-complete\\\",\\n      \\\"fired_at\\\": \\\"2020-01-21T20:58:17.092262\\\",\\n      \\\"ticket\\\": { ... ticket payload },\\n      \\\"message\\\": { ... message payload },\\n      \\\"translation\\\": { ... translation payload }\\n    }'\\n\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]","updates":[],"order":0,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"createdAt":"2020-04-30T11:11:08.548Z","user":"5eaaaf35d0cd6d0012523bdf","category":"5eaab032c8f6eb0061090008","version":"54afb7160cf42a0b001d5bf0","project":"54ad6c769219922100751763","__v":34,"parentDoc":null,"childrenPages":[]}

post/tickets/translate


Body Params

ticket_external_id:
string
Required. Ticket ID on the source platform.
brand_external_id:
string
Required. Brand ID on the source platform.
brand_external_name:
string""
Optional. A human readable name for the brand_external_id provided
agent_external_id:
string
Required. ID of the agent serving the ticket on the source platform. Should be the email of the agent.
message_body:
string
Required. The message body to translate. The format of this field should conform with `message_body_format`.
message_body_format:
string
Required. Format of the message body. Either `xliff`, `html` or `text`
message_inbound:
string
Required. Indicates if a message is inbound. The direction is defined by the author of the message, as such a message created by an agent is **outbound** (field must be `false`.) A message created by a customer is **inbound** (field must be `true`)
message_author_external_id:
string
Required. User ID of the author of the message. Maps to the external ID of **the agent for outbound** messages or **the customer for inbound** messages. When an agent should be the email of the agent
message_external_id:
string
Required. Message ID in the source platform. This has to identify the message uniquely within the ticket
agent_language_id:
string
Optional. Language that the agent is speaking. This field is optional for new outbound messages, in this case the agent language will be identified. For **inbound messages, this field is required**.
customer_language_id:
string
Optional. Language that the customer is speaking. This field is optional for new tickets created from inbound messages, in this case the customer language will be identified. For **tickets created from outbound messages, this field is required**. For existing tickets the customer language to use will be the one of the ticket.
message_template_external_id:
string
Optional. References to the template that generated the message/translation request
message_subject:
string
Optional. as not all platforms support messages with subjects. When provided it'll be used for language detection (when applicable,) and will be used translated
installation_id:
string""
Use this field to specify an installation. Typically a platform unique URL such as "unbabel.zendesk.com" or "unbabel.freshdesk.com"
# Request a Ticket Translation A translation is only possible over a message, which must belong to a ticket. As such, a ticket must have one or more messages, and messages must have one or more translations. All of them are created using this endpoint. Tickets are created whenever the `ticket_external_id` is new, and messages are created when the `message_external_id` is new for a specific ticket. Check the example below [block:parameters] { "data": { "h-0": "ticket_external_id", "h-1": "message_external_id", "h-2": "Actions", "h-3": "Status code", "0-0": "1", "0-1": "1", "1-0": "1", "1-1": "2", "2-0": "1", "2-1": "2", "3-0": "2", "3-1": "1", "0-2": "Ticket and message are created", "1-2": "Message is created, and associated with ticket 1", "2-2": "Ticket and message are not created", "3-2": "Ticket and message are created, but the ticket is different from above", "0-3": "201", "1-3": "201", "2-3": "200", "3-3": "201" }, "cols": 4, "rows": 4 } [/block] This means that **this endpoint is idempotent**. **You can reuse the same call to request translations and to check them (and the ticket and message entities.)** Translation entities are idempotent too. For each message, there can only be one translation for a certain source and target language. The **source language** or a translation refers to the original language of the text to be translated, while the **target language** indicates the language to translate to. The source and target languages are tied to the message direction (inbound vs outbound:) - for an **inbound message**, the customer language will be the source and the agent language will be the target; - for an **outbound message**, the agent language will be the source and the customer language will be the target. This endpoint will only get or create the ticket, message and translation entities, and not updating them. Certain fields (marked with required) must always be provided but, some of them (such as `agent_language_id` and `customer_language_id`,) will only be used upon creation, even if there was a change in between calls. This means that the agent and customer languages that will be used for every translation request will be set on the first translation request, or after you update the customer and agent language of the ticket. Check the [Partially Update a Ticket Section.]() ### Detecting the language of a ticket message If the `customer_language_id` is not known in advance, you can omit or set the field to `null` and we'll perform language identification over the source content. This action is accurate, but fallible. Specially for short or ambiguous content. If the language is misidentified, you can update the ticket's customer language, for that check the `PATCH /tickets/:ticket_id`. ## Scenarios _Successful scenarios_ [block:parameters] { "data": { "h-0": "Scenario", "h-1": "Status code", "0-0": "New ticket, message, and translation", "0-1": "201", "1-0": "Existing ticket and message, new translation", "1-1": "201", "2-0": "Existing ticket, new message and translation", "2-1": "201", "3-0": "Existing ticket, message, and translation", "3-1": "200" }, "cols": 2, "rows": 4 } [/block] _Failure scenarios_ [block:parameters] { "data": { "h-0": "Scenario", "h-1": "Status code", "h-2": "Error", "h-3": "How to recover", "0-0": "Invalid payload", "0-1": "422", "0-2": "`validation_error`", "0-3": "Check the payload. `details` and `description` should have more information", "1-0": "Customer language wasn’t provided, or couldn’t be inferred", "1-1": "400", "1-2": "`client_error`", "1-3": "Provide a customer language", "2-0": "Translation of an inactive ticket", "2-1": "400", "2-2": "`inactive_error`", "2-3": "If necessary, update ticket (`active=true`) and repeat the call", "3-0": "Invalid subscription", "3-1": "402", "3-2": "`invalid_subscription`", "3-3": "", "4-0": "Server error", "4-1": "5xx", "4-2": "`server_error`", "4-3": "Repeat the call, since this endpoint is idempotent you can retry safely" }, "cols": 4, "rows": 5 } [/block] ## Receiving the translation You can receive the translation in two ways: 1. Through a webhook that is fired upon translation complete **(recommended)** 2. Long pooling the translation using this endpoint or any other that where you can retrieve the translation ### Through a webhook The webhook needs to be registered beforehand using the [/configurations](https://developers.unbabel.com/docs/configurations-1) endpoint. There you're able to specify a callback endpoint. No templating is yet allowed on the URL. The service receiving the translations must return a response with the status code on the `2xx` range. You can provide a shared key which we’ll use to sign the payload (HMAC’s SHA1) and send the signature on the header (`X-Signature`). _Sample call from made when delivering:_ [block:code] { "codes": [ { "code": "> curl -X POST \\\\\n \"https://a-service.com/unbabel-webhook\" \\\n -H \"X-Signature: ...\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary '{\n \"topic\": \"translation-complete\",\n \"fired_at\": \"2020-01-21T20:58:17.092262\",\n \"ticket\": { ... ticket payload },\n \"message\": { ... message payload },\n \"translation\": { ... translation payload }\n }'\n", "language": "shell" } ] } [/block]

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



# Request a Ticket Translation A translation is only possible over a message, which must belong to a ticket. As such, a ticket must have one or more messages, and messages must have one or more translations. All of them are created using this endpoint. Tickets are created whenever the `ticket_external_id` is new, and messages are created when the `message_external_id` is new for a specific ticket. Check the example below [block:parameters] { "data": { "h-0": "ticket_external_id", "h-1": "message_external_id", "h-2": "Actions", "h-3": "Status code", "0-0": "1", "0-1": "1", "1-0": "1", "1-1": "2", "2-0": "1", "2-1": "2", "3-0": "2", "3-1": "1", "0-2": "Ticket and message are created", "1-2": "Message is created, and associated with ticket 1", "2-2": "Ticket and message are not created", "3-2": "Ticket and message are created, but the ticket is different from above", "0-3": "201", "1-3": "201", "2-3": "200", "3-3": "201" }, "cols": 4, "rows": 4 } [/block] This means that **this endpoint is idempotent**. **You can reuse the same call to request translations and to check them (and the ticket and message entities.)** Translation entities are idempotent too. For each message, there can only be one translation for a certain source and target language. The **source language** or a translation refers to the original language of the text to be translated, while the **target language** indicates the language to translate to. The source and target languages are tied to the message direction (inbound vs outbound:) - for an **inbound message**, the customer language will be the source and the agent language will be the target; - for an **outbound message**, the agent language will be the source and the customer language will be the target. This endpoint will only get or create the ticket, message and translation entities, and not updating them. Certain fields (marked with required) must always be provided but, some of them (such as `agent_language_id` and `customer_language_id`,) will only be used upon creation, even if there was a change in between calls. This means that the agent and customer languages that will be used for every translation request will be set on the first translation request, or after you update the customer and agent language of the ticket. Check the [Partially Update a Ticket Section.]() ### Detecting the language of a ticket message If the `customer_language_id` is not known in advance, you can omit or set the field to `null` and we'll perform language identification over the source content. This action is accurate, but fallible. Specially for short or ambiguous content. If the language is misidentified, you can update the ticket's customer language, for that check the `PATCH /tickets/:ticket_id`. ## Scenarios _Successful scenarios_ [block:parameters] { "data": { "h-0": "Scenario", "h-1": "Status code", "0-0": "New ticket, message, and translation", "0-1": "201", "1-0": "Existing ticket and message, new translation", "1-1": "201", "2-0": "Existing ticket, new message and translation", "2-1": "201", "3-0": "Existing ticket, message, and translation", "3-1": "200" }, "cols": 2, "rows": 4 } [/block] _Failure scenarios_ [block:parameters] { "data": { "h-0": "Scenario", "h-1": "Status code", "h-2": "Error", "h-3": "How to recover", "0-0": "Invalid payload", "0-1": "422", "0-2": "`validation_error`", "0-3": "Check the payload. `details` and `description` should have more information", "1-0": "Customer language wasn’t provided, or couldn’t be inferred", "1-1": "400", "1-2": "`client_error`", "1-3": "Provide a customer language", "2-0": "Translation of an inactive ticket", "2-1": "400", "2-2": "`inactive_error`", "2-3": "If necessary, update ticket (`active=true`) and repeat the call", "3-0": "Invalid subscription", "3-1": "402", "3-2": "`invalid_subscription`", "3-3": "", "4-0": "Server error", "4-1": "5xx", "4-2": "`server_error`", "4-3": "Repeat the call, since this endpoint is idempotent you can retry safely" }, "cols": 4, "rows": 5 } [/block] ## Receiving the translation You can receive the translation in two ways: 1. Through a webhook that is fired upon translation complete **(recommended)** 2. Long pooling the translation using this endpoint or any other that where you can retrieve the translation ### Through a webhook The webhook needs to be registered beforehand using the [/configurations](https://developers.unbabel.com/docs/configurations-1) endpoint. There you're able to specify a callback endpoint. No templating is yet allowed on the URL. The service receiving the translations must return a response with the status code on the `2xx` range. You can provide a shared key which we’ll use to sign the payload (HMAC’s SHA1) and send the signature on the header (`X-Signature`). _Sample call from made when delivering:_ [block:code] { "codes": [ { "code": "> curl -X POST \\\\\n \"https://a-service.com/unbabel-webhook\" \\\n -H \"X-Signature: ...\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary '{\n \"topic\": \"translation-complete\",\n \"fired_at\": \"2020-01-21T20:58:17.092262\",\n \"ticket\": { ... ticket payload },\n \"message\": { ... message payload },\n \"translation\": { ... translation payload }\n }'\n", "language": "shell" } ] } [/block]
{"_id":"5eab0ded7cd692004153e513","metadata":{"image":[],"title":"","description":""},"api":{"url":"/tickets/","auth":"required","settings":"5eaab1568ee37d00209d5c89","results":{"codes":[{"name":"","code":"{\n  \"next_page\": \"https://tickets.unbabel.com/api/v1/tickets?created_at__lte=2020-03-24+12%3A47%3A48.862606\",\n  \"tickets\": [\n    {\n      \"id\": \"02b82af8-24b2-41e6-a73b-ec38aa929c2e\",\n      \"external_id\": \"1\",\n      \"created_at\": \"2020-02-06T18:37:08.185156\",\n      \"updated_at\": \"2020-02-06T18:37:08.202556\",\n      \"brand_external_id\": \"1\",\n      \"agent_language_id\": \"en\",\n      \"agent_external_id\": \"843\",\n      \"active\": true,\n      \"customer_language_id\": \"pt\"\n    }\n  ]\n}","language":"json","status":200},{"code":"{\n  \"error\": \"unauthorized\",\n  \"description\": \"Unauthorized authentication\",\n  \"localized_description\": \"Unauthorized authentication\",\n  \"details\": null\n}","language":"json","status":401},{"code":"{\n  \"error\": \"missing_authentication\",\n  \"description\": \"Authentication credentials were not found\",\n  \"localized_description\": \"Authentication credentials were not found\",\n  \"details\": null\n}","language":"json","status":403}]},"params":[{"name":"external_id","type":"string","default":"","desc":"Optional. Ticket id on the source platform.","required":false,"in":"query","ref":"","_id":"5eab0f57ad1461005372af88"},{"name":"active","type":"string","default":"","desc":"Optional. Indicates if translations can be requested over the ticket","required":false,"in":"query","ref":"","_id":"5eab0f57ad1461005372af87"},{"name":"brand_external_id","type":"string","default":"","desc":"Optional. Brand ID on the source platform.","required":false,"in":"query","ref":"","_id":"5eab0f57ad1461005372af86"},{"name":"agent_external_id","type":"string","default":"","desc":"Optional. ID of the agent serving the ticket on the source platform. Should be the email of the agent.","required":false,"in":"query","ref":"","_id":"5eab0f57ad1461005372af85"},{"name":"agent_language_id","type":"string","default":"","desc":"Optional. Language that the agent is speaking.","required":false,"in":"query","ref":"","_id":"5eab0f57ad1461005372af84"},{"name":"customer_language_id","type":"string","default":"","desc":"Optional. Language that the customer is speaking.","required":false,"in":"query","ref":"","_id":"5eab0f57ad1461005372af83"},{"name":"created_at__gt","type":"datetime","default":"","desc":"Optional. Use this to filter tickets based on their creation date. This parameter is used for pagination.","required":false,"in":"query","ref":"","_id":"5eaff3579149b900738d5ea6"},{"name":"installation_id","type":"string","default":"","desc":"Optional. Use this to filter tickets that belong a specified installation","required":false,"in":"query","ref":"","_id":"5fbbff34b04eab005b673272"}],"examples":{"codes":[{"code":"#!/bin/bash\ncurl \"https://tickets.unbabel.com/api/v1/tickets\" \\\n    -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\"","language":"shell"}]},"method":"get"},"next":{"description":"","pages":[]},"title":"/tickets/","type":"get","slug":"list_tickets","excerpt":"","body":"# List Tickets\n\nYou can use this endpoint to list all of a customer's tickets.\n\nThe listing is paginated, using the created datetime as the cursor (you can\nuse the `next_page` field to navigate to the next page) and a\nmaximum number of 25 results are returned at each iteration.\n\nIf the customer has not yet requested a translation, an empty list will be returned.\n\nIt's also possible to filter the results returned. This is useful\nif you want to list tickets that:\n  - belong to a specific agent\n  - belong to a specific brand\n  - have a certain agent or customer languages\n  - have a certain external id\n  - are active\n  - belong to a specific installation","updates":[],"order":1,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"createdAt":"2020-04-30T17:42:05.702Z","user":"5eaaaf35d0cd6d0012523bdf","category":"5eaab032c8f6eb0061090008","version":"54afb7160cf42a0b001d5bf0","project":"54ad6c769219922100751763","__v":14,"parentDoc":null,"childrenPages":[]}

get/tickets/


Query Params

external_id:
string
Optional. Ticket id on the source platform.
active:
string
Optional. Indicates if translations can be requested over the ticket
brand_external_id:
string
Optional. Brand ID on the source platform.
agent_external_id:
string
Optional. ID of the agent serving the ticket on the source platform. Should be the email of the agent.
agent_language_id:
string
Optional. Language that the agent is speaking.
customer_language_id:
string
Optional. Language that the customer is speaking.
created_at__gt:
datetime
Optional. Use this to filter tickets based on their creation date. This parameter is used for pagination.
installation_id:
string
Optional. Use this to filter tickets that belong a specified installation
# List Tickets You can use this endpoint to list all of a customer's tickets. The listing is paginated, using the created datetime as the cursor (you can use the `next_page` field to navigate to the next page) and a maximum number of 25 results are returned at each iteration. If the customer has not yet requested a translation, an empty list will be returned. It's also possible to filter the results returned. This is useful if you want to list tickets that: - belong to a specific agent - belong to a specific brand - have a certain agent or customer languages - have a certain external id - are active - belong to a specific installation

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



# List Tickets You can use this endpoint to list all of a customer's tickets. The listing is paginated, using the created datetime as the cursor (you can use the `next_page` field to navigate to the next page) and a maximum number of 25 results are returned at each iteration. If the customer has not yet requested a translation, an empty list will be returned. It's also possible to filter the results returned. This is useful if you want to list tickets that: - belong to a specific agent - belong to a specific brand - have a certain agent or customer languages - have a certain external id - are active - belong to a specific installation
{"_id":"5eab10a1ee3825006775466e","metadata":{"image":[],"title":"","description":""},"api":{"url":"/tickets/:ticket_id/","auth":"required","settings":"5eaab1568ee37d00209d5c89","results":{"codes":[{"name":"","code":"{\n  \"id\": \"02b82af8-24b2-41e6-a73b-ec38aa929c2e\",\n  \"external_id\": \"1\",\n  \"created_at\": \"2020-02-06T18:37:08.185156\",\n  \"updated_at\": \"2020-02-06T18:37:08.202556\",\n  \"brand_external_id\": \"1\",\n  \"agent_language_id\": \"en\",\n  \"agent_external_id\": \"843\",\n  \"active\": true,\n  \"customer_language_id\": \"pt\"\n}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400},{"code":"{\n  \"error\": \"not_found\",\n  \"description\": \"Ticket not found\",\n  \"localized_description\": \"Ticket not found\",\n  \"details\": null\n}","language":"json","status":404},{"code":"{\n  \"error\": \"unauthorized\",\n  \"description\": \"Unauthorized authentication\",\n  \"localized_description\": \"Unauthorized authentication\",\n  \"details\": null\n}","language":"json","status":401},{"code":"{\n  \"error\": \"missing_authentication\",\n  \"description\": \"Authentication credentials were not found\",\n  \"localized_description\": \"Authentication credentials were not found\",\n  \"details\": null\n}","language":"json","status":403}]},"params":[{"name":"ticket_id","type":"string","default":"","desc":"Unbabel ticket id","required":false,"in":"path","ref":"","_id":"5eab10a1ee3825006775466f"}],"examples":{"codes":[{"code":"#!/bin/bash\ncurl \"https://tickets.unbabel.com/api/v1/tickets/02b82af8-24b2-41e6-a73b-ec38aa929c2e\" \\\n    -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\"","language":"shell"}]},"method":"get"},"next":{"description":"","pages":[]},"title":"/tickets/:ticket_id/","type":"get","slug":"retrieve_ticket","excerpt":"","body":"# Retrieve ticket\n\nYou can use this endpoint to retrieve a single ticket based on its id.\n\nThis endpoint will only return the ticket entity.\n\nTo create a ticket check the `POST /tickets/translate`.","updates":[],"order":2,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"createdAt":"2020-04-30T17:53:37.855Z","user":"5eaaaf35d0cd6d0012523bdf","category":"5eaab032c8f6eb0061090008","version":"54afb7160cf42a0b001d5bf0","project":"54ad6c769219922100751763","__v":10,"parentDoc":null,"childrenPages":[]}

get/tickets/:ticket_id/


Path Params

ticket_id:
string
Unbabel ticket id
# Retrieve ticket You can use this endpoint to retrieve a single ticket based on its id. This endpoint will only return the ticket entity. To create a ticket check the `POST /tickets/translate`.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



# Retrieve ticket You can use this endpoint to retrieve a single ticket based on its id. This endpoint will only return the ticket entity. To create a ticket check the `POST /tickets/translate`.
{"_id":"5eab10edc49d73002d5dc24b","metadata":{"image":[],"title":"","description":""},"api":{"url":"/tickets/:ticket_id/","auth":"required","settings":"5eaab1568ee37d00209d5c89","results":{"codes":[{"name":"","code":"{\n  \"id\": \"02b82af8-24b2-41e6-a73b-ec38aa929c2e\",\n  \"external_id\": \"1\",\n  \"created_at\": \"2020-02-06T18:37:08.185156\",\n  \"updated_at\": \"2020-02-06T18:40:34.217292\",\n  \"brand_external_id\": \"1\",\n  \"agent_language_id\": \"en\",\n  \"agent_external_id\": \"843\",\n  \"active\": true,\n  \"customer_language_id\": \"pt-br\"\n}","language":"json","status":200},{"name":"Invalid payload","code":"{\n  \"error\": \"validation_error\",\n  \"description\": \"Invalid payload\",\n  \"localized_description\": \"Invalid payload\",\n  \"details\": [\n    {\n      \"type\": \"value_error.extra\",\n      \"location\": [\n        \"brand_external_id\"\n      ],\n      \"description\": \"extra fields not permitted\"\n    }\n  ]\n}","language":"json","status":422},{"code":"{\n  \"error\": \"not_found\",\n  \"description\": \"Ticket not found\",\n  \"localized_description\": \"Ticket not found\",\n  \"details\": null\n}","language":"json","status":404},{"code":"{\n  \"error\": \"unauthorized\",\n  \"description\": \"Unauthorized authentication\",\n  \"localized_description\": \"Unauthorized authentication\",\n  \"details\": null\n}","language":"json","status":401},{"code":"{\n  \"error\": \"missing_authentication\",\n  \"description\": \"Authentication credentials were not found\",\n  \"localized_description\": \"Authentication credentials were not found\",\n  \"details\": null\n}","language":"json","status":403}]},"params":[{"name":"ticket_id","type":"string","default":"","desc":"Unbabel ticket id","required":false,"in":"path","ref":"","_id":"5eab10edc49d73002d5dc24c"},{"name":"active","type":"boolean","default":"","desc":"Optional. Set this to update the ticket's active state.","required":false,"in":"body","ref":"","_id":"5eafebfc6346aa01ecf70d2b"},{"name":"agent_external_id","type":"string","default":"","desc":"Optional. Set this to update the ticket `agent_external_id`.","required":false,"in":"body","ref":"","_id":"5eafebfc6346aa01ecf70d2a"},{"name":"agent_language_id","type":"string","default":"","desc":"Optional. Set this to update the `agent_language_id`.","required":false,"in":"body","ref":"","_id":"5eafebfc6346aa01ecf70d29"},{"name":"customer_language_id","type":"string","default":"","desc":"Optional. Set this to update the `customer_language_id`.","required":false,"in":"body","ref":"","_id":"5eafebfc6346aa01ecf70d28"}],"examples":{"codes":[{"code":"#!/bin/bash\ncurl \"https://tickets.unbabel.com/api/v1/tickets/02b82af8-24b2-41e6-a73b-ec38aa929c2e\" \\\n    -X PATCH \\\n    -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n    --data '{\n      \"customer_language_id\": \"pt-br\"\n    }'","language":"shell"}]},"method":"patch"},"next":{"description":"","pages":[]},"title":"/tickets/:ticket_id/","type":"patch","slug":"update_ticket","excerpt":"","body":"# Partially update ticket\n\nUse this endpoint to update the ticket metadata:\n- `active`\n- `agent_external_id`\n- `agent_language_id`\n- `customer_language_id`\n\nNote that, if you change the agent or customer languages, **no new translations will be requested.** If you which to translate a ticket and it's messages based on the language changes, you'll need to call the `POST /tickets/translate/` again with the message content.","updates":[],"order":3,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"createdAt":"2020-04-30T17:54:53.693Z","user":"5eaaaf35d0cd6d0012523bdf","category":"5eaab032c8f6eb0061090008","version":"54afb7160cf42a0b001d5bf0","project":"54ad6c769219922100751763","__v":10,"parentDoc":null,"childrenPages":[]}

patch/tickets/:ticket_id/


Path Params

ticket_id:
string
Unbabel ticket id

Body Params

active:
boolean
Optional. Set this to update the ticket's active state.
agent_external_id:
string
Optional. Set this to update the ticket `agent_external_id`.
agent_language_id:
string
Optional. Set this to update the `agent_language_id`.
customer_language_id:
string
Optional. Set this to update the `customer_language_id`.
# Partially update ticket Use this endpoint to update the ticket metadata: - `active` - `agent_external_id` - `agent_language_id` - `customer_language_id` Note that, if you change the agent or customer languages, **no new translations will be requested.** If you which to translate a ticket and it's messages based on the language changes, you'll need to call the `POST /tickets/translate/` again with the message content.

User Information

Try It Out

patch
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



# Partially update ticket Use this endpoint to update the ticket metadata: - `active` - `agent_external_id` - `agent_language_id` - `customer_language_id` Note that, if you change the agent or customer languages, **no new translations will be requested.** If you which to translate a ticket and it's messages based on the language changes, you'll need to call the `POST /tickets/translate/` again with the message content.
{"_id":"5eab115136cd930033ebd288","metadata":{"image":[],"title":"","description":""},"api":{"url":"/tickets/:ticket_id/messages/","auth":"required","settings":"5eaab1568ee37d00209d5c89","results":{"codes":[{"name":"","code":"{\n  \"next_page\": null,\n  \"messages\": [\n    {\n      \"id\": \"c7f32b37-2bdc-460a-ac16-d4e7445dda5b\",\n      \"ticket_id\": \"02b82af8-24b2-41e6-a73b-ec38aa929c2e\",\n      \"external_id\": \"1\",\n      \"body\": \"Hello world\",\n      \"inbound\": true,\n      \"body_format\": \"text\",\n      \"subject\": null,\n      \"language_id\": \"pt\",\n      \"author_external_id\": \"678320\",\n      \"created_at\": \"2020-05-04T09:08:06.558922\",\n      \"updated_at\": \"2020-05-04T09:08:06.567889\"\n    }\n  ]\n}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400},{"code":"{\n  \"error\": \"not_found\",\n  \"description\": \"Message not found\",\n  \"localized_description\": \"Message not found\",\n  \"details\": null\n}","language":"json","status":404},{"code":"{\n  \"error\": \"unauthorized\",\n  \"description\": \"Unauthorized authentication\",\n  \"localized_description\": \"Unauthorized authentication\",\n  \"details\": null\n}","language":"json","status":401},{"code":"{\n  \"error\": \"missing_authentication\",\n  \"description\": \"Authentication credentials were not found\",\n  \"localized_description\": \"Authentication credentials were not found\",\n  \"details\": null\n}","language":"json","status":403}]},"params":[{"name":"ticket_id","type":"string","default":"","desc":"Ticket id","required":false,"in":"path","ref":"","_id":"5eafee7e36fe600011f29ab0"},{"name":"external_id","type":"string","default":"","desc":"Optional. Use this to filter the messages based on `external_id`.","required":false,"in":"query","ref":"","_id":"5eafee7e36fe600011f29aaf"},{"name":"inbound","type":"boolean","default":"","desc":"Optional. Use this to filter the messages based on whether or not their inbound (`true`) or outbound `false`.","required":false,"in":"query","ref":"","_id":"5eafee7e36fe600011f29aae"},{"name":"language_id","type":"string","default":"","desc":"Optional. Use this to filter the messages based on their language","required":false,"in":"query","ref":"","_id":"5eafee7e36fe600011f29aad"},{"name":"created_at__lte","type":"datetime","default":"","desc":"Optional. Use this to filter messages based on their creation date. This parameter is used for pagination.","required":false,"in":"query","ref":"","_id":"5eafee7e36fe600011f29aac"}],"examples":{"codes":[{"code":"#!/bin/bash\ncurl \"https://tickets.unbabel.com/api/v1/tickets/02b82af8-24b2-41e6-a73b-ec38aa929c2e/messages\" \\\n    -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\"","language":"shell"}]},"method":"get"},"next":{"description":"","pages":[]},"title":"/tickets/:ticket_id/messages/","type":"get","slug":"list_ticket_messages","excerpt":"","body":"# List messages\n\nYou can use this endpoint to list all the messages whithin a ticket.\n\nThe listing is paginated, using the created datetime as the cursor (you can\nuse the `next_page` field to navigate to the next page) and a\nmaximum number of 25 results are returned at each iteration.\n\nIf the customer has not yet requested a translation, an empty list will be returned.\n\nIt's possible to filter the results returned. This is useful\nif you want to list messages that:\n  - are either inbound or outbound\n  - have a certain language\n  - have a certain external id","updates":[],"order":4,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"createdAt":"2020-04-30T17:56:33.266Z","user":"5eaaaf35d0cd6d0012523bdf","category":"5eaab032c8f6eb0061090008","version":"54afb7160cf42a0b001d5bf0","project":"54ad6c769219922100751763","__v":8,"parentDoc":null,"childrenPages":[]}

get/tickets/:ticket_id/messages/


Path Params

ticket_id:
string
Ticket id

Query Params

external_id:
string
Optional. Use this to filter the messages based on `external_id`.
inbound:
boolean
Optional. Use this to filter the messages based on whether or not their inbound (`true`) or outbound `false`.
language_id:
string
Optional. Use this to filter the messages based on their language
created_at__lte:
datetime
Optional. Use this to filter messages based on their creation date. This parameter is used for pagination.
# List messages You can use this endpoint to list all the messages whithin a ticket. The listing is paginated, using the created datetime as the cursor (you can use the `next_page` field to navigate to the next page) and a maximum number of 25 results are returned at each iteration. If the customer has not yet requested a translation, an empty list will be returned. It's possible to filter the results returned. This is useful if you want to list messages that: - are either inbound or outbound - have a certain language - have a certain external id

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



# List messages You can use this endpoint to list all the messages whithin a ticket. The listing is paginated, using the created datetime as the cursor (you can use the `next_page` field to navigate to the next page) and a maximum number of 25 results are returned at each iteration. If the customer has not yet requested a translation, an empty list will be returned. It's possible to filter the results returned. This is useful if you want to list messages that: - are either inbound or outbound - have a certain language - have a certain external id
{"_id":"5eab1184aadc8b0047a6d7f7","metadata":{"image":[],"title":"","description":""},"api":{"url":"/tickets/:ticket_id/messages/:message_id/","auth":"required","settings":"5eaab1568ee37d00209d5c89","results":{"codes":[{"name":"","code":"{\n  \"id\": \"c7f32b37-2bdc-460a-ac16-d4e7445dda5b\",\n  \"ticket_id\": \"02b82af8-24b2-41e6-a73b-ec38aa929c2e\",\n  \"external_id\": \"1\",\n  \"body\": \"Hello world\",\n  \"inbound\": true,\n  \"body_format\": \"text\",\n  \"subject\": null,\n  \"language_id\": \"pt\",\n  \"author_external_id\": \"678320\",\n  \"created_at\": \"2020-05-04T09:08:06.558922\",\n  \"updated_at\": \"2020-05-04T09:08:06.567889\"\n}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400},{"code":"{\n  \"error\": \"not_found\",\n  \"description\": \"Message not found\",\n  \"localized_description\": \"Message not found\",\n  \"details\": null\n}","language":"json","status":404},{"code":"{\n  \"error\": \"unauthorized\",\n  \"description\": \"Unauthorized authentication\",\n  \"localized_description\": \"Unauthorized authentication\",\n  \"details\": null\n}","language":"json","status":401},{"code":"{\n  \"error\": \"missing_authentication\",\n  \"description\": \"Authentication credentials were not found\",\n  \"localized_description\": \"Authentication credentials were not found\",\n  \"details\": null\n}","language":"json","status":403}]},"params":[{"name":"ticket_id","type":"string","default":"","desc":"Ticket id","required":false,"in":"path","ref":"","_id":"5eaffbb5be143100431a10f6"},{"name":"message_id","type":"string","default":"","desc":"Message id","required":false,"in":"path","ref":"","_id":"5eaffbb5be143100431a10f5"}],"examples":{"codes":[{"code":"#!/bin/bash\ncurl \"https://tickets.unbabel.com/api/v1/tickets/02b82af8-24b2-41e6-a73b-ec38aa929c2e/messages/c7f32b37-2bdc-460a-ac16-d4e7445dda5b\" \\\n    -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\"","language":"shell"}]},"method":"get"},"next":{"description":"","pages":[]},"title":"/tickets/:ticket_id/messages/:message_id/","type":"get","slug":"retrieve_message","excerpt":"","body":"# Retrieve message\n\nYou can use this endpoint to retrieve a single message based on its id.\n\nThis endpoint will only return the message entity.","updates":[],"order":5,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"createdAt":"2020-04-30T17:57:24.700Z","user":"5eaaaf35d0cd6d0012523bdf","category":"5eaab032c8f6eb0061090008","version":"54afb7160cf42a0b001d5bf0","project":"54ad6c769219922100751763","__v":1,"parentDoc":null,"childrenPages":[]}

get/tickets/:ticket_id/messages/:message_id/


Path Params

ticket_id:
string
Ticket id
message_id:
string
Message id
# Retrieve message You can use this endpoint to retrieve a single message based on its id. This endpoint will only return the message entity.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



# Retrieve message You can use this endpoint to retrieve a single message based on its id. This endpoint will only return the message entity.
{"_id":"5eab11df21b34d002bc228bf","metadata":{"image":[],"title":"","description":""},"api":{"url":"/tickets/:ticket_id/messages/:message_id/translations/","auth":"required","settings":"5eaab1568ee37d00209d5c89","results":{"codes":[{"name":"","code":"{\n  \"next_page\": null,\n  \"translations\": [\n    {\n      \"id\": \"b2e0b583-2052-4f5f-a725-4aa23154da13\",\n      \"message_id\": \"c7f32b37-2bdc-460a-ac16-d4e7445dda5b\",\n      \"source_language_id\": \"pt\",\n      \"target_language_id\": \"en\",\n      \"mode\": \"mt\",\n      \"state\": \"delivered\",\n      \"subject\": null,\n      \"body\": \"Olá mundo\",\n      \"upgraded_from_id\": null,\n      \"created_at\": \"2020-05-04T09:08:06.572751\",\n      \"updated_at\": \"2020-05-04T09:08:08.455628\"\n    }\n  ]\n}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400},{"code":"{\n  \"error\": \"not_found\",\n  \"description\": \"Message not found\",\n  \"localized_description\": \"Message not found\",\n  \"details\": null\n}","language":"json","status":404},{"code":"{\n  \"error\": \"unauthorized\",\n  \"description\": \"Unauthorized authentication\",\n  \"localized_description\": \"Unauthorized authentication\",\n  \"details\": null\n}","language":"json","status":401},{"code":"{\n  \"error\": \"missing_authentication\",\n  \"description\": \"Authentication credentials were not found\",\n  \"localized_description\": \"Authentication credentials were not found\",\n  \"details\": null\n}","language":"json","status":403}]},"params":[{"name":"created_at__lte","type":"datetime","default":"","desc":"Optional. Use this to filter messages based on their creation date. This parameter is used for pagination.","required":false,"in":"query","ref":"","_id":"5eafefd4bd83550061383100"},{"name":"ticket_id","type":"string","default":"","desc":"Ticket id","required":false,"in":"path","ref":"","_id":"5eafefd4bd835500613830ff"},{"name":"message_id","type":"string","default":"","desc":"Message id","required":false,"in":"path","ref":"","_id":"5eafefd4bd835500613830fe"}],"examples":{"codes":[{"code":"#!/bin/bash\ncurl \"https://tickets.unbabel.com/api/v1/tickets/02b82af8-24b2-41e6-a73b-ec38aa929c2e/messages/c7f32b37-2bdc-460a-ac16-d4e7445dda5b/translations\" \\\n    -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\"","language":"shell"}]},"method":"get"},"next":{"description":"","pages":[]},"title":"/tickets/:ticket_id/messages/:message_id/translations/","type":"get","slug":"list_message_translations","excerpt":"","body":"# List message translations\n\nYou can use this endpoint to list all the translations for a message.\n\nThe listing is paginated, using the created datetime as the cursor (you can\nuse the `next_page` field to navigate to the next page) and a\nmaximum number of 25 results are returned at each iteration.\n\nIf the customer has not yet requested a translation, an empty list will be returned.","updates":[],"order":6,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"createdAt":"2020-04-30T17:58:55.215Z","user":"5eaaaf35d0cd6d0012523bdf","category":"5eaab032c8f6eb0061090008","version":"54afb7160cf42a0b001d5bf0","project":"54ad6c769219922100751763","__v":10,"parentDoc":null,"childrenPages":[]}

get/tickets/:ticket_id/messages/:message_id/translations/


Path Params

ticket_id:
string
Ticket id
message_id:
string
Message id

Query Params

created_at__lte:
datetime
Optional. Use this to filter messages based on their creation date. This parameter is used for pagination.
# List message translations You can use this endpoint to list all the translations for a message. The listing is paginated, using the created datetime as the cursor (you can use the `next_page` field to navigate to the next page) and a maximum number of 25 results are returned at each iteration. If the customer has not yet requested a translation, an empty list will be returned.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



# List message translations You can use this endpoint to list all the translations for a message. The listing is paginated, using the created datetime as the cursor (you can use the `next_page` field to navigate to the next page) and a maximum number of 25 results are returned at each iteration. If the customer has not yet requested a translation, an empty list will be returned.
{"_id":"5eab120e432ce500251dacd4","metadata":{"image":[],"title":"","description":""},"api":{"url":"/tickets/:ticket_id/messages/:message_id/translations/:translation_id/","auth":"required","settings":"5eaab1568ee37d00209d5c89","results":{"codes":[{"name":"","code":"{\n  \"id\": \"b2e0b583-2052-4f5f-a725-4aa23154da13\",\n  \"message_id\": \"c7f32b37-2bdc-460a-ac16-d4e7445dda5b\",\n  \"source_language_id\": \"pt\",\n  \"target_language_id\": \"en\",\n  \"mode\": \"mt\",\n  \"state\": \"delivered\",\n  \"subject\": null,\n  \"body\": \"Olá mundo\",\n  \"upgraded_from_id\": null,\n  \"created_at\": \"2020-05-04T09:08:06.572751\",\n  \"updated_at\": \"2020-05-04T09:08:08.455628\"\n}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400},{"code":"{\n  \"error\": \"not_found\",\n  \"description\": \"Translation not found\",\n  \"localized_description\": \"Translation not found\",\n  \"details\": null\n}","language":"json","status":404},{"code":"{\n  \"error\": \"unauthorized\",\n  \"description\": \"Unauthorized authentication\",\n  \"localized_description\": \"Unauthorized authentication\",\n  \"details\": null\n}","language":"json","status":401},{"code":"{\n  \"error\": \"missing_authentication\",\n  \"description\": \"Authentication credentials were not found\",\n  \"localized_description\": \"Authentication credentials were not found\",\n  \"details\": null\n}","language":"json","status":403}]},"params":[{"name":"ticket_id","type":"string","default":"","desc":"Ticket id","required":false,"in":"path","ref":"","_id":"5eaff052bd9759004b8f7429"},{"name":"message_id","type":"string","default":"","desc":"Message id","required":false,"in":"path","ref":"","_id":"5eaff052bd9759004b8f7428"},{"name":"translation_id","type":"string","default":"","desc":"Translation id","required":false,"in":"path","ref":"","_id":"5eaff052bd9759004b8f7427"}],"examples":{"codes":[{"code":"#!/bin/bash\ncurl \"https://tickets.unbabel.com/api/v1/tickets/02b82af8-24b2-41e6-a73b-ec38aa929c2e/messages/c7f32b37-2bdc-460a-ac16-d4e7445dda5b/translations/b2e0b583-2052-4f5f-a725-4aa23154da13\" \\\n    -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\"","language":"shell"}]},"method":"get"},"next":{"description":"","pages":[]},"title":"/tickets/:ticket_id/messages/:message_id/translations/:translation_id/","type":"get","slug":"retrieve_translation","excerpt":"","body":"# Retrieve translation\n\nYou can use this endpoint to retrieve a single translation based on its id.\n\nThis endpoint will only return the translation entity.","updates":[],"order":7,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"createdAt":"2020-04-30T17:59:42.654Z","user":"5eaaaf35d0cd6d0012523bdf","category":"5eaab032c8f6eb0061090008","version":"54afb7160cf42a0b001d5bf0","project":"54ad6c769219922100751763","__v":8,"parentDoc":null,"childrenPages":[]}

get/tickets/:ticket_id/messages/:message_id/translations/:translation_id/


Path Params

ticket_id:
string
Ticket id
message_id:
string
Message id
translation_id:
string
Translation id
# Retrieve translation You can use this endpoint to retrieve a single translation based on its id. This endpoint will only return the translation entity.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



# Retrieve translation You can use this endpoint to retrieve a single translation based on its id. This endpoint will only return the translation entity.
{"_id":"5eab12376fc28d00525652b3","metadata":{"image":[],"title":"","description":""},"api":{"url":"/tickets/:ticket_id/messages/:message_id/translations/:translation_id/upgrade","auth":"required","settings":"5eaab1568ee37d00209d5c89","results":{"codes":[{"name":"","code":"{\n  \"id\": \"e3a3cd74-3993-4731-aa58-1e68d8d796b2\",\n  \"message_id\": \"c7f32b37-2bdc-460a-ac16-d4e7445dda5b\",\n  \"source_language_id\": \"pt\",\n  \"target_language_id\": \"en\",\n  \"mode\": \"human\",\n  \"state\": \"translating\",\n  \"subject\": null,\n  \"body\": null,\n  \"upgraded_from_id\": \"b2e0b583-2052-4f5f-a725-4aa23154da13\",\n  \"created_at\": \"2020-05-04T10:46:13.966087\",\n  \"updated_at\": \"2020-05-04T10:46:14.982788\"\n}","language":"json","status":200},{"name":"","code":"{\n  \"error\": \"client_error\",\n  \"description\": \"Can't upgrade over human translations\",\n  \"localized_description\": \"Can't upgrade over human translations\",\n  \"details\": null\n}","language":"json","status":400},{"status":201,"code":"{\n  \"id\": \"e3a3cd74-3993-4731-aa58-1e68d8d796b2\",\n  \"message_id\": \"c7f32b37-2bdc-460a-ac16-d4e7445dda5b\",\n  \"source_language_id\": \"pt\",\n  \"target_language_id\": \"en\",\n  \"mode\": \"human\",\n  \"state\": \"translating\",\n  \"subject\": null,\n  \"body\": null,\n  \"upgraded_from_id\": \"b2e0b583-2052-4f5f-a725-4aa23154da13\",\n  \"created_at\": \"2020-05-04T10:46:13.966087\",\n  \"updated_at\": \"2020-05-04T10:46:14.982788\"\n}","language":"json"},{"code":"{\n  \"error\": \"not_found\",\n  \"description\": \"Translation not found\",\n  \"localized_description\": \"Translation not found\",\n  \"details\": null\n}","language":"json","status":404},{"code":"{\n  \"error\": \"unauthorized\",\n  \"description\": \"Unauthorized authentication\",\n  \"localized_description\": \"Unauthorized authentication\",\n  \"details\": null\n}","language":"json","status":401},{"code":"{\n  \"error\": \"missing_authentication\",\n  \"description\": \"Authentication credentials were not found\",\n  \"localized_description\": \"Authentication credentials were not found\",\n  \"details\": null\n}","language":"json","status":403}]},"params":[{"name":"ticket_id","type":"string","default":"","desc":"Ticket id","required":false,"in":"path","ref":"","_id":"5eaff1c2079597002af24d5d"},{"name":"message_id","type":"string","default":"","desc":"Message id","required":false,"in":"path","ref":"","_id":"5eaff1c2079597002af24d5c"},{"name":"translations_id","type":"string","default":"","desc":"Translation id","required":false,"in":"path","ref":"","_id":"5eaff1c2079597002af24d5b"}],"examples":{"codes":[{"code":"#!/bin/bash\ncurl \"https://tickets.unbabel.com/api/v1/tickets/02b82af8-24b2-41e6-a73b-ec38aa929c2e/messages/c7f32b37-2bdc-460a-ac16-d4e7445dda5b/translations/b2e0b583-2052-4f5f-a725-4aa23154da13/upgrade\" \\\n    -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\"","language":"shell"}]},"method":"post"},"next":{"description":"","pages":[]},"title":"/tickets/:ticket_id/messages/:message_id/translations/:translation_id/upgrade","type":"post","slug":"upgrade_translation","excerpt":"","body":"# Upgrade translation\n\nAt Unbabel, we've got two main flows of translation:\n- Automatic, often called machine translation, `machine`, or `mt`\n- Post-edited, often called human translation, `human`, or `ht`\n\nIn cases where the inbound or outbound flow is configured to use automatic\ntranslation, it's possible to request a post-edit for that translation. The configuration of the flow to use is done on our side, and it's not possible to specify it on a per-translation basis.\n\nThis is useful in situation where the automatic translation doesn't prove\nto be enough for an adequate understanding of the content.\n\nAs such, an upgrade can only be requested over an automatic translation.\n\n**This endpoint is idempotent.**","updates":[],"order":8,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"createdAt":"2020-04-30T18:00:23.219Z","user":"5eaaaf35d0cd6d0012523bdf","category":"5eaab032c8f6eb0061090008","version":"54afb7160cf42a0b001d5bf0","project":"54ad6c769219922100751763","__v":10,"parentDoc":null,"childrenPages":[]}

post/tickets/:ticket_id/messages/:message_id/translations/:translation_id/upgrade


Path Params

ticket_id:
string
Ticket id
message_id:
string
Message id
translations_id:
string
Translation id
# Upgrade translation At Unbabel, we've got two main flows of translation: - Automatic, often called machine translation, `machine`, or `mt` - Post-edited, often called human translation, `human`, or `ht` In cases where the inbound or outbound flow is configured to use automatic translation, it's possible to request a post-edit for that translation. The configuration of the flow to use is done on our side, and it's not possible to specify it on a per-translation basis. This is useful in situation where the automatic translation doesn't prove to be enough for an adequate understanding of the content. As such, an upgrade can only be requested over an automatic translation. **This endpoint is idempotent.**

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



# Upgrade translation At Unbabel, we've got two main flows of translation: - Automatic, often called machine translation, `machine`, or `mt` - Post-edited, often called human translation, `human`, or `ht` In cases where the inbound or outbound flow is configured to use automatic translation, it's possible to request a post-edit for that translation. The configuration of the flow to use is done on our side, and it's not possible to specify it on a per-translation basis. This is useful in situation where the automatic translation doesn't prove to be enough for an adequate understanding of the content. As such, an upgrade can only be requested over an automatic translation. **This endpoint is idempotent.**
{"_id":"5eaff0a7b9f627005c569a83","metadata":{"image":[],"title":"","description":""},"api":{"url":"/tickets/:ticket_id/translations/","auth":"required","settings":"5eaab1568ee37d00209d5c89","results":{"codes":[{"name":"","code":"{\n  \"next_page\": null,\n  \"translations\": [\n    {\n      \"id\": \"b2e0b583-2052-4f5f-a725-4aa23154da13\",\n      \"message_id\": \"c7f32b37-2bdc-460a-ac16-d4e7445dda5b\",\n      \"source_language_id\": \"pt\",\n      \"target_language_id\": \"en\",\n      \"mode\": \"mt\",\n      \"state\": \"delivered\",\n      \"subject\": null,\n      \"body\": \"Olá mundo\",\n      \"upgraded_from_id\": null,\n      \"created_at\": \"2020-05-04T09:08:06.572751\",\n      \"updated_at\": \"2020-05-04T09:08:08.455628\"\n    }\n  ]\n}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400},{"code":"{\n  \"error\": \"not_found\",\n  \"description\": \"Ticket not found\",\n  \"localized_description\": \"Ticket not found\",\n  \"details\": null\n}","language":"json","status":404},{"code":"{\n  \"error\": \"unauthorized\",\n  \"description\": \"Unauthorized authentication\",\n  \"localized_description\": \"Unauthorized authentication\",\n  \"details\": null\n}","language":"json","status":401},{"code":"{\n  \"error\": \"missing_authentication\",\n  \"description\": \"Authentication credentials were not found\",\n  \"localized_description\": \"Authentication credentials were not found\",\n  \"details\": null\n}","language":"json","status":403}]},"params":[{"name":"created_at__lte","type":"datetime","default":"","desc":"Optional. Use this to filter messages based on their creation date. This parameter is used for pagination.","required":false,"in":"query","ref":"","_id":"5eafefd4bd83550061383100"},{"name":"ticket_id","type":"string","default":"","desc":"Ticket id","required":false,"in":"path","ref":"","_id":"5eafefd4bd835500613830ff"}],"examples":{"codes":[{"code":"#!/bin/bash\ncurl \"https://tickets.unbabel.com/api/v1/tickets/02b82af8-24b2-41e6-a73b-ec38aa929c2e/translations\" \\\n    -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\"","language":"shell"}]},"method":"get"},"next":{"description":"","pages":[]},"title":"/tickets/:ticket_id/translations/","type":"get","slug":"list_ticket_translations","excerpt":"","body":"# List ticket translations\n\nYou can use this endpoint to list all the translations for a ticket.\n\nThe listing is paginated, using the created datetime as the cursor (you can\nuse the `next_page` field to navigate to the next page) and a\nmaximum number of 25 results are returned at each iteration.","updates":[],"order":9,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"createdAt":"2020-05-04T10:38:31.422Z","user":"5eaaaf35d0cd6d0012523bdf","category":"5eaab032c8f6eb0061090008","version":"54afb7160cf42a0b001d5bf0","project":"54ad6c769219922100751763","__v":10,"parentDoc":null,"childrenPages":[]}

get/tickets/:ticket_id/translations/


Path Params

ticket_id:
string
Ticket id

Query Params

created_at__lte:
datetime
Optional. Use this to filter messages based on their creation date. This parameter is used for pagination.
# List ticket translations You can use this endpoint to list all the translations for a ticket. The listing is paginated, using the created datetime as the cursor (you can use the `next_page` field to navigate to the next page) and a maximum number of 25 results are returned at each iteration.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



# List ticket translations You can use this endpoint to list all the translations for a ticket. The listing is paginated, using the created datetime as the cursor (you can use the `next_page` field to navigate to the next page) and a maximum number of 25 results are returned at each iteration.
{"_id":"5fbbd9243b47160059632298","metadata":{"image":[],"title":"","description":""},"api":{"url":"/configurations/","auth":"required","settings":"5eaab1568ee37d00209d5c89","results":{"codes":[{"name":"","code":"{\n  \"next_page\": null,\n  \"configurations\": [\n    {\n      \"installation_id\": \"crm1.example.com\",\n      \"callback_endpoint\": \"https://crm1.example.com/callback_url\"\n    },\n    {\n      \"installation_id\": \"crm2.example.com\",\n      \"callback_endpoint\": \"https://crm2.example.com/different_callback_url\"\n    }\n  ]\n}","language":"json","status":200},{"code":"{\n  \"error\": \"unauthorized\",\n  \"description\": \"Unauthorized authentication\",\n  \"localized_description\": \"Unauthorized authentication\",\n  \"details\": null\n}","language":"json","status":401},{"code":"{\n  \"error\": \"missing_authentication\",\n  \"description\": \"Authentication credentials were not found\",\n  \"localized_description\": \"Authentication credentials were not found\",\n  \"details\": null\n}","language":"json","status":403}]},"params":[{"name":"installation_id","type":"string","default":"\"\"","desc":"Optional. Specify to retrieve an configuration with this installation id","required":false,"in":"query","ref":"","_id":"5eab0f57ad1461005372af88"},{"name":"created_at__gt","type":"datetime","default":"","desc":"Optional. Use this to filter configurations based on their creation date. This parameter is used for pagination.","required":false,"in":"query","ref":"","_id":"5eaff3579149b900738d5ea6"}],"examples":{"codes":[{"code":"#!/bin/bash\ncurl \"https://tickets.unbabel.com/api/v1/configurations\" \\\n    -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\"","language":"shell"}]},"method":"get"},"next":{"description":"","pages":[]},"title":"/configurations/","type":"get","slug":"configurations","excerpt":"","body":"# List Configurations\n\nYou can use this endpoint to list all of a customer's configurations.\n\nThe listing is paginated, using the created datetime as the cursor (you can\nuse the `next_page` field to navigate to the next page) and a\nmaximum number of 25 results are returned at each iteration.\n\nIf the customer has not yet created a configuration, an empty list will be returned.\n\nIt's also possible to filter the results returned. This is useful\nif you want to list configurations that:\n  - belong to a specific installation id","updates":[],"order":10,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"createdAt":"2020-11-23T15:45:40.526Z","user":"5eaaaf35d0cd6d0012523bdf","category":"5eaab032c8f6eb0061090008","version":"54afb7160cf42a0b001d5bf0","project":"54ad6c769219922100751763","__v":2,"parentDoc":null,"childrenPages":[]}

get/configurations/


Query Params

installation_id:
string""
Optional. Specify to retrieve an configuration with this installation id
created_at__gt:
datetime
Optional. Use this to filter configurations based on their creation date. This parameter is used for pagination.
# List Configurations You can use this endpoint to list all of a customer's configurations. The listing is paginated, using the created datetime as the cursor (you can use the `next_page` field to navigate to the next page) and a maximum number of 25 results are returned at each iteration. If the customer has not yet created a configuration, an empty list will be returned. It's also possible to filter the results returned. This is useful if you want to list configurations that: - belong to a specific installation id

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



# List Configurations You can use this endpoint to list all of a customer's configurations. The listing is paginated, using the created datetime as the cursor (you can use the `next_page` field to navigate to the next page) and a maximum number of 25 results are returned at each iteration. If the customer has not yet created a configuration, an empty list will be returned. It's also possible to filter the results returned. This is useful if you want to list configurations that: - belong to a specific installation id
{"_id":"5fbbddc6d268a60018dea608","metadata":{"image":[],"title":"","description":""},"api":{"url":"/configurations/","auth":"required","settings":"5eaab1568ee37d00209d5c89","results":{"codes":[{"name":"","code":"{\n  \"installation_id\": \"crm1.example.com\",\n  \"callback_endpoint\": \"https://crm1.example.com/callback_url\"\n}","language":"json","status":200},{"code":"{\n  \"error\": \"unauthorized\",\n  \"description\": \"Unauthorized authentication\",\n  \"localized_description\": \"Unauthorized authentication\",\n  \"details\": null\n}","language":"json","status":401},{"code":"{\n  \"error\": \"missing_authentication\",\n  \"description\": \"Authentication credentials were not found\",\n  \"localized_description\": \"Authentication credentials were not found\",\n  \"details\": null\n}","language":"json","status":403}]},"params":[{"name":"installation_id","type":"string","default":"\"\"","desc":"Optional. Specify to retrieve an configuration with this installation id","required":false,"in":"body","ref":"","_id":"5eab0f57ad1461005372af88"},{"name":"callback_endpoint","type":"string","default":"\"\"","desc":"Optional. Callback endpoint were translations will be delivered, for this installation id","required":false,"in":"body","ref":"","_id":"5fbbddc6d268a60018dea60a"},{"name":"shared_key","type":"string","default":"\"\"","desc":"Optional. Specify a shared key sign the payload, when calling the callback endpoint","required":false,"in":"body","ref":"","_id":"5fbbddc6d268a60018dea609"}],"examples":{"codes":[{"code":"#!/bin/bash\ncurl \"https://tickets.unbabel.com/api/v1/configurations\" \\\n    -X POST \\\n    -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n    -H \"Content-Type: application/json\" \\\n    --data '{\n      \"installation_id\": \"crm1.example.com\",\n      \"callback_endpoint\": \"https://crm1.example.com/callback_url\"\n    }'","language":"shell"}]},"method":"post"},"next":{"description":"","pages":[]},"title":"/configurations/","type":"post","slug":"configurations-1","excerpt":"","body":"# Create or update a configuration\n\nYou can use this endpoint to create or update a certain configuration. Configurations are identified by a user-provided `installation_id`. If one exists, it'll update the existing configuration. If not, a new one will be created.","updates":[],"order":11,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"createdAt":"2020-11-23T16:05:26.699Z","user":"5eaaaf35d0cd6d0012523bdf","category":"5eaab032c8f6eb0061090008","version":"54afb7160cf42a0b001d5bf0","project":"54ad6c769219922100751763","__v":0,"parentDoc":null,"childrenPages":[]}

post/configurations/


Body Params

installation_id:
string""
Optional. Specify to retrieve an configuration with this installation id
callback_endpoint:
string""
Optional. Callback endpoint were translations will be delivered, for this installation id
shared_key:
string""
Optional. Specify a shared key sign the payload, when calling the callback endpoint
# Create or update a configuration You can use this endpoint to create or update a certain configuration. Configurations are identified by a user-provided `installation_id`. If one exists, it'll update the existing configuration. If not, a new one will be created.

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



# Create or update a configuration You can use this endpoint to create or update a certain configuration. Configurations are identified by a user-provided `installation_id`. If one exists, it'll update the existing configuration. If not, a new one will be created.
{"_id":"55a8b68229d10b2100779fbe","githubsync":"","hidden":false,"project":"54ad6c769219922100751763","sync_unique":"","title":"/translation/","user":"54ad6c239219922100751762","category":"55a8b603f36b3f2d00f12158","excerpt":"Create translation jobs","link_external":false,"next":{"description":"","pages":[]},"parentDoc":null,"updates":["56798d35239fac0d00c7e00b"],"__v":10,"createdAt":"2015-07-17T08:02:10.013Z","editedParams":true,"link_url":"","slug":"translation","type":"post","version":"54afb7160cf42a0b001d5bf0","api":{"url":"/translation/","auth":"required","examples":{"codes":[{"name":"","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X POST https://api.unbabel.com/tapi/v2/translation/ \\\n        -d '{\n                \"text\": \"Text to be translated\",\n                \"source_language\": \"en\",\n                \"target_language\": \"pt\"\n            }'","language":"shell"}]},"method":"post","params":[{"_id":"55a8b68229d10b2100779fbf","ref":"","in":"body","required":true,"desc":"UTF-8 encoding is preferred.","default":"","type":"string","name":"text"},{"_id":"55a8b6d4402f330d00a373da","ref":"","in":"body","required":true,"desc":"If not supplied will be auto-detected. Language detection is not 100% accurate so please supply this field if possible!","default":"","type":"string","name":"source_language"},{"_id":"55a8b773f36b3f2d00f12166","ref":"","in":"body","required":true,"desc":"Language shortname. See the language_pair endpoint for available languages and their shortnames.","default":"","type":"string","name":"target_language"},{"_id":"55a8b773f36b3f2d00f12165","ref":"","in":"body","required":false,"desc":"If you already have a translation you want post-edited, use this field.","default":"","type":"string","name":"target_text"},{"_id":"55a8b773f36b3f2d00f1215f","ref":"","in":"body","required":false,"desc":"You can choose from \"text\", \"html\", \"srt\" or \"xliff\"","default":"text","type":"string","name":"text_format"},{"_id":"55a8b773f36b3f2d00f12164","ref":"","in":"body","required":false,"desc":"You can specify an ID for a particular translation. Note that it has to be unique.","default":"","type":"string","name":"uid"},{"_id":"55a8b773f36b3f2d00f12163","ref":"","in":"body","required":false,"desc":"If supplied we will POST the translation back to this URL when it is complete.","default":"","type":"string","name":"callback_url"},{"_id":"596fd2f62decf000429d875f","ref":"","in":"body","required":false,"desc":"Enter the external identifier of a Brand or omit to use the brand default","default":"","type":"string","name":"brand"},{"_id":"55a8b773f36b3f2d00f12162","ref":"","in":"body","required":false,"desc":"See tone endpoint for list of available tones. Omit this field to use brand value.","default":"","type":"string","name":"tone"},{"_id":"55a8b773f36b3f2d00f12160","ref":"","in":"body","required":false,"desc":"See topic endpoint for list of possible topics.","default":"","type":"array_string","name":"topics"}],"results":{"codes":[{"status":201,"name":"","code":"{\n    \"order_number\": 1.0,\n    \"price\": 8.0, \n    \"source_language\": \"en\", \n    \"status\": \"new\", \n    \"target_language\": \"pt\", \n    \"text\": \"Text to be translated\", \n    \"text_format\": \"text\", \n    \"uid\": \"9a86cf619f\"\n}","language":"json"},{"code":"{}","language":"json","status":400,"name":""}]},"settings":""},"editedParams2":true,"isReference":false,"order":0,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Preserving variables\"\n}\n[/block]\nWhen sending translation jobs in HTML or XLIFF sometimes you have variables that must be preserved. To do that the variables have to be wrapped in a specific way.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- If this was your content -->\\n<p>Hello, world, my name is {{ name }}</p>\\n\\n\\n<!-- This is how it should look like before sending it to Unbabel -->\\n<p>Hello world, my name is <span class=\\\"notranslate\\\" origval=\\\"{{ name }}\\\">John Smith</span></p>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nThe tag used to wrap the variable can be of any type, the only requirements are the two attributes.\n\nIn order to give more context to our translators the content inside the tag with the class **notranslate** should be an example of what the variable is, as in the example above.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"class\",\n    \"0-1\": \"The class of the tag must be **notranslate**. Anything else won't work.\",\n    \"1-0\": \"origval\",\n    \"1-1\": \"This attribute saves the variable. After the translation is complete the content inside tags with **notranslate** attribute is replaced with the correspondent **origval** values.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

post/translation/

Create translation jobs

Body Params

text:
required
string
UTF-8 encoding is preferred.
source_language:
required
string
If not supplied will be auto-detected. Language detection is not 100% accurate so please supply this field if possible!
target_language:
required
string
Language shortname. See the language_pair endpoint for available languages and their shortnames.
target_text:
string
If you already have a translation you want post-edited, use this field.
text_format:
stringtext
You can choose from "text", "html", "srt" or "xliff"
uid:
string
You can specify an ID for a particular translation. Note that it has to be unique.
callback_url:
string
If supplied we will POST the translation back to this URL when it is complete.
brand:
string
Enter the external identifier of a Brand or omit to use the brand default
tone:
string
See tone endpoint for list of available tones. Omit this field to use brand value.
topics:
array of strings
See topic endpoint for list of possible topics.
[block:api-header] { "type": "basic", "title": "Preserving variables" } [/block] When sending translation jobs in HTML or XLIFF sometimes you have variables that must be preserved. To do that the variables have to be wrapped in a specific way. [block:code] { "codes": [ { "code": "<!-- If this was your content -->\n<p>Hello, world, my name is {{ name }}</p>\n\n\n<!-- This is how it should look like before sending it to Unbabel -->\n<p>Hello world, my name is <span class=\"notranslate\" origval=\"{{ name }}\">John Smith</span></p>", "language": "html" } ] } [/block] The tag used to wrap the variable can be of any type, the only requirements are the two attributes. In order to give more context to our translators the content inside the tag with the class **notranslate** should be an example of what the variable is, as in the example above. [block:parameters] { "data": { "h-0": "Attribute", "h-1": "Description", "0-0": "class", "0-1": "The class of the tag must be **notranslate**. Anything else won't work.", "1-0": "origval", "1-1": "This attribute saves the variable. After the translation is complete the content inside tags with **notranslate** attribute is replaced with the correspondent **origval** values." }, "cols": 2, "rows": 2 } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:api-header] { "type": "basic", "title": "Preserving variables" } [/block] When sending translation jobs in HTML or XLIFF sometimes you have variables that must be preserved. To do that the variables have to be wrapped in a specific way. [block:code] { "codes": [ { "code": "<!-- If this was your content -->\n<p>Hello, world, my name is {{ name }}</p>\n\n\n<!-- This is how it should look like before sending it to Unbabel -->\n<p>Hello world, my name is <span class=\"notranslate\" origval=\"{{ name }}\">John Smith</span></p>", "language": "html" } ] } [/block] The tag used to wrap the variable can be of any type, the only requirements are the two attributes. In order to give more context to our translators the content inside the tag with the class **notranslate** should be an example of what the variable is, as in the example above. [block:parameters] { "data": { "h-0": "Attribute", "h-1": "Description", "0-0": "class", "0-1": "The class of the tag must be **notranslate**. Anything else won't work.", "1-0": "origval", "1-1": "This attribute saves the variable. After the translation is complete the content inside tags with **notranslate** attribute is replaced with the correspondent **origval** values." }, "cols": 2, "rows": 2 } [/block]
{"_id":"56cb4b11245b841300806f13","api":{"settings":"","url":"/translation/","auth":"required","examples":{"codes":[{"language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://api.unbabel.com/tapi/v2/translation/","name":"Curl (list all)"},{"name":"Curl (filter per target language)","language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://unbabel.com/tapi/v2/translation/?target_language__in=[\"pt\", \"es]"}]},"method":"get","params":[{"name":":uid","type":"string","default":"","desc":"","required":false,"in":"query","ref":"","_id":"56cb4b11245b841300806f16"},{"name":":status","type":"string","default":"","desc":"Acceptable status: \"new\", \"translating\", \"completed\", \"failed\", \"canceled\", \"accepted\", \"rejected\"","required":false,"in":"query","ref":"","_id":"55a8d952c8bd450d000dd0b3"},{"name":"source_language","type":"string","default":"","desc":"","required":false,"in":"query","ref":"","_id":"56cb4b11245b841300806f15"},{"name":"target_language","type":"string","default":"","desc":"","required":false,"in":"query","ref":"","_id":"56cb4b11245b841300806f14"}],"results":{"codes":[{"name":"","code":"{\n    \"meta\": {\n        \"limit\": 20, \n        \"next\": null, \n        \"offset\": 0, \n        \"previous\": null, \n        \"total_count\": 3\n    }, \n    \"objects\": [\n        {\n            \"order_number\": 1,\n          \t\"price\": 10,\n            \"source_language\": \"en\", \n            \"status\": \"new\", \n            \"target_language\": \"pt\", \n            \"text_format\": \"text\", \n            \"uid\": \"30292308e7\"\n        }, (...)\n    ]\n}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]}},"category":"55a8b603f36b3f2d00f12158","createdAt":"2016-02-22T17:53:21.945Z","slug":"translation-list-update","body":"[block:api-header]\n{\n  \"title\": \"Status Description\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"\\\"new\\\", \\\"translating\\\"\",\n    \"1-0\": \"\\\"completed\\\", \\\"accepted\\\"\",\n    \"2-0\": \"\\\"failed\\\",  \\\"rejected\\\"\",\n    \"3-0\": \"\\\"canceled\\\"\",\n    \"h-0\": \"Status\",\n    \"h-1\": \"Description\",\n    \"0-1\": \"Translation in progress\",\n    \"1-1\": \"Translation successfully completed\",\n    \"2-1\": \"Translation completed but failed\",\n    \"3-1\": \"Translation canceled\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]","order":3,"project":"54ad6c769219922100751763","updates":["6017c674901204006df08eab"],"type":"get","user":"561637e421e9110d007802f9","version":"54afb7160cf42a0b001d5bf0","__v":5,"excerpt":"Get jobs with a specific status","githubsync":"","next":{"description":"","pages":[]},"sync_unique":"","link_external":false,"link_url":"","parentDoc":null,"editedParams":true,"editedParams2":true,"hidden":false,"isReference":false,"title":"/translation/","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

get/translation/

Get jobs with a specific status

Query Params

uid:
string
status:
string
Acceptable status: "new", "translating", "completed", "failed", "canceled", "accepted", "rejected"
source_language:
string
target_language:
string
[block:api-header] { "title": "Status Description" } [/block] [block:parameters] { "data": { "0-0": "\"new\", \"translating\"", "1-0": "\"completed\", \"accepted\"", "2-0": "\"failed\", \"rejected\"", "3-0": "\"canceled\"", "h-0": "Status", "h-1": "Description", "0-1": "Translation in progress", "1-1": "Translation successfully completed", "2-1": "Translation completed but failed", "3-1": "Translation canceled" }, "cols": 2, "rows": 4 } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:api-header] { "title": "Status Description" } [/block] [block:parameters] { "data": { "0-0": "\"new\", \"translating\"", "1-0": "\"completed\", \"accepted\"", "2-0": "\"failed\", \"rejected\"", "3-0": "\"canceled\"", "h-0": "Status", "h-1": "Description", "0-1": "Translation in progress", "1-1": "Translation successfully completed", "2-1": "Translation completed but failed", "3-1": "Translation canceled" }, "cols": 2, "rows": 4 } [/block]
{"_id":"55a8d952c8bd450d000dd0b2","parentDoc":null,"__v":3,"createdAt":"2015-07-17T10:30:42.378Z","isReference":false,"link_url":"","next":{"description":"","pages":[]},"order":4,"user":"54ad6c239219922100751762","link_external":false,"type":"get","editedParams":true,"excerpt":"Get a translation job by its uid","githubsync":"","project":"54ad6c769219922100751763","title":"/translation/:uid/","version":"54afb7160cf42a0b001d5bf0","updates":["5e27258ec5900c004b6ef39d"],"api":{"settings":"","url":"/translation/:uid/","auth":"required","examples":{"codes":[{"language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://api.unbabel.com/tapi/v2/translation/:uid/","name":""}]},"method":"get","params":[{"_id":"58dd55d73ca9540f00ef17d2","ref":"","in":"path","required":false,"desc":"UID returned from the original POST or PATCH request","default":"","type":"string","name":":uid"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n    \"balance\": 2682.0, \n    \"client\": \"username\", \n    \"price\": 12.0, \n    \"source_language\": \"en\", \n    \"status\": \"new\", \n    \"target_language\": \"pt\", \n    \"text\": \"The quick brown fox\", \n    \"text_format\": \"text\", \n    \"uid\": \"f2f7a62ca5\"\n}","name":""},{"status":400,"language":"json","code":"{}","name":""}]}},"body":"","category":"55a8b603f36b3f2d00f12158","editedParams2":true,"hidden":false,"slug":"translation-detail","sync_unique":"","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

get/translation/:uid/

Get a translation job by its uid

Path Params

uid:
string
UID returned from the original POST or PATCH request

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"_id":"58dd550915f4150f00839b74","api":{"auth":"required","examples":{"codes":[{"name":"","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X DELETE https://api.unbabel.com/tapi/v2/translation/:uid/","language":"shell"}]},"method":"delete","params":[{"type":"string","name":":uid","_id":"58dd553985a2a02f0005188f","ref":"","in":"path","required":false,"desc":"UID returned from the original POST or PATCH request","default":""}],"results":{"codes":[{"name":"","code":"","language":"text","status":200},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","url":"/translation/:uid/"},"isReference":false,"link_url":"","project":"54ad6c769219922100751763","slug":"translation-cancel","sync_unique":"","excerpt":"Cancel a translation request","hidden":false,"parentDoc":null,"user":"561637e421e9110d007802f9","__v":1,"body":"","link_external":false,"next":{"pages":[],"description":""},"order":5,"type":"delete","updates":[],"version":"54afb7160cf42a0b001d5bf0","category":"55a8b603f36b3f2d00f12158","createdAt":"2017-03-30T18:57:13.840Z","githubsync":"","title":"/translation/:uid/","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

delete/translation/:uid/

Cancel a translation request

Path Params

uid:
string
UID returned from the original POST or PATCH request

Definition

{{ api_url }}{{ page_api_url }}

Examples



{"_id":"580f4f217567d72500498700","link_url":"","parentDoc":null,"updates":[],"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Preserving variables\"\n}\n[/block]\nWhen sending translation jobs in HTML or XLIFF sometimes you have variables that must be preserved. To do that the variables have to be wrapped in a specific way.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- If this was your content -->\\n<p>Hello, world, my name is {{ name }}</p>\\n\\n\\n<!-- This is how it should look like before sending it to Unbabel -->\\n<p>Hello world, my name is <span class=\\\"notranslate\\\" origval=\\\"{{ name }}\\\">John Smith</span></p>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nThe tag used to wrap the variable can be of any type, the only requirements are the two attributes.\n\nIn order to give more context to our translators the content inside the tag with the class **notranslate** should be an example of what the variable is, as in the example above.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"class\",\n    \"0-1\": \"The class of the tag must be **notranslate**. Anything else won't work.\",\n    \"1-0\": \"origval\",\n    \"1-1\": \"This attribute saves the variable. After the translation is complete the content inside tags with **notranslate** attribute is replaced with the correspondent **origval** values.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]","githubsync":"","slug":"mt_translation","api":{"auth":"required","examples":{"codes":[{"name":"","code":"#!/bin/bash\ncurl \\\n  -H \"Authorization: ApiKey username:apikey\" \\\n  -H \"Content-Type: application/json\" \\\n  -X POST https://api.unbabel.com/tapi/v2/mt_translation/ \\\n  -d '{ \"text\": \"Hello, world\", \"source_language\": \"en\", \"target_language\": \"pt\"}'","language":"shell"}]},"method":"post","params":[{"_id":"55a8b68229d10b2100779fbf","ref":"","in":"body","required":true,"desc":"UTF-8 encoding is preferred.","default":"","type":"string","name":"text"},{"_id":"55a8b6d4402f330d00a373da","ref":"","in":"body","required":true,"desc":"If not supplied will be auto-detected. Language detection is not 100% accurate so please supply this field if possible!","default":"","type":"string","name":"source_language"},{"_id":"55a8b773f36b3f2d00f12166","ref":"","in":"body","required":true,"desc":"Language shortname. See the language_pair endpoint for available languages and their shortnames.","default":"","type":"string","name":"target_language"},{"_id":"55a8b773f36b3f2d00f1215f","ref":"","in":"body","required":false,"desc":"You can choose from \"text\", \"html\", \"srt\" or \"xliff\"","default":"text","type":"string","name":"text_format"},{"_id":"55a8b773f36b3f2d00f12164","ref":"","in":"body","required":false,"desc":"You can specify an ID for a particular translation. Note that it has to be unique.","default":"","type":"string","name":"uid"},{"_id":"55a8b773f36b3f2d00f12163","ref":"","in":"body","required":false,"desc":"If supplied we will POST the translation back to this URL when it is complete.","default":"","type":"string","name":"callback_url"},{"_id":"5c864f651f4879005db3df2a","ref":"","in":"body","required":false,"desc":"Enter the external identifier of a Brand or omit to use the brand default","default":"","type":"string","name":"brand"},{"_id":"55a8b773f36b3f2d00f12162","ref":"","in":"body","required":false,"desc":"See tone endpoint for list of available tones.","default":"","type":"string","name":"tone"},{"_id":"55a8b773f36b3f2d00f12160","ref":"","in":"body","required":false,"desc":"See topic endpoint for list of possible topics.","default":"","type":"array_string","name":"topics"}],"results":{"codes":[{"status":201,"name":"","code":"{\n\t\t\"origin\": \"api\",\n  \t\"source_language\": \"en\",\n  \t\"status\": \"machine_translate_in_progress\",\n  \t\"target_language\": \"pt\",\n  \t\"text\": \"Hello, world\",\n  \t\"text_format\": \"text\",\n  \t\"uid\": \"329165fca4\"\n}","language":"json"},{"code":"{}","language":"json","status":400,"name":""}]},"settings":"","url":"/mt_translation/"},"createdAt":"2016-10-25T12:25:05.084Z","hidden":false,"isReference":false,"next":{"description":"","pages":[]},"title":"/mt_translation/","type":"post","version":"54afb7160cf42a0b001d5bf0","__v":4,"category":"55a8b603f36b3f2d00f12158","excerpt":"Create machine translation only jobs","link_external":false,"order":6,"project":"54ad6c769219922100751763","sync_unique":"","user":"57eaf88543d2780e008e7a87","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

post/mt_translation/

Create machine translation only jobs

Body Params

text:
required
string
UTF-8 encoding is preferred.
source_language:
required
string
If not supplied will be auto-detected. Language detection is not 100% accurate so please supply this field if possible!
target_language:
required
string
Language shortname. See the language_pair endpoint for available languages and their shortnames.
text_format:
stringtext
You can choose from "text", "html", "srt" or "xliff"
uid:
string
You can specify an ID for a particular translation. Note that it has to be unique.
callback_url:
string
If supplied we will POST the translation back to this URL when it is complete.
brand:
string
Enter the external identifier of a Brand or omit to use the brand default
tone:
string
See tone endpoint for list of available tones.
topics:
array of strings
See topic endpoint for list of possible topics.
[block:api-header] { "type": "basic", "title": "Preserving variables" } [/block] When sending translation jobs in HTML or XLIFF sometimes you have variables that must be preserved. To do that the variables have to be wrapped in a specific way. [block:code] { "codes": [ { "code": "<!-- If this was your content -->\n<p>Hello, world, my name is {{ name }}</p>\n\n\n<!-- This is how it should look like before sending it to Unbabel -->\n<p>Hello world, my name is <span class=\"notranslate\" origval=\"{{ name }}\">John Smith</span></p>", "language": "html" } ] } [/block] The tag used to wrap the variable can be of any type, the only requirements are the two attributes. In order to give more context to our translators the content inside the tag with the class **notranslate** should be an example of what the variable is, as in the example above. [block:parameters] { "data": { "h-0": "Attribute", "h-1": "Description", "0-0": "class", "0-1": "The class of the tag must be **notranslate**. Anything else won't work.", "1-0": "origval", "1-1": "This attribute saves the variable. After the translation is complete the content inside tags with **notranslate** attribute is replaced with the correspondent **origval** values." }, "cols": 2, "rows": 2 } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:api-header] { "type": "basic", "title": "Preserving variables" } [/block] When sending translation jobs in HTML or XLIFF sometimes you have variables that must be preserved. To do that the variables have to be wrapped in a specific way. [block:code] { "codes": [ { "code": "<!-- If this was your content -->\n<p>Hello, world, my name is {{ name }}</p>\n\n\n<!-- This is how it should look like before sending it to Unbabel -->\n<p>Hello world, my name is <span class=\"notranslate\" origval=\"{{ name }}\">John Smith</span></p>", "language": "html" } ] } [/block] The tag used to wrap the variable can be of any type, the only requirements are the two attributes. In order to give more context to our translators the content inside the tag with the class **notranslate** should be an example of what the variable is, as in the example above. [block:parameters] { "data": { "h-0": "Attribute", "h-1": "Description", "0-0": "class", "0-1": "The class of the tag must be **notranslate**. Anything else won't work.", "1-0": "origval", "1-1": "This attribute saves the variable. After the translation is complete the content inside tags with **notranslate** attribute is replaced with the correspondent **origval** values." }, "cols": 2, "rows": 2 } [/block]
{"_id":"580f503a7567d72500498701","slug":"mt_translation-1","title":"/mt_translation/","user":"57eaf88543d2780e008e7a87","githubsync":"","order":7,"parentDoc":null,"project":"54ad6c769219922100751763","body":"[block:api-header]\n{\n  \"title\": \"Status Description\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"\\\"new\\\", \\\"translating\\\"\",\n    \"1-0\": \"\\\"completed\\\"\",\n    \"2-0\": \"\\\"failed\\\"\",\n    \"3-0\": \"\\\"canceled\\\"\",\n    \"h-0\": \"Status\",\n    \"h-1\": \"Description\",\n    \"0-1\": \"Translation in progress\",\n    \"1-1\": \"Translation successfully completed\",\n    \"2-1\": \"Translation completed but failed\",\n    \"3-1\": \"Translation canceled\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]","excerpt":"Get machine translation jobs with a specific status","link_url":"","type":"get","updates":[],"__v":4,"category":"55a8b603f36b3f2d00f12158","createdAt":"2016-10-25T12:29:46.116Z","link_external":false,"next":{"description":"","pages":[]},"api":{"method":"get","params":[{"name":":uid","type":"string","default":"","desc":"","required":false,"in":"query","ref":"","_id":"56cb4b11245b841300806f16"},{"name":":status","type":"string","default":"","desc":"Acceptable status: \"new\", \"translating\", \"completed\", \"failed\", \"canceled\"","required":false,"in":"query","ref":"","_id":"55a8d952c8bd450d000dd0b3"},{"name":"source_language","type":"string","default":"","desc":"","required":false,"in":"query","ref":"","_id":"56cb4b11245b841300806f15"},{"name":"target_language","type":"string","default":"","desc":"","required":false,"in":"query","ref":"","_id":"56cb4b11245b841300806f14"}],"results":{"codes":[{"status":200,"name":"","code":"{\n    \"meta\": {\n        \"limit\": 20, \n        \"next\": null, \n        \"offset\": 0, \n        \"previous\": null, \n        \"total_count\": 3\n    }, \n    \"objects\": [\n        {\n            \"price\": 10, \n            \"source_language\": \"en\", \n            \"status\": \"new\", \n            \"target_language\": \"pt\", \n            \"text_format\": \"text\", \n            \"uid\": \"30292308e7\"\n        }, (...)\n    ]\n}","language":"json"},{"code":"{}","language":"json","status":400,"name":""}]},"settings":"","url":"/mt_translation/","auth":"required","examples":{"codes":[{"language":"shell","code":"#!/bin/bash\ncurl \\\n  -H \"Authorization: ApiKey username:apikey\" \\\n  -X GET https://api.unbabel.com/tapi/v2/mt_translation/329165","name":"Curl (list all)"},{"name":"Curl (filter per target language)","language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://unbabel.com/tapi/v2/translation/?target_language__in=[\"pt\", \"es]"}]}},"hidden":false,"isReference":false,"sync_unique":"","version":"54afb7160cf42a0b001d5bf0","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

get/mt_translation/

Get machine translation jobs with a specific status

Query Params

uid:
string
status:
string
Acceptable status: "new", "translating", "completed", "failed", "canceled"
source_language:
string
target_language:
string
[block:api-header] { "title": "Status Description" } [/block] [block:parameters] { "data": { "0-0": "\"new\", \"translating\"", "1-0": "\"completed\"", "2-0": "\"failed\"", "3-0": "\"canceled\"", "h-0": "Status", "h-1": "Description", "0-1": "Translation in progress", "1-1": "Translation successfully completed", "2-1": "Translation completed but failed", "3-1": "Translation canceled" }, "cols": 2, "rows": 4 } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:api-header] { "title": "Status Description" } [/block] [block:parameters] { "data": { "0-0": "\"new\", \"translating\"", "1-0": "\"completed\"", "2-0": "\"failed\"", "3-0": "\"canceled\"", "h-0": "Status", "h-1": "Description", "0-1": "Translation in progress", "1-1": "Translation successfully completed", "2-1": "Translation completed but failed", "3-1": "Translation canceled" }, "cols": 2, "rows": 4 } [/block]
{"_id":"580f51c833021619006cbc72","api":{"params":[{"default":"","desc":"Uid returned from the original POST request","in":"query","name":":uid","ref":"","required":true,"type":"string","_id":"55a8d952c8bd450d000dd0b3"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n    \"balance\": 2682.0, \n    \"client\": \"username\", \n    \"price\": 12.0, \n    \"source_language\": \"en\", \n    \"status\": \"new\", \n    \"target_language\": \"pt\", \n    \"text\": \"The quick brown fox\", \n    \"text_format\": \"text\", \n    \"uid\": \"f2f7a62ca5\"\n}","name":""},{"code":"{}","name":"","status":400,"language":"json"}]},"settings":"","url":"/mt_translation/:uid/","auth":"required","examples":{"codes":[{"language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://api.unbabel.com/tapi/v2/translation/:uid/","name":""}]},"method":"get"},"body":"","link_url":"","parentDoc":null,"title":"/mt_translation/:uid/","__v":1,"createdAt":"2016-10-25T12:36:24.763Z","githubsync":"","order":8,"sync_unique":"","updates":[],"version":"54afb7160cf42a0b001d5bf0","category":"55a8b603f36b3f2d00f12158","hidden":false,"isReference":false,"link_external":false,"next":{"pages":[],"description":""},"user":"57eaf88543d2780e008e7a87","excerpt":"Get a machine translation job by its uid","project":"54ad6c769219922100751763","slug":"mt_translationuid","type":"get","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

get/mt_translation/:uid/

Get a machine translation job by its uid

Query Params

uid:
required
string
Uid returned from the original POST request

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"_id":"54afc12ea71047160099015a","__v":5,"body":"[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"#!/bin/bash\\n\\ncurl -H \\\"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\\\" \\\\\\n     -H \\\"Content-Type: application/json\\\" \\\\\\n     -X GET https://api.unbabel.com/tapi/v2/tone/\\n\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]","link_url":"","sync_unique":"","githubsync":"","isReference":false,"project":"54ad6c769219922100751763","slug":"tone","version":"54afb7160cf42a0b001d5bf0","updates":[],"user":"54ad6c239219922100751762","api":{"params":[],"results":{"codes":[{"code":"{\n  \"objects\": [\n    {\n      \"tone\": {\n       \"description\": \"Informal style\", \n       \"name\": \"Informal\"\n     }\n    },\n    {\n      \"tone\": {\n        \"description\": \"Formal style\", \n        \"name\": \"Formal\"\n      }\n    }\n  ]\n}","name":"","status":200,"language":"json"},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"/tone/","auth":"required","examples":{"codes":[{"code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://api.unbabel.com/tapi/v2/tone/","name":"","language":"shell"}]},"method":"get"},"hidden":false,"link_external":false,"next":{"description":"","pages":[]},"parentDoc":null,"title":"/tone/","category":"55a8e987cf45e1390093f212","createdAt":"2015-01-09T11:53:18.504Z","excerpt":"Get all possible tones that a translation may have. Editors will take the tone into account and possibly use it to change the formality of the translation.","order":0,"type":"get","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

get/tone/

Get all possible tones that a translation may have. Editors will take the tone into account and possibly use it to change the formality of the translation.

[block:code] { "codes": [ { "code": "#!/bin/bash\n\ncurl -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -X GET https://api.unbabel.com/tapi/v2/tone/\n", "language": "shell" } ] } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:code] { "codes": [ { "code": "#!/bin/bash\n\ncurl -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -X GET https://api.unbabel.com/tapi/v2/tone/\n", "language": "shell" } ] } [/block]
{"_id":"54afc1a2ed9ada1400afbf56","slug":"topic","sync_unique":"","title":"/topic/","body":"[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"#!/bin/bash\\n\\ncurl -H \\\"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\\\" \\\\\\n     -H \\\"Content-Type: application/json\\\" \\\\\\n     -X GET https://unbabel.com/tapi/v2/topic/\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]","category":"55a8e98c27a17d21005251a8","createdAt":"2015-01-09T11:55:14.498Z","githubsync":"","link_url":"","updates":[],"user":"54ad6c239219922100751762","type":"get","version":"54afb7160cf42a0b001d5bf0","api":{"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"objects\": [\n    {\n      \"topic\": {\n        \"name\": \"politics\"\n      }\n    }, \n    {\n      \"topic\": {\n        \"name\": \"gossip\"\n      }\n    }, \n    {\n      \"topic\": {\n        \"name\": \"sex & relationships\"\n      }\n    }, \n    {\n      \"topic\": {\n        \"name\": \"crafts\"\n      }\n    }, \n    {\n      \"topic\": {\n        \"name\": \"parenting\"\n      }\n    }, \n    {\n      \"topic\": {\n        \"name\": \"startups\"\n      }\n    }, \n    {\n      \"topic\": {\n        \"name\": \"tech\"\n      }\n    }, \n    {\n      \"topic\": {\n        \"name\": \"sports\"\n      }\n    }\n  ]\n}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"/topic/","auth":"required","examples":{"codes":[{"language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://api.unbabel.com/tapi/v2/topic/","name":""}]},"method":"get","params":[]},"isReference":false,"order":0,"project":"54ad6c769219922100751763","__v":5,"excerpt":"Get list of topics that may be applied to a translation. Specifying one of these when POSTing a translation will help Unbabel choose which Editors to assign to the translation based upon their experience.","next":{"description":"","pages":[]},"parentDoc":null,"hidden":false,"link_external":false,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

get/topic/

Get list of topics that may be applied to a translation. Specifying one of these when POSTing a translation will help Unbabel choose which Editors to assign to the translation based upon their experience.

[block:code] { "codes": [ { "code": "#!/bin/bash\n\ncurl -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -X GET https://unbabel.com/tapi/v2/topic/", "language": "shell" } ] } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:code] { "codes": [ { "code": "#!/bin/bash\n\ncurl -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -X GET https://unbabel.com/tapi/v2/topic/", "language": "shell" } ] } [/block]
{"_id":"5539007ef426ca0d003ae42b","editedParams":true,"excerpt":"Count words on a text","link_url":"","project":"54ad6c769219922100751763","order":0,"parentDoc":null,"sync_unique":"","body":"","category":"55a8e9d127a17d21005251a9","githubsync":"","link_external":false,"next":{"description":"","pages":[]},"title":"/wordcount/","createdAt":"2015-04-23T14:23:58.037Z","hidden":false,"user":"54f0cebb7d40be370012d525","type":"post","updates":[],"version":"54afb7160cf42a0b001d5bf0","__v":8,"api":{"params":[{"name":"text","type":"string","default":"","desc":"From where we will be counting all the words","required":true,"in":"body","ref":"","_id":"55a8eb30cf45e1390093f21c"}],"results":{"codes":[{"status":201,"language":"json","code":"{\n  \"word_count\": 4\n}","name":null},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"/wordcount/","auth":"required","examples":{"codes":[{"code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X POST https://api.unbabel.com/tapi/v2/wordcount/ \\\n        -d '{\n                \"text\": \"Text to be translated\"\n            }'","language":"shell"}]},"method":"post"},"editedParams2":true,"isReference":false,"slug":"post-wordcount","metadata":{"title":"","description":"","image":[]},"childrenPages":[]}

post/wordcount/

Count words on a text

Body Params

text:
required
string
From where we will be counting all the words

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format