# Documents ## List documents of a project {% hint style="info" %} **OAuth:** This endpoint requires one of the following scopes: `project:manage`, `project:write` or `project:read`. {% endhint %} {% openapi src="" path="/v1/clients/projects/{project\_id}/documents" method="get" %} {% endopenapi %} #### Code samples ```shell curl -G "https://api.textmaster.com/v1/clients/projects/61698a9e8b81926d91c0e3a3/documents" \ -H "Authorization: Bearer d8d6b2738bb6e88bb32351fad917d9b6e726a0413251e6a7e3d1da164cadeb65" ``` ## Filter documents of a project {% hint style="info" %} **OAuth:** This endpoint requires one of the following scopes: `project:manage`, `project:write` or `project:read`. {% endhint %} {% openapi src="" path="/v1/clients/projects/{project\_id}/documents/filter" method="get" %} {% endopenapi %} #### Parameters You can use the [Filter API](https://developer.textmaster.com/overview/filters) to filter documents on a collection of criteria. | Name | Type | Description | | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | string | The unique identifier of the document. | | `ref` | string | The reference identifying the document. | | `title` | string | The title of the document. | | `activity_name` | string | The activity of the document. | | `status` | string | The status of the document. See the [Workflow](https://developer.textmaster.com/overview/workflow#documents) section. | | `created_at` | string | Describes the time the document was created. This is a timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: `YYYY-MM-DDTHH:MM:SSZ`. | | `updated_at` | string | Describes the time the document was last updated. This is a timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: `YYYY-MM-DDTHH:MM:SSZ`. | | `completed_at` | string | Describes the time the document was completed. This is a timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: `YYYY-MM-DDTHH:MM:SSZ`. | | `started_at` | string | Describes the time the assigned author started working on the document. This is a timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: `YYYY-MM-DDTHH:MM:SSZ`. | | `submitted_at` | string | Describes the time the assigned author submitted its work on the document. This is a timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: `YYYY-MM-DDTHH:MM:SSZ`. | | `language_from_code` | string | The source language code of the document. One of the language code returned by the [Language](https://developer.textmaster.com/reference/languages) endpoint. | | `language_to_code` | string | The target language code of the document. One of the language code returned by the [Language](https://developer.textmaster.com/reference/languages) endpoint. | | `word_count` | integer | The number of words in the document. | | `category` | string | The category identifier for the document. One of the category returned by the [Category](https://developer.textmaster.com/reference/categories) endpoint. | | `deliver_work_as_file` | boolean | Whether the author has to submit its work as a file or not. Default to `false`. | #### Code samples ```shell curl -G "https://api.textmaster.com/v1/clients/projects/61698a9c8b81926d91c0e32b/documents/filter" \ --data-urlencode 'where={"status":"waiting_assignment","language_from_code":"fr","language_to_code":"en"}' \ --data-urlencode 'order=level_name' \ -H "Authorization: Bearer b3e8b9c6653dc5b1ec5e5c3607b6720a8cee46fd483972595dcb17fc1eae183a" ``` ## Get a document {% hint style="info" %} **OAuth:** This endpoint requires one of the following scopes: `project:manage`, `project:write` or `project:read`. {% endhint %} {% openapi src="" path="/v1/clients/projects/{project\_id}/documents/{document\_id}" method="get" %} {% endopenapi %} #### Code samples ```shell curl -G "https://api.textmaster.com/v1/clients/projects/61698aa18b81926d91c0e4e3/documents/61698aa18b81926d91c0e4e4" \ -H "Authorization: Bearer 0fbf01dc293e00fb51d17069e68e8525f50d7d73000adfb1a1921dd2155833af" ``` ## Create a document TextMaster supports automated word-counting for translation and proofreading documents. An automated count can be scheduled by setting the `perform_word_count` to `true`. In this case `word_count` can be omitted and will be ignored if provided. In case of an error, the API response will contain a `word_count_error: true` node. The two most common failure reasons are: * Unsupported file format for file attachments, in this case a new file must be uploaded * For key/value and plain text documents, the only possible reason is a temporary service issue For translation documents, the automated word-counting can be configured to count *translatable* content in HTML/XML documents, using the `markup_in_content` option. {% hint style="warning" %} **Warning:** If you're using this parameter, you must wait for `word_count_finished` callback for all documents before attempting to launch the project. {% endhint %} #### Original Content {% hint style="warning" %} **Warning:** Due to HTTP protocol limitation, prefere using `remote_file_url` field than `original_content` field to avoid server timeout. HTTP protocol purpose is not to transfer large amount of data, like file or various document. See Providing content as a file Section for more information {% endhint %} For translation or proofreading documents, the content can be provided directly or by using the [Upload API](https://developer.textmaster.com/overview/file-uploads). For standard documents, the original content is a sentence in a readable format (txt, html, …). For key/value documents, the original content has to be an object with a unique key associated to a value. ```json { "document": { ..., "original_content": { "some_unique_key": { "original_phrase": "Some text to translate.", "details": "Some context that will be displayed to the translator." }, "some_other_unique_key": { "original_phrase": "Some other text to translate." } } } } ``` #### Markup in content The `markup_in_content` option indicates whether the original content contains markup (HTML, XML, …) or not. Always set it to `true` for HTML/XML files. Failing to doing so could result in tag names being counted as words and translated, and you being charged for that work. For files with a `.html` or `.xml` extension, this parameter is assumed to be `true`. It defaults to `false` otherwise. {% hint style="info" %} **Tips:** Always set `markup_in_content` to `true` for content which contains HTML or XML. {% endhint %} #### Providing content as a file You can choose to provide the original content as a file instead of providing as raw data. To do so, provide the URL of the file as `remote_file_url`. To learn more about uploading files, see: {% content-ref url="../overview/file-uploads" %} [file-uploads](https://developer.textmaster.com/overview/file-uploads) {% endcontent-ref %} #### Callbacks You can specify callbacks using the `callback` property. It's an object listing URLs to call for each document status. See the list of supported [events](https://developer.textmaster.com/webhooks-and-events/events#documents). ```json { "document": { ..., "callback": { "waiting_assignment": { "url": "http://my.host/waiting_assignment_callback", "format": "json" }, "completed": { "url": "http://my.host/completed_callback", "format": "json" } } } } ``` {% hint style="info" %} **OAuth:** This endpoint requires one of the following scopes: `project:manage` or `project:write`. {% endhint %} {% openapi src="" path="/v1/clients/projects/{project\_id}/documents" method="post" %} {% endopenapi %} #### Code samples ```bash curl "https://api.textmaster.com/v1/clients/projects/61698a9f8b81926d91c0e41b/documents" \ -X POST \ -d '{ "document": { "title": "My document", "instructions": "Some instructions.", "activity_name": "proofreading", "word_count": 200, "word_count_rule": 0, "keywords_repeat_count": 1, "keyword_list": "foo,bar,baz", "language_from": "fr-fr", "language_to": "fr-fr", "original_content": "Some text to proofread.", "callback": { "support_message_created": { "url": "https://callback.example.com/support" } }, "custom_data": { "tags": ["red","soft"], "external_client_id": 1234 } } }' \ -H "Authorization: Bearer edd5e969f9ef1055c5804ee62233d271df8eb4ed30687c2b77d21f93b6301afa" \ -H "Content-Type: application/json" ``` ## Create batch of documents Creates several documents at once. Accepts the same document parameters as singular version, but there can be several of them and they must be placed into a `documents` array. {% hint style="info" %} **OAuth:** This endpoint requires one of the following scopes: `project:manage` or `project:write`. {% endhint %} {% openapi src="" path="/v1/clients/projects/{project\_id}/batch/documents" method="post" %} {% endopenapi %} #### Code samples ```shell curl "https://api.textmaster.com/v1/clients/projects/61698aa08b81926d91c0e47b/batch/documents" \ -X POST \ -d '{ "documents": [ { "title": "My document 1", "instructions": "Some instructions.", "activity_name": "proofreading", "word_count":200, "word_count_rule":0, "keywords_repeat_count":1, "keyword_list": "foo,bar,baz", "language_from": "fr-fr", "language_to": "fr-fr", "original_content": "Some text to proofread." }, { "title": "My document 2", "instructions": "Some instructions.", "activity_name": "translation", "keyword_list": "foo,bar,baz", "language_from": "fr-fr", "language_to": "en-us", "original_content": "Some text to translate." }, ] }' \ -H "Authorization: Bearer b59de755d0f4ab0026cd0f8dcef611fef717858015bd7559992785ff72ad7fa4" \ -H "Content-Type: application/json" ``` ## Get a document review URL Generates the document's review URL which points to the work that requires author review. You can for example, copy this URL into the message sent to the assigned author when completed the document. {% hint style="info" %} **OAuth:** This endpoint requires one of the following scopes: `project:manage`, `project:write` or `project:read`. {% endhint %} {% openapi src="" path="/v1/clients/projects/{project\_id}/documents/{document\_id}/review\_url" method="post" %} {% endopenapi %} #### Code samples ```shell curl "https://api.textmaster.com/v1/clients/projects/61698aa88b81926d91c0e71b/documents/61698aa88b81926d91c0e71c/review_url" \ -X POST \ -d '{ "keys": ["some-key","another-key"] }' \ -H "Authorization: Bearer 977991a2b31ca7f22adf293e5780c683cc18bc72e4cec8a11014e5f6531349de" \ -H "Content-Type: application/json" ``` ## Update a document The update document endpoint takes the same parameters as the create endpoint. Note that you can't update a document once its project has been launched. {% hint style="info" %} **OAuth:** This endpoint requires one of the following scopes: `project:manage` or `project:write`. {% endhint %} {% openapi src="" path="/v1/clients/projects/{project\_id}/documents/{document\_id}" method="put" %} {% endopenapi %} #### Code samples ```shell curl "https://api.textmaster.com/v1/clients/projects/61698aa38b81926d91c0e55b/documents/61698aa48b81926d91c0e5c5" \ -X PUT \ -d '{ "document": { "original_content": "Some text to translate.", "instructions": "Some instructions." } }' \ -H "Authorization: Bearer 3b0eda84b87968d41167bf67b6afbddefd694dcf064f3157dbb70678d7b16b44" \ -H "Content-Type: application/json" ``` ## Complete a document Approve the work done by the assigned author and mark the document as `completed`. Note that when all documents in a project are completed, the project is considered completed too. {% hint style="info" %} **OAuth:** This endpoint requires one of the following scopes: `project:manage` or `project:write`. {% endhint %} {% openapi src="" path="/v1/clients/projects/{project\_id}/documents/{document\_id}/complete" method="put" %} {% endopenapi %} #### Code samples ```shell curl "https://api.textmaster.com/v1/clients/projects/61698aa58b81926d91c0e684/documents/61698aa58b81926d91c0e685/complete" \ -X PUT \ -d '{ "satisfaction": "positive", "message": "Well done!" }' \ -H "Authorization: Bearer 7dddb9f65cfcb17d0de74fe184d62f647842eef357739f00b26029bec27c32f1" \ -H "Content-Type: application/json" ``` ## Complete batch of documents {% hint style="info" %} **OAuth:** This endpoint requires one of the following scopes: `project:manage` or `project:write`. {% endhint %} {% openapi src="" path="/v1/clients/projects/{project\_id}/batch/documents/complete" method="post" %} {% endopenapi %} #### Code samples ```shell curl "https://api.textmaster.com/v1/clients/projects/61698aab8b81926d91c0e7a8/batch/documents/complete" \ -X POST \ -d '{ "documents": ["61698aab8b81926d91c0e7a9"], "satisfaction": "positive", "message": "Well done!" }' \ -H "Authorization: Bearer cb9f19a679fcf674259da57d457820ac965e7b7c6324d59eacc0b0bde6ca123c" \ -H "Content-Type: application/json" ``` ## Delete a document Note that you can't delete a document once its project has been launched. {% hint style="info" %} **OAuth:** This endpoint requires one of the following scopes: `project:manage` or `project:write`. {% endhint %} {% openapi src="" path="/v1/clients/projects/{project\_id}/documents/{document\_id}" method="delete" %} {% endopenapi %} #### Code samples ```shell curl "https://api.textmaster.com/v1/clients/projects/61698aa48b81926d91c0e5fd/documents/61698aa58b81926d91c0e64b" \ -X DELETE \ -H "Authorization: Bearer 5d57d0dce1eeef52be88cf86f98066856eeddd96f12aa7685877adb6769bc894" ```