Quotes - ImmiTranslate API

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`	String	Source Language (ISO-639 Language Code)
`target`	Array	Target Languages (ISO-639 Language Codes)
`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.
`payment_url`	String	The quote’s page on ImmiTranslate, where the customer can review and pay for it. `null` until the quote is ready. Use it when your OAuth app is not verified and cannot pay through the API.

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: Bearer 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"
    }
  }
}

If the payment fails, the response is HTTP 402:

{
  "error": true,
  "code": "payment_failed",
  "message": "Your card was declined.",
  "result": "error",
  "data": {
    "message": "Your card was declined."
  }
}

After receiving the Quote Ready event, a quote is ready for payment. This method triggers the creation of a new Order. Accounts with invoicing enabled are billed on their invoice; otherwise the account’s default payment method is charged unless payment_method names another. If the charge is declined or the payment can’t be taken, the response is 402 with "code": "payment_failed" and the reason in message. A quote that is not ready returns 422 with invalid_state. An OAuth app that is not verified receives 403 with payment_requires_verified_app and a payment_url where the customer can pay instead.

Pay Quote Request

Field	Type	Required	Description
`payment_method`	String	No	The token of one of the account’s saved payment methods (`sources` in Get Account). Defaults to the account’s invoice, if it has invoicing, or its default payment method.

Cancel Quote

DELETE https://api.immitranslate.com/v1/quotes/{token} \
  -H "Authorization: Bearer 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

If you’re shipping at volume and have negotiated rates with a different carrier, contact your ImmiTranslate account representative for information on how to utilize your carrier account directly.

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": "customer@example.com",
      "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. The quote is placed on the account your API key belongs to and attributed to the partner, whichever account the partner belongs to. An invalid partner token 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.

​Quote Object

​Create Quote

​Request Parameters

​Pay Quote

​Pay Quote Request

​Cancel Quote

​Query Parameters

​Services Object

​Translation Options

​Credential Evaluation Options

​Expert Opinion Letter Options

​Currency Conversion Options

​Apostille Options

​Notarization Options

​Shipping Options

​Shipping Service Options

​Shipping Address Options

​Use Cases Object

​Partner Object

Quote Object

Create Quote

Request Parameters

Pay Quote

Pay Quote Request

Cancel Quote

Query Parameters

Services Object

Translation Options

Credential Evaluation Options

Expert Opinion Letter Options

Currency Conversion Options

Apostille Options

Notarization Options

Shipping Options

Shipping Service Options

Shipping Address Options

Use Cases Object

Partner Object