Project Detail Retrieval

Retrieving detailed information about your projects is crucial for effective project management. Whether you're looking to review the current state of a project, analyze past performance, or prepare for upcoming tasks, having access to comprehensive project details is essential. This guide will walk you through how to retrieve detailed information about your projects, including segments and other key metrics, using TextUnited's API.

Understanding the Importance of Project Details

Access to detailed project information enables you to:

• Monitor project progress in real-time.
• Analyze translation quality and efficiency.
• Plan future projects based on historical data.
• Make informed decisions regarding project adjustments.

Working with Segments in TextUnited

Segments represent discrete units of text within a document that are translated individually. Managing these segments effectively is crucial for maintaining the integrity and quality of translations. This guide will walk you through how to retrieve segments for a project and work with them using TextUnited's API.

Understanding the Get Segments Endpoint

The "Get Segments" endpoint allows you to fetch segments associated with a specific project. You can filter segments by either the TextUnited ID or a custom ID, providing flexibility in how you access segment data.

TextUnited ID

The TextUnited ID refers to the unique identifier assigned to each segment within a project by the TextUnited platform. When you create or import documents into TextUnited for translation, each segment of text is automatically assigned a unique TextUnited ID. This ID is generated by TextUnited and is consistent across all projects and users within the system. Using the TextUnited ID allows you to precisely target and retrieve specific segments from a project, regardless of the project's size or the number of segments it contains.

Custom ID

A Custom ID, on the other hand, is a user-defined identifier that can be assigned to segments during the document setup or import process. Unlike the TextUnited ID, which is automatically generated, Custom IDs must be manually set by the user. This feature offers flexibility in segment management, enabling translators or project managers to categorize or tag segments in ways that best suit their workflow or project requirements. For example, you might assign Custom IDs to segments based on their topic, priority, or any other criteria relevant to your project.

Filtering Segments

When using the "Get Segments" endpoint, you have the option to filter segments by either the TextUnited ID or a Custom ID. This flexibility allows you to tailor your API calls to meet specific needs:

• Filtering by TextUnited ID: This method is straightforward and efficient for accessing segments based on their unique identifiers assigned by TextUnited. It's ideal for situations where you need to retrieve specific segments without additional categorization.
• Filtering by Custom ID: Choosing to filter by Custom ID is beneficial when you've organized your segments using user-defined tags or categories. This approach enables you to retrieve segments based on your own classification system, enhancing the precision and relevance of the data you access.

Example Usage

Suppose you have a project with numerous segments, and you're interested in retrieving only those segments related to a specific topic. Instead of searching through all segments, you can use the "Get Segments" endpoint with a Custom ID that represents that topic. This targeted approach saves time and resources, ensuring that you only work with the segments that are most relevant to your current task.

Prerequisites

Before proceeding, ensure you have:

• API Credentials: If you're using Basic Authentication, get your Company ID and API Key. For Bearer JWT Authentication, you'll need your JWT Access Token. Refer to our guides on Obtaining Your API Key and Company ID and Obtaining JWT Token for details.
• Understanding of API Basics: Familiarity with RESTful APIs, HTTP methods (GET), and JSON format.

Step-by-Step Guide to Retrieve Project Details

Getting Segments by TextUnited ID

When you need to retrieve specific segments associated with a project, you'll use the "Get Segments by TextUnited ID" endpoint of the TextUnited API. This endpoint allows you to fetch segments based on the project's TextUnited ID, which is automatically generated by TextUnited upon creating a multilingual project using the "Create Multilingual Project" endpoint.

ℹ️

Note

For detailed guides on creating a multilingual project, refer to this guide on Project Initialization.

Step 1: Obtain the TextUnited ID

To obtain the TextUnited ID of your project programmatically, you can use the "Get Projects" endpoint. This endpoint returns a list of your projects, including their IDs. Here's how you can use it:

• Endpoint: /segments/projects
• Method: GET
• Authentication: Include your API credentials in the request headers for authentication.

An example response from the "Get Projects" endpoint might look like this:

[
    {
        "source": {
            "id": <identifier_of_the_segment>,
            "customId": "<custom_identifier_of_the_segment>",
            "content": "<content_of_the_segment>",
            "notes": "<note_for_the_segment>",
            "taskId": "<identifier_for_the_specific_task>",
            "languageSpecificNotes": "<specific_tasks_for_the_language>"
        },
        "translations": [
            {
                "id": <identifier_for_the_translator>,
                "languageId": <language_identifier>,
                "languageCode": "<language_code>",
                "content": "<translated_content>",
                "status": "<status_of_the_translation>",
                "comments": <comments_added>
            }
        ]
    },
    {
         "source": {
            "id": <identifier_of_the_segment>,
            "customId": "<custom_identifier_of_the_segment>",
            "content": "<content_of_the_segment>",
            "notes": "<note_for_the_segment>",
            "taskId": "<identifier_for_the_specific_task>",
            "languageSpecificNotes": "<specific_tasks_for_the_language>"
        },
        "translations": [
            {
                "id": <identifier_for_the_translator>,
                "languageId": <language_identifier>,
                "languageCode": "<language_code>",
                "content": "<translated_content>",
                "status": "<status_of_the_translation>",
                "comments": <comments_added>
            }
        ]
    },
    {
         "source": {
            "id": <identifier_of_the_segment>,
            "customId": "<custom_identifier_of_the_segment>",
            "content": "<content_of_the_segment>",
            "notes": "<note_for_the_segment>",
            "taskId": "<identifier_for_the_specific_task>",
            "languageSpecificNotes": "<specific_tasks_for_the_language>"
        },
        "translations": [
            {
                "id": <identifier_for_the_translator>,
                "languageId": <language_identifier>,
                "languageCode": "<language_code>",
                "content": "<translated_content>",
                "status": "<status_of_the_translation>",
                "comments": <comments_added>
            }
        ]
    }
]

From this response, identify the "id" field corresponding to the project you're interested in retrieving segments for.

Step 2: Construct the API Request

Once you have identified the TextUnited ID of your project, you can construct the GET request to the "Get Segments" endpoint as follows:

GET /segments/projects/{id}/segments

Replace {id} with the actual TextUnited ID of the project you wish to retrieve segments for. For example, if your project's TextUnited ID is <your_id> (this is a placeholder), the constructed endpoint URL for retrieving segments would be:

GET /segments/projects/<your_id>/segments

This URL instructs the TextUnited API to return all segments associated with the project that has the TextUnited ID .

❗️

Note

Include your API credentials in the request headers for authentication. Here's an example using curl:

cURL

curl --request GET \
     --url https://api.textunited.com/segments/projects/<your_id>/segments \
     --header 'Authorization: Bearer <your_api_token>' \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json'

Replace "<your_api_token>" with your actual JWT Access token that can be obtained from calling the Obtain JWT endpoint and replace <your_id>with your TextUnited ID.

ℹ️

Try your Request

You can call the endpoint to retrieve segments associated with the TextUnited ID directly on our documentation platform. Refer to our API Reference for the Get Segments by TextUnited ID endpoint.

👍

Success

Once the request is successful, you'll receive a status code of 200 OK along with your project list.

Example Response

[
    {
        "source": {
            "id": <identifier_of_the_segment>,
            "customId": "<custom_identifier_of_the_segment>",
            "content": "<content_of_the_segment>",
            "notes": "<note_for_the_segment>",
            "taskId": "<identifier_for_the_specific_task>",
            "languageSpecificNotes": "<specific_tasks_for_the_language>"
        },
        "translations": [
            {
                "id": <identifier_for_the_translator>,
                "languageId": <language_identifier>,
                "languageCode": "<language_code>",
                "content": "<translated_content>",
                "status": "<status_of_the_translation>",
                "comments": <comments_added>
            }
        ]
    },
    {
         "source": {
            "id": <identifier_of_the_segment>,
            "customId": "<custom_identifier_of_the_segment>",
            "content": "<content_of_the_segment>",
            "notes": "<note_for_the_segment>",
            "taskId": "<identifier_for_the_specific_task>",
            "languageSpecificNotes": "<specific_tasks_for_the_language>"
        },
        "translations": [
            {
                "id": <identifier_for_the_translator>,
                "languageId": <language_identifier>,
                "languageCode": "<language_code>",
                "content": "<translated_content>",
                "status": "<status_of_the_translation>",
                "comments": <comments_added>
            }
        ]
    },
    {
         "source": {
            "id": <identifier_of_the_segment>,
            "customId": "<custom_identifier_of_the_segment>",
            "content": "<content_of_the_segment>",
            "notes": "<note_for_the_segment>",
            "taskId": "<identifier_for_the_specific_task>",
            "languageSpecificNotes": "<specific_tasks_for_the_language>"
        },
        "translations": [
            {
                "id": <identifier_for_the_translator>,
                "languageId": <language_identifier>,
                "languageCode": "<language_code>",
                "content": "<translated_content>",
                "status": "<status_of_the_translation>",
                "comments": <comments_added>
            }
        ]
    }
]

Optional Query Parameters

The "Get Segments by TextUnited ID" endpoint supports several optional query parameters that can be used to filter the segments returned by the API. Two commonly used parameters are status and taskId.

Status

The status parameter filters segments based on their current translation status. This is particularly useful when you want to focus on segments that are in a specific phase of the translation process, such as completed, in progress, pending, or even failed.

• Usage: Append status followed by the desired status value to the endpoint URL. For example, to retrieve only the segments that have been completed, you would use:

GET /segments/projects/{id}/segments?status=completed

• Values: Common status values include completed, InProgress, pending, and failed. The exact set of possible values may vary based on the implementation of the TextUnited API.

TaskId

The taskId parameter allows you to filter segments based on the task they are associated with. Tasks in TextUnited often correspond to specific translation jobs or batches, making this parameter useful for targeting segments related to a particular task.

• Usage: Append taskId followed by the task ID to the endpoint URL. For example, to retrieve segments associated with a task with the ID <your_task_id> (a placeholder), you would use:

GET /segments/projects/{id}/segments?taskId=<your_task_id>

• Values: The taskId value corresponds to the unique identifier of a task within the TextUnited system. This ID is typically provided when the task is created or can be obtained from the API response when querying tasks.

Practical Example

If you have a project with the TextUnited ID <project_id>, and you're interested in retrieving only the segments that are currently being translated (InProgress). You could construct the API request as follows:

GET /segments/projects/{<project_id}/segments?status=InProgress

Replace the placeholder {<project_id>} with your project ID. This request would return all segments associated with that specific project ID that are currently in the InProgress status, helping you track the translation progress more closely.

Example Response

[
    {
        "source": {
            "id": <identifier_of_the_segment>,
            "customId": "<custom_identifier_of_the_segment>",
            "content": "<content_of_the_segment>",
            "notes": "<note_for_the_segment>",
            "taskId": "<identifier_for_the_specific_task>",
            "languageSpecificNotes": "<specific_tasks_for_the_language>"
        },
        "translations": [
            {
                "id": <identifier_for_the_translator>,
                "languageId": <language_identifier>,
                "languageCode": "<language_code>",
                "content": "<translated_content>",
                "status": "<status_of_the_translation>",
                "comments": <comments_added>
            }
        ]
    },
    {
         "source": {
            "id": <identifier_of_the_segment>,
            "customId": "<custom_identifier_of_the_segment>",
            "content": "<content_of_the_segment>",
            "notes": "<note_for_the_segment>",
            "taskId": "<identifier_for_the_specific_task>",
            "languageSpecificNotes": "<specific_tasks_for_the_language>"
        },
        "translations": [
            {
                "id": <identifier_for_the_translator>,
                "languageId": <language_identifier>,
                "languageCode": "<language_code>",
                "content": "<translated_content>",
                "status": "<status_of_the_translation>",
                "comments": <comments_added>
            }
        ]
    },
    {
         "source": {
            "id": <identifier_of_the_segment>,
            "customId": "<custom_identifier_of_the_segment>",
            "content": "<content_of_the_segment>",
            "notes": "<note_for_the_segment>",
            "taskId": "<identifier_for_the_specific_task>",
            "languageSpecificNotes": "<specific_tasks_for_the_language>"
        },
        "translations": [
            {
                "id": <identifier_for_the_translator>,
                "languageId": <language_identifier>,
                "languageCode": "<language_code>",
                "content": "<translated_content>",
                "status": "<status_of_the_translation>",
                "comments": <comments_added>
            }
        ]
    }
]

Get Segments by TextUnited ID Parameters

The table below contains detailed descriptions of the parameters used in the 'Get Segments by TextUnited ID' API call, designed to help you understand their roles and how they influence the retrieval of segment data.

Get Segments by TextUnited ID Response Fields

This table below contains detailed descriptions of the response fields for 'Get Segments by TextUnited ID', aiding in understanding the structure and data types used to represent segment information in TextUnited.

Getting Segments by Custom ID

When working with TextUnited's API, you might encounter scenarios where you need to retrieve segments associated with a project using a Custom ID instead of the standard TextUnited ID. This can be particularly useful when dealing with projects that have been imported or managed outside of the standard workflow.

Step 1: Construct the API Request

To retrieve segments by Custom ID, you'll construct a GET request to the following endpoint:

GET /segments/projects/custom/{customId}/segments

In this URL, {customId} is a placeholder for the actual Custom ID of the project whose segments you wish to retrieve. Unlike the TextUnited ID, the Custom ID is a string value that you define when creating or importing a project into TextUnited.

How to Replace {customId}

• Determine the Custom ID of your project. This ID is typically set during the creation or import process of the project within the TextUnited platform. (Refer to this API Reference on "Get Projects" to retrieve the custom ID you defined when creating your project with the "Create Multilingual Project" endpoint.)
• Copy the Custom ID.
• Paste the copied Custom ID in place of {customId} in the endpoint URL.

For example, if your project's Custom ID is <your_custom_id> (a placeholder), the constructed endpoint URL for retrieving segments would be:

GET /segments/projects/custom/<your_custom_id>/segments

This URL instructs the TextUnited API to return all segments associated with the project that has the Custom ID <your_custom_id>.

Step 2: Provide Optional Query Parameters

The endpoint supports additional query parameters like status and taskId to further filter the segments returned by the API. These parameters allow you to refine your request based on the current translation status of the segments or their association with specific tasks.

• status: Filters segments based on their current translation status. Possible values might include completed, inProgress, pending, or failed.

Example usage:

GET /segments/projects/custom/<your_custom_id>/segments?status=InProgress

• taskId: Allows you to filter segments based on the task they are associated with. This is useful for targeting segments related to a particular translation job or batch.

Example usage:

GET /segments/projects/custom/<your_custom_id>/segments?taskId=<your_task_id

Step 3: Send the Request

With the endpoint URL constructed and any optional query parameters added, you're ready to send the GET request to the TextUnited API. Ensure you include your API credentials in the request headers for authentication.

curl --request GET \
     --url https://api.textunited.com/segments/projects/custom/new-seg-project-customId/segments \
     --header 'Authorization: Bearer <your_api_token>' \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json'

Replace "<your_api_token>" with your actual JWT Access token that can be obtained from calling the Obtain JWT endpoint, and replace <your_custom_id>with your Custom ID.

ℹ️

Try your Request

You can call the endpoint to retrieve segments associated with the TextUnited ID directly on our documentation platform. Refer to our API Reference for the Get Segments by Custom ID endpoint.

Step 4: Handle the Response

Upon successful execution, the API will return a JSON response containing the segments associated with the project, filtered according to the criteria specified in your request.

Example Response

[
   [
    {
        "source": {
            "id": <identifier_of_the_segment>,
            "customId": "<custom_identifier_of_the_segment>",
            "content": "<content_of_the_segment>",
            "notes": "<note_for_the_segment>",
            "taskId": "<identifier_for_the_specific_task>",
            "languageSpecificNotes": "<specific_tasks_for_the_language>"
        },
        "translations": [
            {
                "id": <identifier_for_the_translator>,
                "languageId": <language_identifier>,
                "languageCode": "<language_code>",
                "content": "<translated_content>",
                "status": "<status_of_the_translation>",
                "comments": <comments_added>
            }
        ]
    },
    {
         "source": {
            "id": <identifier_of_the_segment>,
            "customId": "<custom_identifier_of_the_segment>",
            "content": "<content_of_the_segment>",
            "notes": "<note_for_the_segment>",
            "taskId": "<identifier_for_the_specific_task>",
            "languageSpecificNotes": "<specific_tasks_for_the_language>"
        },
        "translations": [
            {
                "id": <identifier_for_the_translator>,
                "languageId": <language_identifier>,
                "languageCode": "<language_code>",
                "content": "<translated_content>",
                "status": "<status_of_the_translation>",
                "comments": <comments_added>
            }
        ]
    },
    {
         "source": {
            "id": <identifier_of_the_segment>,
            "customId": "<custom_identifier_of_the_segment>",
            "content": "<content_of_the_segment>",
            "notes": "<note_for_the_segment>",
            "taskId": "<identifier_for_the_specific_task>",
            "languageSpecificNotes": "<specific_tasks_for_the_language>"
        },
        "translations": [
            {
                "id": <identifier_for_the_translator>,
                "languageId": <language_identifier>,
                "languageCode": "<language_code>",
                "content": "<translated_content>",
                "status": "<status_of_the_translation>",
                "comments": <comments_added>
            }
        ]
    }
]

Get Segments by Custom ID Parameters

The table below contains detailed descriptions of the parameters used in the 'Get Segments by Custom ID' API call, designed to help you understand their roles and how they influence the retrieval of segment data.

Get Segments by Custom ID Response Fields

This table below contains detailed descriptions of the response fields for 'Get Segments by Custom ID', aiding in understanding the structure and data types used to represent segment information in TextUnited.