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:

1. Save the returnedid for tracking your translation
2. Monitor status via GET requests or callbacks
3. Retrieve completed translations when status becomes "finished"

For testing, use "target_language_code": "tq" (Tolq Latin) which is free and processes immediately.