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 and commonmark 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 guide
context_url (string) - URL for translator context
name (string) - Human-readable name for this request
description (string) - Additional context or instructions
auto_client_review (boolean) - Skip client review step (default: false)
callback_url (string) - URL for completion notifications
plain_text (boolean) - Force plain text processing
char_limit (object) - Character limits per content key
preferred_delivery_date (string) - ISO 8601 date for delivery preference
purchase_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 later
status - Current state of the translation request
created_at - Timestamp when request was submitted
completed_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 returnedid 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.