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).
URL
(POST) /api/orders/createPARAMETERS
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 https://wordbee.atlassian.net/wiki/spaces/API2/pages/491567 and https://wordbee.atlassian.net/wiki/spaces/API2/pages/491572
| 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:
| 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:
See https://wordbee.atlassian.net/wiki/spaces/API2/pages/491646 to enumerate custom fields by API and get the IDs (keys). The “key” can also be found in the Wordbee Translator user interface, see . 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 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:
| 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 . 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 . | 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.
Copyright Wordbee - Buzzin' Outside the Box since 2008