orders/create (POST)

This method permits to submit new orders to the client portal.

This method does not provide all the features that you get when submitting orders online (alternative full-feature methods will be added over time).

1 URL
2 PARAMETERS
- 2.1 Order parameters (“data”)
- 2.2 ZIP archive (“zipFile”)
3 RESULTS
4 NOTES

URL

(POST) /api/orders/create

PARAMETERS

The BODY must be of type form-data and contain two elements:

data: A JSON object where you include all the various parameters, explained below.
zipFile: The ZIP archive that contains the files to translate or attach as reference material. See further down for explanation.

In Postman, this is done as follows:

Order parameters (“data”)

This is a JSON object with these properties:

client	A JSON object containing the company submitting the order and, optionally, the person within the company. Example: `"client" : { "companyId": 100, "personId": null }` To find companies or persons use companies/list and persons/list companyId is mandatory personId is optional and can be set to null or be omitted	object {int, int?} , Mandatory
option	The zero-based “option” to select in the order form. An order form may have one (default) or more options a client can choose from. These are configured in Settings > New Order form. If an order form has more than one option, the following option-selector appears: Note: The client ID you have chose directly defines the order form configuration that is selected and which influences how the order will be created.	int, Mandatory
deadline	The deadline. Always set to a future date and note that this date may get adjusted according to various options in the order form configuration. This date must include time zone information such as in: `2018-08-02T00:00:01.0000000Z`	datetime, Optional
reference	The order reference provided by the client.	string, Mandatory
sourceLanguage	The source language code such as “en” or “fr-BE”.	string, Mandatory
targetLanguages	An non-empty array of target language codes. Example: `"targetLanguages": [ "fr", "de-DE" ]`	string[], Mandatory
domains	Optional. An array of translation domains to assign to the project.	string[]?, Optional
instructions	Optional instructions included by client.	string?, Optional
	Appointment specific fields
isAppointment	Optional, false by default. Indicates if this order is an “appointment” request such as a request for interpretation. This requires a specific setup in the order form settings. The date when the appointment starts.	bool?, Optional
appointmentStartDate	Optional. This field is used with appointments only. The date when the appointment starts.	datetime?, Optional
appointmentEndDate	Optional. This field is used with appointments only. The date when the appointment ends.	datetime?, Optional
	Custom fields
customFields	Optional array of custom fields to populate. Any custom field defined for Orders can be used. Each array element is an object with properties: key: The unique identifier of the order custom field, such as “CustomStr4” text: The value to assign. Use null to clear an existing value. See settings/customfields to enumerate custom fields by API and get the IDs (keys). The “key” can also be found in the Wordbee Translator user interface, see Creating and updating Custom Fields. Go to “Settings” then “Custom fields”, select the “Orders” tab and pick any of the fields. At the bottom of the popup you will find the custom field’s ID. Example:	object[{string, string?}], Optional
	Management
manager	Optional. The user ID of the project manager to assign to this order. If not specified no manager is assigned. The ID must refer to an internal user with manager level access rights. See persons/list to enumerate or find persons.	int?, Optional
parserProfileId	Optional. Generally, this should not be used. The parser profile ID to be used to extract content from the uploaded files. The order form configuration typically lets you define this profile. But, you can override this as well. To find or enumerate available profiles, see: Document format profiles	int?, Optional

Example:

ZIP archive (“zipFile”)

Include the ZIP file in the BODY form-data with key zipFile

To add reference material, create a folder named ___ref___ to your zip file and place your reference files. Optionally, add "___ref___/" before the file name.

Example: The ZIP archive might contain these files:

The folder hierarchy for files such as for “marketing” above is maintained in both the created order as well as the created project (if it is created by configuration).

RESULTS

The method executes asynchronously. It returns the operation ID which is a number.

Example:

You would then wait a few seconds and request a detailed operation status using trm/status. This will return the status. You need to poll the method and wait 2 to 5 seconds in between polls until the status is Finished or Failed. Please read this page for a detailed explanation: Asynchronous operation

If the operation finished with success, the status is Finished and you can access some details on the newly created order in the result property:

The v node above has a lot of properties. Most of them are self-explanatory and we will only highlight the most important ones:

orderDetails.orderSummary.orderId	The unique order ID which was assigned to the order. You can find back this order or all orders using orders/list .	int

onlineUrl	The URL to access the new order in a web browser	string
orderDetails.counts	An array of word count details, per each uploaded document. Example:	object[]
orderDetails.costDetails	Details about the total client cost (if costing is enabled in the order form settings). Example: If property orderDetails.incompleteCost is false then this means that the cost details above are incomplete. This can happen if a file failed to be processed, a unit price could not be found in the price list or if any other information is missing.	object
orderDetails.errors	An order submission is a complex operation and often involves creation of an order, a project, workflows, jobs, assignments to people etc. All this is controlled in the order form configuration. If it happens that some steps did not complete successful but overall the order was created, then you will find in this array a list of errors. Errors will also be visible to the project manager online in the order details. The array is empty or contains errors , see example:	object[]

There are many more properties that you might find useful. An example of an operation result is shown below:

NOTES

The former documentation contained various errors:

The files property is not required and should not be included. It formerly stated that all files in the ZIP must be listed here.
The isDeadlineByFiles is not supported and should NOT be set or included. It formerly stated that you can include a deadline individually per file. Please simply set the general deadline property for the order.