A first-steps guide to using TextUnited API 2.0

This article provides some basic information to a developer on how to start using TextUnited API.

Authentication

Text United API support two methods Authentications
  • Basic Authentication
  • Bearer JWT Authentication

Bearer JWT is a faster and newer technology than Basic Authentication

Basic Authentication

Get the access information for the basic authentication in the portal's menu API integration.

Untitled-1

(The data in the screenshot is anonymized.)

 

Bearer JWT Authentication

To generate a JWT token, you need to send a POST request to the address
https://api.textunited.com/authentication/token
with json request body:

{
"username": "user.email@mail.com",
"password": "userPassword"
}

the response will be json:

{
"AccessToken": "token",
"RefreshToken": "43bbfse9b-2ce4-43c5-988f-434dsa"
}

AccessToken is valid for 30 minutes from the moment of generation

RefreshToken can be used to generate a new AccessToken without having to send the username and password again

In order to get a new AccessToken, you can use again a request as above or use endpoint for refresh token

  POST

  https://api.textunited.com/authentication/RefreshToken

 

  json request body:

{
  "token": "43bbfse9b-2ce4-43c5-988f-434dsa"
}

  Where:
token - it is refresh token which was received during the access token generation

  json response:

{
  "AccessToken": "token",
  "RefreshToken": "43bbfse9b-2ce4-43c5-988f-434dsa"
}

Projects

Create project

 

Request
POST

https://api.textunited.com/ProjectAutomation/Projects

 json request body:

{

  "name": "TestProject", //project name

  "creationDateUtc": "2021-10-07T10:39:01.858Z", //Project creation date (UTC)

  "startDateUtc": "2021-10-07T10:39:01.858Z", //Project start date (UTC)

  "endDateUtc": "2021-10-024T10:39:01.858Z", //Project deadline (UTC)

  "sourceLanguageCode": "de-AT", // sourceLanguageCode. Possible values are ISO codes of languages (e.g. DE-AT for German (Austria), or EN-EN for English (UK))

  "targetLanguageCode": "en-US", // targetLanguageCode. Possible values are ISO codes of languages (e.g. DE-AT for German (Austria), or EN-EN for English (UK))

  "team": [

  {

  "id": XXXXX, // ID of the user

  "name": "User Name", // name of the user

  "username": "user.email@mail.com", // e-mail of the user

  "isProjectManager": true, // Is the user’s role “Project Manager”. Values can be “true” and “false”.

  "isTranslator": true, // Is the user’s role “Translator”. Values can be “true” and “false”.

  "isProofreader": true, // Is the user’s role “Proofreader”. Values can be “true” and “false”.

  "isInCountryReviewer": true, // Is the user’s role “In-Country Reviewer”. Values can be “true” and “false”.

  "translationRate": 0, // The rate paid for the translation. You can keep the default value “0”.

  "translationProductivity": 2500, // How many words the user can translate a day.

  "proofreadedBy": XXXXX, // The ID of the user who will proofread what this user has translated.

  "proofreadingRate": 0, // The rate paid for the translation. You can keep the default value “0”.

  "proofreadingProductivity": 5000 // How many words the user can proofread a day.

  }

  ],

  "domain": 0,

  "files": [//file collection

  {

  "filename": "ThisIsATestFile.txt", // file name

  "content": "VGhpcyBpcyBhIHRlc3QgZmlsZS4=" // content as base64

  }

  ]

,

  "serviceTranslation": true, // Request human translation. Values can be “true” or “false”.

  "serviceProofreading": true, // Request human proofreading. Values can be “true” or “false”.

  "serviceMachineTranslation": true, // Request machine translation. Values can be “true” or “false”.

  "progress": 0, // Used to define the project’s progress. You can leave the default value “0”.

  "projectType": 1, // project type. Enum ProjectType. The value “1” is an internal project (“Me & My Team”).

  "projectState": 2, // project state. Enum ProjectState. Possible values are 1 or 2 (1 is “In Preparation”, 2 is “In Progress”)

  "translationMemoryOnComplete": XXXXXX, // the ID of the translation memory to be used for merging the completed translation.

  "terminologyRepositoryOnComplete": XXXXX, // the ID of the terminology repository to be used for merging the completed translation.

  "postBackUrl": "string" // post back url

}

 

json response


{

  "multilingualProjectId": 0, // Id Multilingual Project. Value is null if project is not multilingual. If workflow has more than one target language, they will be connected into a multi-language project

  "name": "TestProject", //project name

  "description": null, // Additional information about the project.

  "creationDateUtc": "2021-10-07T10:39:01.858Z", //Project creation date (UTC)

  "startDateUtc": "2021-10-07T10:39:01.858Z", //Project start date (UTC)

  "endDateUtc": "2021-10-024T10:39:01.858Z", //Project deadline (UTC)

  "sourceLanguageId": 41, //ID of the source language

  "sourceLanguageCode": "de-AT", // sourceLanguageCode. Possible values are ISO codes of languages (e.g. DE-AT for German (Austria), or EN-EN for English (UK))

  "targetLanguages": [//Collection of target languages and their settings (they are representing individual translation projects)

  {

  "projectId": 127723, //ID of the newly created project

  "machineTranslationToken": null, // A token of the machine translation for a pure-MT translation task (non-project task)

  "targetLanguageId": 97, //ID of the target language

  "targetLanguageCode": "en-US", // targetLanguageCode. Possible values are ISO codes of languages (e.g. DE-AT for German (Austria), or EN-EN for English (UK))

  "agencyId": null, // ID of the agency responsible for handling the project (null for internal projects)

  "team": null, //Team - list of users and their roles in a project

  "serviceTranslation": true, //Request human translation

  "serviceProofreading": true, //Request human proofreading

  "serviceMachineTranslation": true, //Request machine translation

  "referenceNumber": null, //User's custom value for the project

  "progress": null, //Overall progress of the project.

  "flag": null, //Flag of project

  "projectState": 2, //Current or desired state of the project. ProjectState enum

  },

  {…}

  ],

  "domain": null, //Project domain

  "workflowId": null, // ID of the workflow that configures the project

  "files": [ //file collection

  {

  "id": null, //file id

  "filename": "ThisIsATestFile.txt ", //file name

  "content": "VGhpcyBpcyBhIHRlc3QgZmlsZS4=”, //file content as base64, null if get all file project

  "modifiedUtc": null, //date of the last modification

  "size": 0, //size in bytes

  "sizeMB": 0, //size in MB round 2

  "extension": ".txt", //file extension

  "documentStatus": 0, //status of the document processing (DocumentStatus Enum)

  "words": null, // Words number

  "status": "null, // Status of file

  "subdir": null // file subdir

  }

  ],

 

  "uploadToken": null, //upload token

 

  "projectType": 1, // project type. Enum ProjectType

  "projectState": 2, // project state. Enum ProjectState. Possible value 1 or 2

 

  "translationMemoryOnComplete": XXXXXX, // the ID of the translation memory to be used for merging the completed translation.

  "terminologyRepositoryOnComplete": XXXXX, // the ID of the terminology repository to be used for merging the completed translation.

  "ownerId": XXXXX, // ID of the user who created/owns the project.

  "ownerName": User Name,// Name of the user who created/owns the project.

  "postBackUrl": "string" // Url for sending back file

}

 

Get project list

Request
Get

https://api.textunited.com/ProjectAutomation/Projects

Optional query parameters

long? sourceLanguageId - Filters projects by an ID of the source language (optional),

string sourceLanguageCode - Filters projects by a code of the source language (e.g. "de-AT") (optional),

long? targetLanguageId - Filters projects by an ID of the target language (optional),

string targetLanguageCode - Filters projects by a code of the target language (e.g. "en-US") (optional),

bool? isMultilingual - When true, provides a list of all projects that belong to multilingual projects (optional)

without json request body

 

Response

Json with projects list

[

  {

  "id": 127699, // System ID of the project.

  "name": "ProjectTestWorkflow", // Name of the project.

  "description": "", // Additional information about the project

  "creationDateUtc": "2021-08-14T17:06:34.921Z", // Date of creation (UTC time).

  "sourceLangId": 41, // ID of the source language (see Languages for more information about languages).

  "targetLanguageId": 97, // ID of the target language (see Languages for more information about languages).

  "sourceLanguageCode": "EN", // Two-letter code of the source language.

  "targetLanguageCode": "RU", // Two-letter code of the target language.

  "startDateUtc": "2021-08-10T00:00:00Z", // Date when the project starts (UTC time).

  "endDateUtc": "2021-09-10T00:00:00Z", //Date when the project ends (UTC time)

  "stateId": 2, // Id of the current state of the project.

  "state": "In progress", // Current state of the project.

  "ownerId": 66454, // ID of the user who created/owns the project.

  "ownerName": "Kolesnykov Anatolii", // Name of the user who created/owns the project

  "managerId": 66454, // Name of the user who is responsible for managing the project. "managerName": "Kolesnykov Anatolii", // Name of the user who is responsible for managing the project

  "managerPhone": null, // Phone number of the project manager

  "managerEmail": null, //Email address of the project manager.

  "referenceNumber": "", // Additional information about the project reference number.

  "lockContextMatches": null, // Boolean value indicating whether context matches are locked or not. (only in details project)

  "lock100Matches": null, //Boolean value indicating whether 100% matches are locked or not.(only in details project)

  "progress": 0, // Overall progress of the project

  "translationProgress": 0, // Progress of the translation task

  "proofreadingProgress": 0, // Progress of the proofreading task

  "analysis": null, // Collection of Analysis Item objects (see below). (only in details project)

  "team": null, // Team - list of users and their roles in a project. (only in details project)

  "translationMemories": null, // Translation memories linked to the project. Collection of TranslationMemory objects (only in details project)

  "filesCount": null, / / Number of files uploaded to the project. (only in details project)

  "customField1": null, // Additional information identifying the project in an external system*. (only in details project)

  "customField2": null, // Additional information identifying the project in an external system*. (only in details project)

  "isMultilingual": true, // Boolean value indicating whether project is part of multilingual

  "multilingualId": 347, // Multilingual Id

 

  "postBackUrl": null // Post Back Url (only in details project)

  "agencyId": null // agency id (only in details project)

  },

  {…}

]

 

Get project details

Request

 

Get
https://api.textunited.com/ProjectAutomation/Projects/{id}

Without request body

https://api.textunited.com/ProjectAutomation/Projects/127696

 

Response

Json with project object

{

  "id": 127699, // System ID of the project.

  "name": "ProjectTestWorkflow", // Name of the project.

  "description": "", // Additional information about the project

  "creationDateUtc": "2021-08-14T17:06:34.921Z", // Date of creation (UTC time).

  "sourceLangId": 41, // ID of the source language (see Languages for more information about languages).

  "targetLanguageId": 97, // ID of the target language (see Languages for more information about languages).

  "sourceLanguageCode": "EN", // Two-letter code of the source language.

  "targetLanguageCode": "RU", // Two-letter code of the target language.

  "startDateUtc": "2021-08-10T00:00:00Z", // Date when the project starts (UTC time).

  "endDateUtc": "2021-09-10T00:00:00Z", //Date when the project ends (UTC time)

  "stateId": 2, // Id of the current state of the project.

  "state": "In progress", // Current state of the project.

  "ownerId": 66454, // ID of the user who created/owns the project.

  "ownerName": "Kolesnykov Anatolii", // Name of the user who created/owns the project

  "managerId": 66454, // Name of the user who is responsible for managing the project. "managerName": "Kolesnykov Anatolii", // Name of the user who is responsible for managing the project

  "managerPhone": null, // Phone number of the project manager

  "managerEmail": null, //Email address of the project manager.

  "referenceNumber": "", // Additional information about the project reference number.

  "lockContextMatches": true, // Boolean value indicating whether context matches are locked or not. (only in details project)

  "lock100Matches": false, // Boolean value indicating whether 100% matches are locked or not

  "progress": 0, // Overall progress of the project

  "translationProgress": 0, // Progress of the translation task

  "proofreadingProgress": 0, // Progress of the proofreading task

 

  "analysis": [. // Collection of Analysis Item objects (see below)

  {

 

  "range": "Context Match", //Matching range (descriptive value).

  "segments": 0, //Number of segments in the given matching range.

  "words": 0, //Number of words in the given matching range.

  "characters": 0, //Number of characters in the given matching range

  "percent": 0.0 //Percentage of words from the given matching range within the total number of words in the project

  },

  {

  "range": "Repetitions",

  "segments": 0,

  "words": 0,

  "characters": 0,

  "percent": 0.0

  },

  {

  "range": "100%",

  "segments": 0,

  "words": 0,

  "characters": 0,

  "percent": 0.0

  },

  {

  "range": "85 % - 99 %",

  "segments": 0,

  "words": 0,

  "characters": 0,

  "percent": 0.0

  },

  {

  "range": "70 % - 84 %",

  "segments": 0,

  "words": 0,

  "characters": 0,

  "percent": 0.0

  },

  {

  "range": "0 % - 69 %",

  "segments": 0,

  "words": 0,

  "characters": 0,

  "percent": 0.0

  },

  {

  "range": "Total",

  "segments": 0,

  "words": 0,

  "characters": 0,

  "percent": 100.0

  }

  ],

 

  "team": [ //Team - list of users and their roles in a project

  {

 

  "id": 66454, // ID of the user in system

  "name": "Kolesnykov Anatolii", //User's name (first name and last name combined).

  "username": "anatoliik@textunited.com", //Username (email address) registered in the system

  "phone": "", //User's phone number.

  "isProjectManager": false, //Project manager role in project

  "isTranslator": true, //Translator role in project

  "isProofreader": false, //Proofreader role in project

  "isInCountryReviewer": false, //ICR role in project

  "translationRate": 0.0, //Translation rate

  "translationProductivity": 2500.0, // Translation productivity.

  "proofreadedBy": null, //ID of the proofreader assigned to the translator (in case of proofreader, the field has a null value).

  "proofreadingRate": 0.0, //Rate for one word of proofreading

  "proofreadingProductivity": 10000.0 //Rate for one word of proofreading.

  }

  ],

  "translationMemories": [ //Translation memories linked to the project. Collection of TranslationMemory objects (see below)

  {

 

  "id": 204447, //System ID of the translation memory

  "name": "ProjectTestWorkflow", //Name of the translation memory.

 

  "entries": 0, //Number of entries

  "modificationDateUtc": "2021-08-14T17:06:34.921Z" //Date of last modification (UTC time).

  }

  ],

  "filesCount": 1, // Number of files uploaded to the project

  "customField1": "", //Additional information identifying the project in an external system*.

  "customField2": "", //Additional information identifying the project in an external system*.

  "isMultilingual": true, //Boolean value indicating whether project is part of multilingual

  "multilingualId": 347, //Multilingual Id

  "postBackUrl": "https://textUnited.com/ExamplePostBackUrl" //Post Back Url

 

  "agencyId": 64801 // agency id

}

 

 

 

 

Project Files

Get project file list

 

Request
Get

 

https://api.textunited.com/ProjectAutomation/ProjectFiles?projectId={projectId}

Query parameters

long projectId – id of the project to get the files for

https://api.textunited.com/ProjectAutomation/ProjectFiles?projectId=127696

Response

Json with list of file project objects

 

[

  {

  "id": 1887558, //file id

  "filename": "test.docx", //file name

  "content": null, //file content as base64, null if get all file project

  "modifiedUtc": "2021-08-15T14:00:40.027849Z", //date of the last modification

  "size": 13262, //size in bytes

  "sizeMB": 0.01, //size in MB round 2

  "extension": ".docx", //file extension

  "documentStatus": 0, //status of the document processing (DocumentStatus Enum)

  "words": 303, // Words number

  "status": "NotTranslated", // Status of file

  "subdir": "" // file subdir

  },

 {…}

]

 

 

Downloading files

 

Request

Get

https://api.textunited.com/ProjectAutomation/ProjectFiles/projectId={projectId}&fileId={fileId}&type={type}

Query parameters

long projectId – id of the project to get the file for

long fileId – project file id.

String type - file type; possible value: source; translated; delivery

 

 

https://api.textunited.com/ProjectAutomation/ProjectFiles?projectId=127701&fileId=1887558&type=source Response

Json with project object

[

  {

  "id": 1887558, //file id

  "filename": "test.docx", //file name

  "content": “UEsDBBQABg…”, //file content as base64

  "modifiedUtc": "2021-08-15T14:00:40.027849Z", //date of the last modification

  "size": 13262, //size in bytes

  "sizeMB": 0.01, //size in MB round 2

  "extension": ".docx", //file extension

  "documentStatus": 0, //status of the document processing (DocumentStatus Enum)

  "words": 303, // Words number

  "status": "NotTranslated", // Status of file

  "subdir": "" // file subdir

  }

]

 

Upload files

 

Request


POST
https://api.textunited.com/ProjectAutomation/ProjectFiles/projectId={projectId}

Query parameters

long projectId – id of the project to get the file for

 

 https://api.textunited.com/ProjectAutomation/ProjectFiles?projectId=127696

json request body:

 

[

  {

  "filename": "file1.docx", //files name

  "content": "UEsDBBQABgAIAAAA…" //file content base6

  },

  {

  "filename": "file2.docx",

  "content": "UEsDBBQABgAIAAAA…"

  },

  {…}

]

 

 

Response

Json with list of file project objects

[

  {

  "id": 1887559, //file id

  "filename": " file1.docx", //file name

  "content": null, //file content as base64, null if get all file project

  "modifiedUtc": "2021-08-15T14:00:40.027849Z", //date of the last modification

  "size": 13262, //size in bytes

  "sizeMB": 0.01, //size in MB round 2

  "extension": ".docx", //file extension

  "documentStatus": 0, //status of the document processing (DocumentStatus Enum)

  "words": 303, // Words number

  "status": "NotTranslated", // Status of file

  "subdir": "" // file subdir

  },

  {

  "id": 1887560, //file id

  "filename": " file2.docx", //file name

  "content": null, //file content as base64, null if get all file project

  "modifiedUtc": "2021-08-15T14:00:40.027849Z", //date of the last modification

  "size": 13262, //size in bytes

  "sizeMB": 0.01, //size in MB round 2

  "extension": ".docx", //file extension

  "documentStatus": 0, //status of the document processing (DocumentStatus Enum)

  "words": 303, // Words number

  "status": "NotTranslated", // Status of file

  "subdir": "" // file subdir

  },

 {…}

]

 

 

Upload function supported only file, if need upload string list as
100:Create project
101:Create customer
102:Edit customer

You can create json or xml file which contains all string

 

 

 

Enums

 

  DocumentStatus Enum

  /// <summary>

  /// Processing in progress

  /// </summary>

  Waiting = 0,

 

  /// <summary>

  /// All the files were correctly processed

  /// </summary>

  Ok = 1,

 

  /// <summary>

  /// All the files are erronous

  /// </summary>

  Error = 2,

 

  /// <summary>

 

  /// At least one file was not processed

  /// </summary>

  WarningNotProcessed = 3

 

 

 ProjectType

  /// <summary>

  /// Regular project

  /// </summary>

  Standard = 1,

 

 ProjectState

  Undefined = 0,

  InPreparation = 1,

  InProgress = 2,

  Completed = 3,

  Enquiry = 4,

  Archiving = 6,

  InArchive = 7,

  Holding = 9,

  OnHold = 8,

  SystemProcessing = 10,

  SystemProcessingError = 11,

  All = -1