NAV
shell

Introduction

ImmiTranslate provides a REST API for the creation and management of human-powered translation services. Our API operates over HTTPS and utilizes standard HTTP response codes. Our responses are exclusively in JSON. Our API is designed to be consumed "server-side" only.

Currently, we only support Certified Translations via our API. Business Translations are not yet supported.

The examples provided are cURL commands that can be used to test functionality.

If you have questions or need assistance integrating with our API, reach out to our platform team at [email protected].

Authentication

To test your API key, use this code:

curl "https://api.immitranslate.com/v1/ping" \
  -H "Authorization: Bearer a1s2d3f4q5w6e7r8t9y0"

Make sure to replace a1s2d3f4q5w6e7r8t9y0 with your API key.

The above command returns 200 OK and JSON structured like this:

{
  "result": "success"
}

ImmiTranslate uses API keys to authenticate access. Once you have an account, head to the API settings page to generate or view your API keys.

All calls to the API require authentication with an API key.

Authorization: Bearer a1s2d3f4q5w6e7r8t9y0

Endpoints

The production API endpoint is:

https://api.immitranslate.com/v1

The sandbox API endpoint is:

https://sandbox-api.immitranslate.com/v1

Sandbox

ImmiTranslate provides a sandbox API for testing. For information on obtaining access to the Sandbox API, email our platform team at [email protected] and we'll get back to you.

Changelog

2026-08-13

2026-08-02

2026-08-01

2026-06-13

2026-06-12

2025-07-18

2024-06-20

2022-02-19

Languages

Language Object

Field Type Description
code String ISO-639 Language Code
name String Language Name

List Languages

curl "https://api.immitranslate.com/v1/languages" \
  -H "Authorization: a1s2d3f4q5w6e7r8t9y0"

The structure of the List Languages response is below:

{
  "data": [
    {
      "code": "al",
      "name": "Albanian"
    },
    {
      "code": "am",
      "name": "Amharic"
    },
    {
      "code": "ar",
      "name": "Arabic"
    },
    ...
  ]
}

Retrieves a list of available languages for translation. The source language and target language must be provided when placing an order through the API.

Languages are periodically added, but it is most likely safe to cache the results from this API method.

Account

Account Object

Field Type Description
token String The unique identifier for the account associated with the API key
name String A friendly name for this account, if set.
number String The account name as published on PDF invoices, receipts, and used internally.
users Array A list of all the associated users with this account.

Get Account

curl "https://api.immitranslate.com/v1/account" \
  -H "Authorization: a1s2d3f4q5w6e7r8t9y0"

The structure of the Account response is below

{
  "data": {
    "token": "account_a1b2c3d4",
    "name": "Sandbox Account",
    "number": "89413008229483",
    "users": [
      {
        "email": "[email protected]",
        "token": "user_a1b2c3d4",
        "first_name": "Sample",
        "last_name": "User",
        "status": "active",
        "phone_number": null,
        "whatsapp_number": null,
        "created_at": "2025-07-16T20:27:17+00:00",
        "updated_at": "2025-07-16T20:27:17+00:00"
      }
    ],
    "sources": [
      {
        "token": "source_a1b2c3d4",
        "label": "US Bank Account ending in 4321",
        "source_type": "us_bank_account",
        "currency": "usd",
        "processor": "stripe",
        "billing_country": null,
        "billing_postal_code": null,
        "is_saved": true,
        "is_default": false,
        "card_exp_month": null,
        "card_exp_year": null,
        "card_funding_type": null,
        "card_last4": null,
        "card_cvc_check": null,
        "card_avs_check": null,
        "card_brand": null,
        "us_bank_account_type": "checking",
        "us_bank_account_holder_type": "individual",
        "us_bank_name": null,
        "us_bank_last4": "4321",
        "us_bank_routing_number": "110000000",
        "paypal_email": null,
        "paypal_phone": null,
        "created_at": "2025-07-18T18:44:23+00:00",
        "updated_at": "2025-07-18T18:44:23+00:00"
      },
      {
        "token": "source_x1y2z3",
        "label": "Account Invoice",
        "source_type": "account_invoice",
        "currency": "usd",
        "processor": "immitranslate",
        "billing_country": null,
        "billing_postal_code": null,
        "is_saved": true,
        "is_default": true,
        "card_exp_month": null,
        "card_exp_year": null,
        "card_funding_type": null,
        "card_last4": null,
        "card_cvc_check": null,
        "card_avs_check": null,
        "card_brand": null,
        "us_bank_account_type": null,
        "us_bank_account_holder_type": null,
        "us_bank_name": null,
        "us_bank_last4": null,
        "us_bank_routing_number": null,
        "paypal_email": null,
        "paypal_phone": null,
        "created_at": "2025-07-18T18:46:57+00:00",
        "updated_at": "2025-07-18T18:46:57+00:00"
      }
    ],
    "created_at": "2025-07-16T20:26:20+00:00",
    "updated_at": "2025-07-16T20:29:04+00:00"
  }
}

Retrieves information about the account associated with this API key, including a list of the users on the account and available billing methods to use for this account.

Files

File Object

Field Type Description
id String This is the file ID (sometimes referred to as a token) and is unique to each file. File operations are conducted using this as a primary key.
filename String The filename, as received, upon uploading.
size String The file size in bytes
sha256 String The SHA-256 hash of the file as uploaded.
size_label String A human readable file size label.
mimetype String The mimetype based on the file name or as provided upon upload.
url String A short-lived URL to download the related file. The default time limit is 15 minutes.
upload_source String A tag for the original uploading application, typically api
source_word_count Integer The number of words in the source file. For machine-readable formats (DOC, DOCX, TXT, etc..) this is almost always set. For non-machine readable (PDF, JPEG, etc..) this is most likely not set.
page_count Integer The number of pages within the file. For PDF, this is the number of pages in the PDF. For image files, this defaults to 1.
language_detection String A ISO-639 Language Code based on detection. If the language is known and can be provided, it will default to the provided value.
pdf_title String For PDFs only: The title according to metadata
pdf_creator String For PDFs only: The creator according to metadata
pdf_last_modified String For PDFs only: The last modification date according to metadata
source_metadata Object Source Metadata Object
integrations Array If the file was uploaded with a native integration, additional metadata related to that integration is provided here.
created_at DateTime The timestamp for the file creation
updated_at DateTime The timestamp for the file update, typically refers to the last time metadata was changed.

Upload File

POST https://api.immitranslate.com/v1/files

Sample upload request (using remote URL):

curl -X POST https://api.immitranslate.com/v1/files \
  -H "Authorization: Bearer a1s2d3f4q5w6e7r8t9y0" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "url=https://api-test-files.immitranslate.com/test-document-de-scanned.pdf"

Sample upload request (using local File):

curl -X POST https://api.immitranslate.com/v1/files \
  -H "Authorization: Bearer a1s2d3f4q5w6e7r8t9y0" \
  -F "[email protected]"

The Upload File Response:

{
    "data": {
        "id": "file...",
        "filename": "immitranslate-api-test-file-standard.pdf",
        "size": 157231,
        "sha256": "6815eeab802020c22288664ad0ff64870ac9e3eb56fd5b098d6fe558a4c39ed1",
        "mimetype": "application/pdf",
        "url": "https://...",
        "created_at": "2022-02-26T20:01:49+00:00",
        "updated_at": "2022-02-26T20:01:49+00:00",
        "upload_source": "api",
        "source_word_count": null,
        "page_count": 1,
        "language_detection": null,
        "pdf_title": "Scan_2022-02-17T153135",
        "pdf_creator": "Smart Touch 1.9",
        "pdf_last_modified": "2022-02-17T20:32:54+00:00",
        "integrations": []
    }
}

The Upload File request consists of a form data request with either the Content-Type: multipart/form-data header set and a file contained in the variable file or a Content-Type: application/x-www-form-urlencoded form with the parameter url.

Request Parameters

Field Type Required Description
file File Yes (If url not provided) multipart/form-data File
url String Yes (If file not provided) A publicly accessible URL of the file.

Permitted File Types

Quotes

Quote Object

Field Type Description
token String A unique identifier for the specific quote, typically in the format quote_a1b2c3d4e5f6g7h8. This is the ID used throughout operations on this quote object.
number String A human-centric unique identifier for all quotes, typically in the format 1234567-89
source_language String Source Language (ISO-639 Language Code)
target_language Array Target Language (ISO-639 Language Code)
services Object Specifies the relevant services and certain configuration related to them
translation_type String Either certified or business - This API currently only supports certified translation quotes
certification String Either certified or notarized. A notarized translation includes a standard certification that is also stamp and notarized by a notary public.
delivery String Either digital or physical. A physical copy incurs an additional charge. A printed hard copy is sent to the recipient if this option is selected.
turnaround String Either standard
webhook String Optional HTTPS URL that receives webhook events for this quote and any resulting order, in addition to the account-level webhook URL (if configured).
partner String The token of the partner this quote is attributed to, beginning with prt_. Only present when the quote was attributed to a partner.

Create Quote

POST https://api.immitranslate.com/v1/quotes

A basic example with a remote file 

{
  "files": [
    "https://api-test-files.immitranslate.com/test-document-de-scanned.pdf"
  ],
  "services": {
    "translation": true,
    "translation_options": {
      "source_language": "de",
      "target_language": ["en"],
      "translation_type": "certified",
      "certification": "certified",
      "delivery": "digital",
      "turnaround": "standard"
    }
  }
}

The structure of the Create Quote body is below:

{
  "files": [
    "file_a1b2c3d4",
    "https://api-test-files.immitranslate.com/test-document-de-scanned.pdf"
  ],
  "services": {
    "translation": true,
    "translation_options": {
      "source_language": "es",
      "target_language": ["en"],
      "translation_type": "certified",
      "certification": "certified",
      "delivery": "digital",
      "turnaround": "standard",
      "deadline": null,
      "notes_names_places": "Example name",
      "notes": "Example notes"
    },
    "credential_evaluation": true,
    "credential_evaluation_options": {
      "evaluation_type": "course_by_course_evaluation",
      "source_country": "MX",
      "subject_name": "Test Persson",
      "subject_dob": "1990-01-15",
      "institution_name": "Ciudad Universitaria, Mexico City",
      "target_country": "US",
      "target_organization": "uscis",
      "purpose": "immigration",
      "delivery": "physical",
      "turnaround": "standard",
      "deadline": null,
      "notes": "Example notes"
    },
    "currency_conversion": true,
    "currency_conversion_options": {
      "target_currency": "usd",
      "source_currency": "eur",
      "conversion_date": "2020-04-01"
    },
    "shipping": true,
    "shipping_options": {
      "shipping_service": "delivery_fedex_2day",
      "address": {
        "recipient": "Test Persson",
        "line1": "601 13TH ST NW",
        "line2": "STE 900S",
        "city": "WASHINGTON",
        "region": "DC",
        "postal_code": "20005",
        "country": "US"
      }
    }
  },
  "reference": "TL-1138",
  "case_reference": "AA00039212",
  "client_reference": "CL-0001",
  "webhook": "https://example.com/webhooks/immitranslate",
  "partner": {
    "token": "prt_a1b2c3d4e5f6g7h8i9j0a1b2c3d4e5f6"
  },
  "use_cases": [
    {
      "use_case": "immigration",
      "country": "US"
    }
  ],
  "notes": "Additional comments can be provided here!",
  "deadline": "2022-03-04 15:00:00"
}

The Create Quote request is the primary method of creating new orders.

Request Parameters

Field Type Required Description
files Array Yes Either the id for a File Object or a publicly accessible file starting with https://. At least 1 file is required. The response mimetype must be of a permitted file type.
services Object Yes Services Object - Specifies the relevant services and certain related configuration items.
reference String No Custom reference provided during the quote process and copied into subsequent orders.
client_reference String No Custom reference to identify the client, provided during the quote process and copied into subsequent orders.
case_reference String No Custom reference to identify the case/matter, provided during the quote process and copied into subsequent orders.
webhook String No An HTTPS URL that will receive webhook events for this quote and any resulting order, in addition to your account-level webhook URL (if configured). Must begin with https://.
partner Object No Partner Object - Attributes the quote and any resulting order to a partner, and optionally identifies a referred customer. The partner token may alternatively be sent as the Partner-Id HTTP header.
autobuy Boolean No If true, the quote is automatically created alongside an order and the default payment method will be charged. Note: The final value of the order will be updated once the cost is calculated.
use_cases Array No Array of Use Case Objects - Specifies information about the intended use of the translation and other services.
deadline DateTime No In YYYY-MM-DD HH:MM:SS format, the intended deadline. This information will be taken into consideration for pricing. If the service classification is expedited or faster, we intend on completing the services as close to the deadline as possible.
notes String No General notes for our team to consider when providing a quote for the services.

Pay Quote

POST https://api.immitranslate.com/v1/quotes/{token}/pay \
  -H "Authorization: a1s2d3f4q5w6e7r8t9y0"

An example Pay Quote request is provided below.

{
  "payment_method": "payment_method_a1b2c3d4e5f6g7h8i9j"
}

An example response to the Pay Quote Request is provided below.

{
  "result": "success",
  "data": {
    "order": {
      "token": "order_a1s2d3f4q5w6e7r8t9y0"
    }
  }
}

After receiving the Quote Ready event, a quote is ready for payment. This method triggers the creation of a new Order.

Pay Quote Request

Field Type Required Description
payment_method String Yes This is the token representing the preferred payment method for this particular quote. To retrieve valid payment methods, consult the Accounts section.

Cancel Quote

DELETE https://api.immitranslate.com/v1/quotes/{token} \
  -H "Authorization: a1s2d3f4q5w6e7r8t9y0"

The Cancel Quote request is not required, as quotes do expire, however it can assist our team with tracking sales outcomes.

Query Parameters

Parameter Required Default Description
reason false null Either price_too_high, turnaround_unacceptable, no_longer_required, client_declined, wrong_services, wrong_files, resubmitting_later

Services Object

Field Type Required Description
translation Boolean No Specifies whether the translation service is requested. If true, the Translation Options object should be provided in the services object.
credential_evaluation Boolean No Specifies whether to include a credential evaluation in this quote. If true, the Credential Evaluation Options object should be provided in the services object.
expert_opinion_letter Boolean No Specifies whether to include an expert opinion letter in this quote. If true, the Expert Opinion Letter Options object should be provided in the services object.
currency_conversion Boolean No Specifies whether to include a currency conversion in this quote. If true, the Currency Conversion Options object should be provided.
apostille Boolean No Specifies whether to include an apostille of the translation. If true, the Apostille Options object should be provided in the services object.
shipping Boolean No If any delivery type is set to physical, this value should be set to true and the Shipping Options object should be provided in the services object.

Translation Options

Field Type Required Description
source_language String Yes Source Language (ISO-639 Language Code)
target_language Array Yes Array of Target Languages (ISO-639 Language Code)
translation_type String Yes Either certified or business. Defaults to certified. This API currently only supports certified translation quotes
certification String No Either certified or notarized. Defaults to certified. A notarized translation includes a standard certification that is also stamp and notarized by a notary public.
delivery String No Either digital or physical. Defaults to digital. A physical copy incurs an additional charge. A printed hard copy is sent to the recipient if this option is selected.
turnaround String No Either standard or expedited. Defaults to standard
deadline DateTime No Optional deadline information provided in YYYY-MM-DD HH:MM:SS format.
notes_names_places String No The preferred spelling of names, dates, and locations to take into consideration.
notes String No Additional notes for the translators to take into consideration. A secondary reference PDF can be provided in the files section.

Credential Evaluation Options

Field Type Required Description
evaluation_type String No Either diploma_evaluation or course_by_course_evaluation
source_country String No ISO-3166 Country Code of the country where the credential was issued.
subject_name String Yes The name of the subject of the credential evaluation.
subject_dob Date Yes The date of birth of the subject in YYYY-MM-DD format.
institution_name String Yes The name of the institution that issued the credential.
target_country String Yes ISO-3166 Country Code of the country where the credential will be used. Currently only valid for US usage.
target_organization String No The name of the organization where this credential will be used. For example, uscis for immigration purposes.
purpose String Yes The intended purpose of the credential evaluation. Either licensing, education, employment, or immigration
delivery String No Either digital or physical. Defaults to digital. A physical copy incurs an additional charge. A printed hard copy is sent to the recipient if this option is selected.
turnaround String No Either standard, expedited, or same_day. Defaults to standard
deadline DateTime No Optional deadline information provided in YYYY-MM-DD HH:MM:SS format.
notes String No Additional notes for the evaluator to take into consideration. A secondary reference PDF can be provided in the files section.

Expert Opinion Letter Options

Field Type Required Description
visa_type String Yes The intended visa type for the subject of the EOL
subject_name String Yes The name of the subject of the credential evaluation.
subject_dob Date Yes The date of birth of the subject in YYYY-MM-DD format.
delivery String No Either digital or physical. Defaults to digital. A physical copy incurs an additional charge. A printed hard copy is sent to the recipient if this option is selected.
turnaround String No Either standard, expedited, or same_day. Defaults to standard
deadline DateTime No Optional deadline information provided in YYYY-MM-DD HH:MM:SS format.
notes String No Additional notes for the expert to take into consideration. A secondary reference PDF can be provided in the files section.

Currency Conversion Options

Field Type Required Description
target_currency String Yes ISO-4217 Currency Code that the currency should be converted to.
source_currency String No ISO-4217 Currency Code of the currency that the document currently contains.
conversion_date Date No The date, in YYYY-MM-DD format, that the conversion rate should be derived from. If this value is not provided, the conversion will commence from the date the document was originally issued. For example, if a financial statement for March of 2020 was issued on April 1, 2020, the currency conversion rate would be derived from the exchange rate of the currency pair on April 1, 2020.

Apostille Options

Field Type Required Description
target_country String Yes ISO-3166 Country Code of the country where the apostille will be used. The country must be a signatory to the Hague Convention
authorizing_state String No Currently, MD is the only option. In the future, other supported states will be added.
turnaround String No Either standard or expedited. Defaults to standard. Same-day
deadline DateTime No Optional deadline information provided in YYYY-MM-DD HH:MM:SS format.
notes String No Additional notes for our couriers to take into consideration. A secondary reference PDF can be provided in the files section.

Notarization Options

Field Type Required Description
notarization_state String No Currently, MD is the only option. In the future, we plan to add additional states (TX, VA, and FL).
turnaround String No Either standard or expedited. Defaults to standard. Same-day
deadline DateTime No Optional deadline information provided in YYYY-MM-DD HH:MM:SS format.
notes String No Additional notes for the translators to take into consideration. A secondary reference PDF can be provided in the files section.

Shipping Options

Field Type Required Description
shipping_service String Yes A complete list of available shipping options and respective carriers is available in the Shipping Service Options.
address Object Yes The address that the documents should be delivered to, provided as a Shipping Address Options object.

Shipping Service Options

Code Name Carrier Delivery Timeframe Notes
delivery_fedex_2day FedEx 2-Day® FedEx 2 Business Days Recommended US Option; US Only; Saturday Delivery Included
delivery_fedex_priority_overnight FedEx Priority Overnight® FedEx 1 Business Day US Only; 10:30 AM delivery to most addresses
delivery_fedex_standard_overnight FedEx Standard Overnight® FedEx 1 Business Day US Only; 4:30 PM delivery to businesses; 8:00 PM delivery to residences
delivery_dhl_express_envelope DHL Express Worldwide Envelope DHL Varies Recommended Intl Option. 2-4 Day Delivery to North America, Europe; 4-8 Day Delivery to Asia;
delivery_usps_priority_domestic USPS Priority Mail® Domestic USPS 2-3 Business Days US Only; Saturday Delivery Included
delivery_usps_priority_domestic USPS Priority Mail® International USPS 2-4 Weeks International Option
delivery_usps_express_domestic USPS Priority Mail Express® Domestic USPS 1-2 Business Days US Only; Saturday Delivery Included
delivery_usps_express_international USPS Priority Mail Express® International USPS 1-3 Weeks International Option

Shipping Address Options

Field Type Required Description
recipient String Yes The name of the recipient
phone_number String No A valid phone number in E.164 format for the recipient. This is optional for domestic (US) shipping, but is required for international shipping.
line1 String Yes Street address
line2 String No Suite, apartment number, etc..
city String Yes City
region String Yes State, province, or region. If the country is US, a 2 digit State abbreviation should be provided. If the country is CA, a 2 digit Province abbreviation should be provided. Other countries can use full names in the region field.
postal_code String Yes ZIP or Postal code. If the country is US, a 5 digit ZIP code should be provided.
country String Yes ISO-3166 Country Code of the target country.

Use Cases Object

Field Type Required Description
use_case String Yes Either immigration,travel,legal,academic,financial,medical,dmv,business,other
country String No ISO-3166 Country Code for the related use-case
agency String No For immigration, this would be uscis in the US. Other agency names can be provided as well.
date DateTime No YYYY-MM-DD HH:MM:SS format. For travel, this would be the arrival date. Relevant dates can be provided as necessary.
court String No For legal, this would be the court the translation or other documents will be submitted.
school String No For education, this would be the school or academic institution where the documents will be submitted.
region String No For dmv, we may adjust pricing to comply with certain state DMV restrictions. For other use cases, this is the relevant region where the documents will be submitted.

Partner Object

An example Partner object within a Create Quote request:

{
  "partner": {
    "token": "prt_a1b2c3d4e5f6g7h8i9j0a1b2c3d4e5f6",
    "referral": {
      "email": "[email protected]",
      "name": "Test Persson",
      "phone": "+12025551234",
      "company": "Example Law Firm"
    }
  }
}

The Partner object attributes a quote (and any resulting order) to a partner, and optionally identifies the customer the partner is referring.

The partner token may alternatively be provided as the Partner-Id HTTP header on the Create Quote request. If both the header and the partner.token body field are provided, the body field takes precedence. An invalid partner token, or a token for a partner that does not belong to your account, returns a 403 response with the code partner_not_found.

Field Type Required Description
token String No Your partner token, beginning with prt_. Contact our platform team if you do not have your partner token. The quote and any resulting order will be associated with this partner.
referral Object No Identifies the customer being referred by the partner. When provided, the quote is placed on the referred customer's account (created automatically if it does not exist) instead of your API account.
referral.email String No The referred customer's email address. Required for the referral to take effect.
referral.name String No The referred customer's full name.
referral.phone String No The referred customer's phone number.
referral.company String No The referred customer's company or organization name.

Orders

List Orders

curl "https://api.immitranslate.com/v1/orders" \
  -H "Authorization: a1s2d3f4q5w6e7r8t9y0"

The structure of the List Orders response is below:

{
  "data": [
    {
      "url": "https://api.immitranslate.com/v1/orders/order_a1s2d3f4q5w6e7r8t9y0",
      "token": "order_a1s2d3f4q5w6e7r8t9y0",
      "number": "123456-123456",
      "status": "created",
      "total": 2500,
      "app": null,
      "certification": "certified",
      "translation_type": "certified",
      "delivery": "digital",
      "turnaround": "standard",
      "source_language": "en",
      "target_language": [
        "es"
      ],
      "reference": null,
      "client_reference": null,
      "case_reference": null,
      "created_at": "2022-01-01T00:45:09+00:00",
      "updated_at": "2022-01-01T04:37:17+00:00",
      "intake_processed_at": null,
      "translator_assigned_at": null,
      "translator_accepted_at": null,
      "translator_completed_at": null,
      "proofreader_completed_at": null,
      "all_translations_approved_at": null,
      "notarized_at": null,
      "shipped_at": null,
      "completed_at": null
    }
  ],
  "links": {
    "first": "https://api.immitranslate.com/v1/orders?page=1",
    "last": "https://api.immitranslate.com/v1/orders?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://api.immitranslate.com/v1/orders",
    "per_page": 50,
    "to": 1,
    "total": 1
  }
}

Retrieves a paginated list (default 50) of orders associated with the provided account, sorted in descending order by created_at.

The Order objects included in this response are reference objects, meaning they do not contain all the possible properties of the order, but rather a glimpse.

HTTP Request

GET https://api.immitranslate.com/v1/orders

Query Parameters

Parameter Required Default Description
filter[status] false null If set to a valid Order status, returns only the most recent orders with the provided status.

Retrieve an Order

curl "https://api.immitranslate.com/v1/orders/order_a1s2d3f4q5w6e7r8t9y0" \
  -H "Authorization: a1s2d3f4q5w6e7r8t9y0"

The structure of the List Orders request is below:

{
  "data": [
    {
      "url": "https://api.immitranslate.com/v1/orders/order_a1s2d3f4q5w6e7r8t9y0",
      "token": "order_a1s2d3f4q5w6e7r8t9y0",
      "number": "123456-123456",
      "status": "created",
      "total": 2500,
      "app": null,
      "certification": "certified",
      "translation_type": "certified",
      "delivery": "digital",
      "turnaround": "standard",
      "source_language": "en",
      "target_language": [
        "es"
      ],
      "reference": null,
      "client_reference": null,
      "case_reference": null,
      "created_at": "2022-01-01T00:45:09+00:00",
      "updated_at": "2022-01-01T04:37:17+00:00",
      "intake_processed_at": null,
      "translator_assigned_at": null,
      "translator_accepted_at": null,
      "translator_completed_at": null,
      "proofreader_completed_at": null,
      "all_translations_approved_at": null,
      "notarized_at": null,
      "shipped_at": null,
      "completed_at": null
    }
  ],
  "links": {
    "first": "https://api.immitranslate.com/v1/orders?page=1",
    "last": "https://api.immitranslate.com/v1/orders?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://api.immitranslate.com/v1/orders",
    "per_page": 50,
    "to": 1,
    "total": 1
  }
}

Retrieves a paginated list (default 50) of orders associated with the provided account, sorted in descending order by created_at.

The Order objects included in this response are reference objects, meaning they do not contain all the possible properties of the order, but rather a glimpse.

HTTP Request

GET https://api.immitranslate.com/v1/orders

Query Parameters

Parameter Required Default Description
filter[status] false null If set to a valid Order status, returns only the most recent orders with the provided status.

Approve Order

curl -X POST "https://api.immitranslate.com/v1/orders/order_a1s2d3f4q5w6e7r8t9y0/approve" \
  -H "Authorization: a1s2d3f4q5w6e7r8t9y0"

Sample Response

{
  "data": {
    "url": "https://api.immitranslate.com/v1/orders/order_a1s2d3f4q5w6e7r8t9y0",
    "token": "order_a1s2d3f4q5w6e7r8t9y0",
    "number": "123456-123456",
    "status": "approved",
    "approved_at": "2025-07-21T12:34:56+00:00",
    "total": 2500,
    "app": null,
    "certification": "certified",
    "translation_type": "certified",
    "delivery": "digital",
    "turnaround": "standard",
    "source_language": "en",
    "target_language": [
      "es"
    ],
    "reference": null,
    "client_reference": null,
    "case_reference": null,
    "created_at": "2022-01-01T00:45:09+00:00",
    "updated_at": "2025-07-21T12:34:56+00:00",
    "intake_processed_at": "2022-01-01T00:50:00+00:00",
    "translator_assigned_at": null,
    "translator_accepted_at": null,
    "translator_completed_at": null,
    "proofreader_completed_at": null,
    "all_translations_approved_at": null,
    "notarized_at": null,
    "shipped_at": null,
    "completed_at": null
  }
}

HTTP Request

POST https://api.immitranslate.com/v1/orders/{token}/approve

This approves the translations on an order. By default, every translation on the order is approved. To approve only specific translations, provide the optional files parameter.

Path Parameters

Parameter Required Description
token true The unique identifier for the order to approve.

Body Parameters

Parameter Required Description
files false An array of file identifiers to approve. Each must belong to the specified order. When omitted, all translations on the order are approved.

Request a Revision

curl -X POST "https://api.immitranslate.com/v1/orders/order_a1s2d3f4q5w6e7r8t9y0/revision" \
  -H "Authorization: a1s2d3f4q5w6e7r8t9y0" \
  -d "file_id=file_a1s2d3f4q5w6e7r8t9y0" \
  -d "revision=Please correct the spelling of the applicant's name."

Sample Response

{
  "data": {
    "url": "https://api.immitranslate.com/v1/orders/order_a1s2d3f4q5w6e7r8t9y0",
    "token": "order_a1s2d3f4q5w6e7r8t9y0",
    "number": "123456-123456",
    "status": "in_review",
    "approved_at": null,
    "total": 2500,
    "app": null,
    "certification": "certified",
    "translation_type": "certified",
    "delivery": "digital",
    "turnaround": "standard",
    "source_language": "en",
    "target_language": [
      "es"
    ],
    "reference": null,
    "client_reference": null,
    "case_reference": null,
    "created_at": "2022-01-01T00:45:09+00:00",
    "updated_at": "2025-07-21T12:34:56+00:00",
    "intake_processed_at": "2022-01-01T00:50:00+00:00",
    "translator_assigned_at": null,
    "translator_accepted_at": null,
    "translator_completed_at": null,
    "proofreader_completed_at": null,
    "all_translations_approved_at": null,
    "notarized_at": null,
    "shipped_at": null,
    "completed_at": null
  }
}

HTTP Request

POST https://api.immitranslate.com/v1/orders/{token}/revision

This requests a revision on a single translation belonging to the order. The translation is marked as no longer approved and is returned to our team for the requested changes.

Path Parameters

Parameter Required Description
token true The unique identifier for the order containing the translation.

Body Parameters

Parameter Required Description
file_id true The identifier of the translation to revise. Must belong to the specified order.
revision true A plaintext description of the changes being requested.

Webhooks

POST https://example-webhook-url.test/webhooks/immitranslate

The structure of the POST request:

{
  "type": "quote",
  "event": "status_update",
  "target": "quote_a1s2d3f4q5w6e7r8t9y0",
  "data": {
    "token": "quote_a1s2d3f4q5w6e7r8t9y0",
    "status": "ready"
  },
  "url": "https://immitranslate.com/api/v1/quotes/quote_a1s2d3f4q5w6e7r8t9y0"
}

Webhooks notify your systems about quote and order lifecycle events, most notably status updates for quotes and orders.

Webhook destinations can be configured in two ways:

If both an account-level and a quote-level webhook URL are configured, each event is delivered to both URLs. If both are set to the same URL, only a single request is sent.

Webhook deliveries are sent as HTTP POST requests with a JSON body and include the following headers: Webhook-Id (a unique identifier for the delivery), Webhook-Version, and Webhook-Account (your account token). If your endpoint does not respond with a 2xx status code, delivery is retried up to 3 times with exponential backoff.

Event Object

Field Type Description
type String Either quote or order, though additional types will be added later.
event String The event that occurred: status_update, created, file_created, or file_deleted. See Event Types for the complete list of events.
target String The unique token for the object associated with the event
data Object Select properties from the target object which can be used to identify the change
url String The unique URL of the object which can be fetched with the API

Event Types

The complete list of webhook events is below. For status_update events, the data.status property contains the new status of the object.

Type Event Status Fired When
quote status_update requested A quote has been created and is awaiting review by our team.
quote status_update ready The quote has been reviewed and priced, and is ready for payment.
quote status_update approved The quote has been approved and added to an invoice (accounts with invoicing enabled).
quote status_update paid The quote has been paid and converted into an order.
quote status_update cancelled The quote has been cancelled.
order created created An order has been created, whether from a paid quote, an invoice, or a direct checkout.
order status_update in_progress Work on the order has begun.
order status_update on_hold The order has been placed on hold, most commonly when the page or word count needs to be adjusted before work can continue.
order status_update in_review The completed translations are ready for review and approval.
order file_created — A translation file has become available on the order: every translation when the order enters review, or the replacement file after a revision is fulfilled. The target is the file's token and data.file contains the same file object returned in the order's files property.
order file_deleted — A translation file is no longer available on the order: it was replaced by a revision or the order left the review stage. data.file contains the file's id, name, and collection.
order status_update approved Every translation in the order has been approved.
order status_update completed The order is complete and the final files are available.
order status_update refunded The order has been refunded.
order status_update voided The order has been voided.

For file events, the target is the token of the file itself, data.token repeats the file token, data.order contains the order token, and url points to the order, which can be fetched for the current file list. File events are delivered at least once — deduplicate on the file token if your endpoint may receive the same event twice. The temporary url and download_url links inside data.file expire after 1 hour; fetch the order for fresh links.

Errors

The ImmiTranslate API uses the following standard HTTP error codes.

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key was not provided or is invalid.
403 Forbidden -- You do not have access to the specified resource.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't JSON.
422 Validation Failed -- The parameters you specified were not valid.
429 Too Many Requests -- The API key has submitted too many requests in a short period of time.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
shell