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.
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, head over to the contact page and our team will get back to you.
Changelog
2024-06-20
- The
Files
endpoint now contains an optional metadata attribute for existing machine translations and for OCR data. We recommend providing this data when it is already being utilized in an existing system.
2022-02-19
- Initial release of our REST API.
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.
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
An example metadata value is provided:
{
"document_type": "birth_certificate",
"subjects": [
{
"name": "Test Persson",
"name_native": "Test Pärsson",
"dob": "1985-03-01"
}
],
"locations": [
{
"city": "Stockholm",
"notes": "Location of birth"
}
],
"country_of_origin": "SE",
"issuing_authority": "Skatteverket",
"issued_day": 8,
"issued_month": 4,
"issued_year": 1985,
"is_government_issued": true,
"is_academic_issued": false,
"ocr" : [
{
"contents": "...",
"format": "text",
"engine": "tesseract",
"model": "tesseract5"
}
],
"machine_translations": [
{
"source_language": "es",
"target_language": "en",
"translation": "...",
"source": "...",
"engine": "openai",
"model": "gpt-4o"
}
]
}
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,
"source_metadata": {
"subjects": [
{
"dob": "1985-03-01",
"name": "Test Persson",
"name_native": "Test Pärsson"
}
],
"locations": [
{
"city": "Stockholm",
"notes": "Location of birth"
}
],
"issued_day": 8,
"issued_year": 1985,
"issued_month": 4,
"document_type": "birth_certificate",
"country_of_origin": "SE",
"issuing_authority": "Skatteverket",
"is_academic_issued": false,
"other_document_type": null,
"is_government_issued": true
},
"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 the Content-Type: multipart/form-data
header set
and a file contained in the variable file
. We highly recommend providing as much metadata about the file as possible,
enabling our translation team to rapidly prepare documents. We also strongly recommend documents to be separated logically by file.
For example, a birth certificate should not be provided in the same file as a marriage license.
Request Parameters
Field | Type | Required | Description |
---|---|---|---|
file |
File | Yes | multipart/form-data File |
metadata |
JSON String | No | A JSON string containing relevent metadata for this document. |
Permitted File Types
- DOC
- DOCX
- JPG
- JPEG
- XLS
- XLSX
- GIF
- PNG
- BMP
- TIFF
- TIF
- HEIC
- TXT
Metadata Object
Field | Type | Required | Description |
---|---|---|---|
document_type |
String | No | See available Document Types |
subjects |
Array | No | See Subject Object below An array of valid document subjects. For example, if this is a birth certificate, the subject of the document would be the person whom is listed on the certificate. For a marriage certificate, there are multiple subjects. As many or as few subjects can be provided. |
locations |
Array | No | See Location Object below An array of valid locations referenced in the document. For example, if this is a birth certificate, the location of birth may have specific spelling requirements. |
country_of_origin |
String | No | ISO-3166 Country Code for where the document was issued. |
issuing_authority |
String | No | The government agency, institution, or organization that issued the document. |
issued_day |
Integer | No | The day of the month in which the document was issued. |
issued_month |
Integer | No | The month in which the document was issued. |
issued_year |
Integer | No | The year in which the document was issued. |
is_government_issued |
Boolean | No | Whether this document was issued by a government. |
is_academic_issued |
Boolean | No | Whether this document was issued by an academic institution. |
ocr |
Array | No | An array of OCR Objects. An object that contains text that has been previously run through any series of OCR systems. |
machine_translations |
Array | No | An array of Machine Translation Objects. An object that contains an existing machine or AI translation. |
OCR Object
If you are running OCR on documents in any other capacity, this data can be provided to improve accuracy and decrease turnaround times.
Field | Type | Required | Description |
---|---|---|---|
contents |
String | Yes | The full text produced by the OCR system. |
format |
String | No | The format of the text contents. By default, plaintext is assumed. Acceptable values: text , markdown , hocr , html |
engine |
String | No | Optional OCR engine used. This is used for tracking and analytics and does not change the ingestion of data. Typical values may include: openai , tesseract , abbyy |
model |
String | No | Optional model used. This is used for tracking and analytics and does not change the ingestion of data. |
Machine Translation Object
If you are using a system that offers AI or machine translations of documents, this is a way to improve the accuracy and decrease the turnaround time of our certified translations.
Field | Type | Required | Description |
---|---|---|---|
source_language |
String | Yes | ISO-639 language code denoting the source language used in translation. |
target_language |
String | Yes | ISO-639 language code denoting the target language used in translation. |
translation |
String | Yes | The complete translation text, acceptable in either markdown or plaintext. |
source |
String | Yes | The complete source text, acceptable in either markdown or plaintext. |
engine |
String | No | Optional AI engine used. This is used for tracking and analytics and does not change the ingestion of data. Typical values may include: openai , claude , llama , deepl |
model |
String | No | Optional AI model used. This is used for tracking and analytics and does not change the ingestion of data. Typical values may include: gpt-4o , gpt-3.5-turbo , deepl |
Subject Object
Field | Type | Required | Description |
---|---|---|---|
name |
String | No | The full name of the subject of the document. |
name_native |
String | No | Optional full name of the subject in the alphabet of their native language. The name field is what would be used for transliteration. |
dob |
String | No | Date of birth of the subject in YYYY-MM-DD format. |
Location Object
Field | Type | Required | Description |
---|---|---|---|
address |
String | No | The preferred spelling of the address of the reference location, if any. |
city |
String | No | The preferred spelling of the city of the referenced location, if any. |
region |
String | No | The preferred spelling of the region of the referenced location, if any. |
notes |
String | No | Reference notes provided to the translation team to assist with the proper spelling of this location. |
Document Types
Key | Document Type | Description |
---|---|---|
adoption_document |
Adoption Document | Any document related to adoption proceedings, but not a document included elsewhere in the list. |
affidavit |
Affidavit | A signed declaration document. |
apostille |
Apostille | An apostille certificate issued by a member nation of the Hague Treaty. |
asylum_document |
Asylum Document | Any document related to an asylum matter, but not a document included elsewhere in the list. |
background_check |
Background Check | Any background check document, such as an FBI Background Check document. |
bank_statement |
Bank Statement | A financial statement issued by a bank. Note that this should be differentiated with a credit_card_statement if at all possible. If the type is not known, but it is confirmed as a financial document, use the financial_document value. |
credit_card_statement |
Credit Card Statement | A financial statement issued by a credit card company. Note that this should be differentiated with a bank_statement if at all possible. If the type is not known, but it is confirmed as a financial document, use the financial_document value. |
financial_statement |
Financial Statement | Any financial document issued by a financial institution. |
birth_certificate |
Birth Certificate | A document used to establish birth credentials, such as name and date of birth. |
change_of_name |
Change of Name | A document used to establish a change-of-name. |
criminal_record |
Criminal Record | A document establishing a criminal record. This can often overlap with background_check . We recommend using background_check when the document establishes no criminal record, and criminal_record when the document lists criminal records. |
academic_transcript |
Academic Transcript | Any academic transcript, commonly showing courses, grades, and other remarks. |
court_transcript |
Court Transcript | Any court transcript, typically in a format showing speaker and text. |
audio_transcript |
Audio Transcript | Any audio transcription, typically displaying speaker, timestamp, and text. |
death_certificate |
Death Certificate | Any document related to a death. |
diploma |
Diploma | Any academic diploma, displaying a name and academic institution. |
divorce_document |
Divorce Document | Any divorce document not otherwise specified. Use this value to show proceeding-related documents. Use divorce_decree to specify a decree or final judgement. |
divorce_decree |
Divorce Decree | Any divorce document that shows final judgement. |
drivers_license |
Driver's License | Any government issued driver's license. This is differentiated from an id_card when the document lists specific driving abilities and classifications. |
id_card |
ID Card | Any government issued identification card. Use drivers_license when the ID includes associated capabilities and classifications. |
email |
Email Message | Any email message |
legal_contract |
Legal Contract | Any legal contract or binding legal instrument. |
marriage_certificate |
Marriage Certificate | Any certificate showing a record of marriage. |
marriage_license |
Marriage License | Any marriage license. Typically issued prior to a marriage and not necessarily establishing a record of marriage. |
medical_record |
Medical Record | Any medical record. Use this field for COVID-19 Test Results. For vaccination records, use vaccination_record . |
mortgage_document |
Mortgage Document | Any document related to a mortgage. For things such as rentals or leases, use legal_contract . |
passport |
Passport | Any passport and subsequent pages. For US Visas (with our without MRZ), use visa |
cv |
CV | Any Curriculum vitae (or resume) |
tax_record |
Tax Record | Any tax record, such as a tax return or tax receipt. |
text_message |
Text Message | Any text message, such as SMS, WhatsApp, or Messenger. |
vaccination_record |
Vaccination Record | Any vaccination record or vaccination card. Includes COVID-19 vaccination records. |
visa |
Visa | Any visa document or other travel document |
other |
Other | Use this if you would like to provide a custom value. Custom values are provided in the other_document_type field. |
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 |
Create Quote
POST https://api.immitranslate.com/v1/quotes
The structure of the Create Quote response is below:
{
"reference": "TL-1138",
"case_reference": "AA00039212",
"client_reference": "CL-0001",
"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"
}
}
},
"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 |
---|---|---|---|
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. |
services |
Object | Yes | Services Object - Specifies the relevant services and certain related configuration items. |
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. |
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/123456-123456",
"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/123456-123456" \
-H "Authorization: a1s2d3f4q5w6e7r8t9y0"
The structure of the List Orders request is below:
{
"data": [
{
"url": "https://api.immitranslate.com/v1/orders/123456-123456",
"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. |
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. |