Send the content you need to translate
Endpoint: POST https://api.tolq.com/v1/translations/requests
Submit your content for translation using this endpoint. The request will be processed according to your specified quality level and language preferences.
Request Structure
Required Parameters
request
(object, required) - Container for all content to translate
- Each key represents a piece of content with a
text
property - Supports optional metadata like
html
andcommonmark
flags
source_language_code
(string, required) - Source language in ISO 639-1 format (two letters)
target_language_code
(string, required) - Target language in ISO 639-1 format
quality
(string, required) - Translation quality level: machine
, translation
, localization
, or expert
Optional Parameters
options
(object, optional) - Additional configuration:
style_guide_reference_id
(number) - ID of your style guidecontext_url
(string) - URL for translator contextname
(string) - Human-readable name for this requestdescription
(string) - Additional context or instructionsauto_client_review
(boolean) - Skip client review step (default: false)callback_url
(string) - URL for completion notificationsplain_text
(boolean) - Force plain text processingchar_limit
(object) - Character limits per content keypreferred_delivery_date
(string) - ISO 8601 date for delivery preferencepurchase_order_code
(string) - Your internal reference code
Example Request
{
"request": {
"a.key": {
"text": "Some text to translate"
},
"b.key": {
"text": "More text to translate",
"html": true
}
},
"source_language_code": "en",
"target_language_code": "de",
"quality": "translation",
"options": {
"style_guide_reference_id": 1,
"context_url": "http://tolq.com/translations_on_this_page",
"name": "My translations",
"description": "A clarification for future reference",
"auto_client_review": false,
"callback_url": "http://www.tolq.com/translations_completed",
"plain_text": "true",
"char_limit": {"a.key": 120},
"preferred_delivery_date": "2025-02-12T16:35:44Z",
"purchase_order_code": "2022-order-18"
}
}
Response
Successful Response (201 Created)
{
"id": 9,
"name": "I like bacon",
"slug": "i-like-bacon",
"context_url": "http://www.tolq.com",
"description": "This is a description",
"created_at": "2014-09-16T13:17:04.368Z",
"completed_at": "2014-09-16T13:17:04.368Z",
"quality": "standard",
"status": "pending"
}
Key Response Fields:
id
- Use this to retrieve your translation laterstatus
- Current state of the translation requestcreated_at
- Timestamp when request was submittedcompleted_at
- Will be populated when translation is finished
Error Response (400 Bad Request)
Returns validation errors for malformed requests. Common issues:
- Missing required fields
- Invalid language codes
- Exceeding content limits
- Invalid quality levels
Important Notes
Automatic Billing
The order will be automatically billed to your account according to your billing information. For cost verification before committing, use the quote endpoint first.
Callback URL
Recommended: Set a callback_url
to receive automatic notifications when translations are complete. This eliminates the need to poll for status updates and provides the same payload as Retrieve a Translation Request.
Language Codes
All language codes must be in ISO 639-1 format (two letters). See the supported languages for available options.
Content Limits
- Maximum 1000 keys per request
- Maximum 1MB total payload size
- See limits documentation for details
Next Steps
After submitting your request:
- Save the returned
id
for tracking your translation - Monitor status via GET requests or callbacks
- Retrieve completed translations when status becomes "finished"
For testing, use "target_language_code": "tq"
(Tolq Latin) which is free and processes immediately.