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.
(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
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