How to Use TextUnited API: Instant Translation & Project Creation

TextUnited Segments API gives developers a programmatic way to integrate professional translation directly into their applications. Whether you need an immediate automatic translation, want to create a full managed translation project with human review, or need to retrieve completed translations on demand — the API covers all three scenarios. This article walks through each capability with practical examples, followed by a complete data model reference.

Prerequisites

Before making any API calls, you will need:

• A TextUnited account with API access enabled
• A valid Bearer token for authentication. Include it in every request as an Authorization header: Authorization: Bearer <your-token>
• All requests use the base URL: https://api.textunited.com
• The Content-Type header should be set to application/json-patch+json for POST requests.

Note: language codes follow the IETF BCP 47 format (e.g. en-US, de-DE, it-IT). Both SourceLanguageId (numeric) and SourceLanguageCode (string) are accepted — you only need to provide one.

1. Instant Translation

The /segments/translation endpoint translates one or more text segments immediately — no project setup required. This is ideal for on-demand translation of short content, UI strings, or any scenario where you need results right away.

Request

Send a POST request with:

• sourceLanguageCode — the language of the source text (e.g. en-us)
• targetLanguages — an array of target language objects, each with a targetLanguageCode
• segments — an array of segment objects, each with a customId, content (plain text or HTML), and optional notes

curl -X POST --location "https://api.textunited.com/segments/translation" \
    -H "accept: text/plain" \
    -H "Content-Type: application/json-patch+json" \
    -H "Authorization: Bearer ey...O6dnm1BhxtLtICY" \
    -d '{
          "sourceLanguageCode": "en-us",
          "targetLanguages": [
            { "targetLanguageCode": "de-de" },
            { "targetLanguageCode": "it-it" }
          ],
          "segments": [
            { "customId": "00f8dc8d-d77c-47c2-9d38-6983f6cf0003", "content": "Just a sentence to translate.", "notes": "Optional notes here" },
            { "customId": "55a1e1a1-a6ff-4116-b7dd-23f44524a150", "content": "Another sentence to translate" },
            { "customId": "a6599fdc-f872-422a-8381-ca7e390ecd75", "content": "One more." },
            { "customId": "bbb2b98e-71a0-4601-9f47-6eb167cf2c05", "content": "And the last one.", "notes": "That's the last sentence in the batch." }
          ]
        }'

Response

The response includes the original segments and an instantTranslationSegments array. Each entry in that array is an InstantTranslationTranslations object containing the source segment and its translations per target language. Every translation carries a status field indicating how it was produced.

{
  "sourceLanguageCode": "en-us",
  "targetLanguages": [
    { "targetLanguageId": 53, "targetLanguageCode": "de-de" },
    { "targetLanguageId": 71, "targetLanguageCode": "it-it" }
  ],
  "segments": [
    { "customId": "00f8dc8d-d77c-47c2-9d38-6983f6cf0003", "content": "Just a sentence to translate.", "notes": "Optional notes here" }
  ],
  "instantTranslationSegments": [
    {
      "source": {
        "customId": "00f8dc8d-d77c-47c2-9d38-6983f6cf0003",
        "content": "Just a sentence to translate."
      },
      "translations": [
        { "languageId": 53, "languageCode": "de-de", "content": "Nur ein Satz zum Übersetzen.", "status": "automatic" },
        { "languageId": 71, "languageCode": "it-it", "content": "Solo una frase da tradurre.", "status": "automatic" }
      ]
    }
  ]
}

2. Project Creation

The /segments/projects endpoint creates a full translation project. Use this when you need human translators involved, want to track progress over time, or need to manage multiple target languages under a single project.

Key Flags

instantTranslation

• true — automatic translations are returned immediately in the response (inside instantTranslationSegments). Note: this may extend processing time significantly. Human-translated versions can be retrieved later as translators complete their work.
• false — no automatic translations are returned immediately. Human-translated content can be retrieved later via the GET segments endpoint.

managedProject (per target language)

• true — orders a managed translation service: the project is sent to TextUnited for professional translation. It will be started, managed and completed by a TextUnited’s project manager. You are able to query the project status and retrieve human-translated segments via API as the project is progressing.
• false — creates an internal project in InPreparation state, giving your own project manager full control to configure and launch it.

Request

curl -X POST --location "https://api.textunited.com/segments/projects" \
    -H "accept: text/plain" \
    -H "Content-Type: application/json-patch+json" \
    -H "Authorization: Bearer eyJ...YQDVNI" \
    -d '{
          "customId": "22-dec-2025-05",
          "taskId": "22-dec-2025",
          "instantTranslation": false,
          "name": "project-name-22-dec-2025-03",
          "startDateUtc": "2025-12-23T18:13:01.096514+00:00",
          "endDateUtc": "2025-12-29T18:13:01.096514+00:00",
          "sourceLanguageCode": "en-us",
          "targetLanguages": [
            { "targetLanguageCode": "de-de", "managedProject": false, "serviceTranslation": true, "serviceProofreading": false, "serviceAutomaticTranslation": true },
            { "targetLanguageCode": "it-it", "managedProject": false, "serviceTranslation": true, "serviceProofreading": false, "serviceAutomaticTranslation": true }
          ],
          "segments": [
            { "customId": "00f8dc8d-d77c-47c2-9d38-6983f6cf0003", "content": "Just a sentence to translate.", "notes": "Optional notes here" },
            { "customId": "55a1e1a1-a6ff-4116-b7dd-23f44524a150", "content": "Another sentence to translate" },
            { "customId": "a6599fdc-f872-422a-8381-ca7e390ecd75", "content": "One more." },
            { "customId": "bbb2b98e-71a0-4601-9f47-6eb167cf2c05", "content": "And the last one.", "notes": "That's the last sentence in the batch." }
          ]
        }'

Response: Without Instant Translation

When instantTranslation is false, the response contains project metadata and submitted segments. instantTranslationSegments is null. Target language states are InPreparation.

{
  "id": 331070,
  "customId": "22-dec-2025-05",
  "taskId": "22-dec-2025",
  "name": "project-name-22-dec-2025-03",
  "sourceLanguageCode": "en-us",
  "targetLanguages": [
    { "targetLanguageCode": "de-de", "state": "InPreparation", "managedProject": false, "serviceTranslation": true, "serviceAutomaticTranslation": true },
    { "targetLanguageCode": "it-it", "state": "InPreparation", "managedProject": false, "serviceTranslation": true, "serviceAutomaticTranslation": true }
  ],
  "segments": [
    { "customId": "00f8dc8d-d77c-47c2-9d38-6983f6cf0003", "content": "Just a sentence to translate.", "notes": "Optional notes here" }
  ],
  "instantTranslation": false,
  "instantTranslationSegments": null
}

Response: With Instant Translation

When instantTranslation is true, the response has the same structure but instantTranslationSegments is populated with automatic translations for each segment and target language.

{
  "id": 331072,
  "customId": "22-dec-2025-06",
  "sourceLanguageCode": "en-us",
  "targetLanguages": [
    { "targetLanguageCode": "de-de", "state": "InPreparation" },
    { "targetLanguageCode": "it-it", "state": "InPreparation" }
  ],
  "instantTranslation": true,
  "instantTranslationSegments": [
    {
      "source": {
        "customId": "00f8dc8d-d77c-47c2-9d38-6983f6cf0003",
        "content": "Just a sentence to translate."
      },
      "translations": [
        { "languageId": 53, "languageCode": "de-de", "content": "Nur ein Satz zum Übersetzen.", "status": "automatic" },
        { "languageId": 71, "languageCode": "it-it", "content": "Solo una frase da tradurre.", "status": "automatic" }
      ]
    }
  ]
}

3. Retrieving Translated Segments

Once a project is underway, retrieve translated segments at any time using a GET request. The endpoint uses your own customId to identify the project:

GET https://api.textunited.com/segments/projects/custom/{custom-id}/segments

Request

curl -X GET --location "https://api.textunited.com/segments/projects/custom/22-dec-2025-08/segments" \
    -H "accept: text/plain" \
    -H "Authorization: Bearer ey…KYkg"

Response

An array of objects, each containing a source segment and a translations array. Each translation entry includes:

• languageId — numeric ID of the target language
• languageCode — the target language code
• content — the translated text
• status — translation state: untranslated, draft, automatic, pretranslated, translated, or proofread
• comments — any reviewer or translator comments attached to the segment

[
  {
    "source": {
      "customId": "00f8dc8d-d77c-47c2-9d38-6983f6cf0003",
      "content": "Just a sentence to translate.",
      "taskId": "22-dec-2025"
    },
    "translations": [
      { "id": 2227787816, "languageId": 53, "languageCode": "DE-DE", "content": "Nur ein Satz zum Übersetzen.", "status": "automatic", "comments": [] },
      { "id": 2227787812, "languageId": 71, "languageCode": "IT-IT", "content": "Solo una frase da tradurre.", "status": "automatic", "comments": [] }
    ]
  }
]

You can poll this endpoint over time to check for updated translations as human translators complete their work — the status field will progress from automatic through translated and proofread as the workflow advances.

Data Model Reference

This section documents the full C# data models used by the Segments API.

SegmentProject

The top-level project object used when creating a translation project.

• Id (long?, nullable) — Internal Text United project ID, assigned on creation.
• CustomId (string) — Your external system's identifier for this project. Used in subsequent API calls (e.g. retrieving segments).
• TaskId (string) — An initial task identifier for grouping related projects or segments.
• Name (string) — Display name of the project.
• Description (string) — Additional information about the project.
• CreationDateUtc (DateTime?, nullable) — Date the project was created (UTC). Set by the server.
• StartDateUtc (DateTime?, nullable) — Project start date (UTC).
• EndDateUtc (DateTime?, nullable) — Project deadline (UTC).
• SourceLanguageId (long?, nullable) — Numeric ID of the source language. Optional if SourceLanguageCode is provided.
• SourceLanguageCode (string) — Source language code (e.g. en-US). Optional if SourceLanguageId is provided.
• TargetLanguages (List<SegmentProjectTarget>) — Collection of target languages and their settings. Each entry represents an individual translation project.
• Domain (long?, nullable) — ID of the project domain, used to apply domain-specific translation memory.
• Segments (List<SegmentProjectSegment>) — The segments submitted for translation.
• ReferenceNumber (string) — A user-defined custom value for the project.
• CustomField1 (string) — Additional information identifying the project in an external system.
• CustomField2 (string) — Additional information identifying the project in an external system (second field).
• InstantTranslation (bool?, nullable) — Enables immediate automatic or adaptive translation of segments in the response. May extend processing time significantly.
• InstantTranslationSegments (List<InstantTranslationTranslations>) — Automatic translations returned when InstantTranslation is true.

public class SegmentProject
{
    public long? Id { get; set; }
    public string CustomId { get; set; }
    public string TaskId { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
    public DateTime? CreationDateUtc { get; set; }
    public DateTime? StartDateUtc { get; set; }
    public DateTime? EndDateUtc { get; set; }
    public long? SourceLanguageId { get; set; }
    public string SourceLanguageCode { get; set; }
    public List<SegmentProjectTarget> TargetLanguages { get; set; }
    public long? Domain { get; set; }
    public List<SegmentProjectSegment> Segments { get; set; }
    public string ReferenceNumber { get; set; }
    public string CustomField1 { get; set; }
    public string CustomField2 { get; set; }
    public bool? InstantTranslation { get; set; }
    public List<InstantTranslationTranslations> InstantTranslationSegments { get; set; }
}

SegmentProjectTarget

Represents a single target language within a project, including service configuration and project state.

• Id (long?, nullable) — Internal Text United ID of the translation project for this language pair.
• TargetLanguageId (long?, nullable) — Numeric ID of the target language. Optional if TargetLanguageCode is provided.
• TargetLanguageCode (string) — Target language code (e.g. de-DE). Optional if TargetLanguageId is provided.
• ManagedProject (bool) — When true, orders a managed translation service. When false, the project is created in InPreparation state for internal management.
• ServiceTranslation (bool) — Request human translation.
• ServiceProofreading (bool) — Request human proofreading.
• ServiceAutomaticTranslation (bool) — Request automatic (machine) translation.
• ServiceAdaptiveTranslation (bool?, nullable) — Request adaptive translation.
• ServiceScoring (bool) — Enable quality scoring of machine-translated segments.
• Progress (int?, nullable) — Overall translation progress for this language (percentage).
• Flag (long?, nullable) — A flag value associated with the project.
• State (string) — Current or desired project state (e.g. InPreparation, InProgress).
• Team (List<ProjectTeamMember>) — Users and their roles assigned to this language project.
• ReferenceNumber (string) — User-defined custom value for this language project.
• CustomField1 (string) — Additional external system identifier.
• CustomField2 (string) — Additional external system identifier (second field).
• AdditionalInfo (string) — Additional descriptive information about the project.

Note: service flags can be freely combined per language — for example, enabling both ServiceAutomaticTranslation and ServiceProofreading to get machine translation with human review.

public class SegmentProjectTarget
{
    public long? Id { get; set; }
    public long? TargetLanguageId { get; set; }
    public string TargetLanguageCode { get; set; }
    public bool ManagedProject { get; set; }
    public bool ServiceTranslation { get; set; }
    public bool ServiceProofreading { get; set; }
    public bool ServiceAutomaticTranslation { get; set; }
    public bool? ServiceAdaptiveTranslation { get; set; }
    public bool ServiceScoring { get; set; }
    public int? Progress { get; set; }
    public long? Flag { get; set; }
    public string State { get; set; }
    public List<ProjectTeamMember> Team { get; set; }
    public string ReferenceNumber { get; set; }
    public string CustomField1 { get; set; }
    public string CustomField2 { get; set; }
    public string AdditionalInfo { get; set; }
}

ProjectTeamMember

Represents a user assigned to a language project, including their role and rate information.

• Id (long?, nullable) — Internal system ID of the user.
• Name (string) — Full name (first and last name combined).
• Username (string) — Email address registered in the system.
• Phone (string) — Phone number.
• IsProjectManager (bool) — User has the project manager role.
• IsTranslator (bool) — User has the translator role.
• IsProofreader (bool) — User has the proofreader role.
• IsInCountryReviewer (bool) — User has the in-country reviewer (ICR) role.
• TranslationRate (double) — Translation rate for this user.
• TranslationProductivity (double) — Translation productivity for this user.
• ProofreadedBy (long?, nullable) — ID of the proofreader assigned to this translator. Null if the user is a proofreader.
• ProofreadingRate (double) — Rate per word for proofreading.
• ProofreadingProductivity (double) — Productivity rate for proofreading.

Note: a single team member can hold multiple roles simultaneously via the boolean role flags.

public class ProjectTeamMember
{
    public long? Id { get; set; }
    public string Name { get; set; }
    public string Username { get; set; }
    public string Phone { get; set; }
    public bool IsProjectManager { get; set; }
    public bool IsTranslator { get; set; }
    public bool IsProofreader { get; set; }
    public bool IsInCountryReviewer { get; set; }
    public double TranslationRate { get; set; }
    public double TranslationProductivity { get; set; }
    public long? ProofreadedBy { get; set; }
    public double ProofreadingRate { get; set; }
    public double ProofreadingProductivity { get; set; }
}

InstantTranslationTranslations

The wrapper object returned in instantTranslationSegments. Each entry pairs a source segment with its translations across all requested target languages.

• Source (InstantTranslationSegment) — The source segment that was translated.
• Translations (List<InstantTranslationSegmentTarget>) — Translations for this source segment, one entry per target language.

public class InstantTranslationTranslations
{
    public InstantTranslationSegment Source { get; set; }
    public List<InstantTranslationSegmentTarget> Translations { get; set; }
}

InstantTranslationSegment

Identifies the original source segment within an InstantTranslationTranslations entry.

• CustomId (string) — Your external system's ID for this segment. Matches the customId from the request, allowing you to map translations back to your own content.
• Content (string) — The original text submitted for translation. Accepts plain text or HTML markup.

public class InstantTranslationSegment
{
    public string CustomId { get; set; }
    public string Content { get; set; }
}

InstantTranslationSegmentTarget

Represents a single translation result for one target language within an InstantTranslationTranslations entry.

• LanguageId (long) — Numeric ID of the target language.
• LanguageCode (string) — Language code (e.g. EN-US, DE-AT).
• Content (string) — The translated text. Plain text or HTML markup, matching the format of the source.
• Status (string) — The translation status. Possible values: untranslated, draft, automatic, pretranslated, translated, proofread.

public class InstantTranslationSegmentTarget
{
    public long LanguageId { get; set; }
    public string LanguageCode { get; set; }
    public string Content { get; set; }
    public string Status { get; set; }
}

Conclusion

TextUnited API provides a flexible, programmatic approach to translation that fits a wide range of use cases. Need a quick result? Use the instant translation endpoint. Building a workflow with human review? Create a managed project. Want to retrieve results on your own schedule? Poll the segments endpoint using your custom project ID.

By combining these three capabilities — instant translation, project creation, and segment retrieval — developers can build translation pipelines that scale from simple one-off requests to fully managed, multi-language projects, all without leaving their own application environment.