Lab Testing Order Create Guide

Latest Update Time: 2026-06-23 00:00:00

Use the lab testing order create API to submit a new LT booking.

See the Lab Testing Introduction for base URL, authentication, and required headers.

Endpoint

POST https://ppapi.qima.com/v1.2/lt/orders

This API additionally requires the Content-Type: application/json header.

Prerequisites

In addition to the required headers and authentication setup:

Permission to create lab testing orders
Valid LT test IDs and program configuration for your account
Custom fields pre-configured in the target environment by the QIMA development or business team, if you plan to use the customFields section

Request Body Overview

Section	Required	Description
`generalInformation`	Yes	Booking-level information such as reference number, submission type, and test location.
`product`	Yes	Product details. `productName` is required.
`testAssignments`	Recommended	Tests to assign to the order. Each item requires a valid `testId`.
`sampleCollection`	No	Sample collection and courier details.
`additionalRecipients`	No	Email recipients for report, invoice, and quotation notifications.
`specialInstruction`	No	Additional booking remarks.
`customFields`	No	Custom fields for your LT program. Must be configured in advance by the QIMA development or business team in the target environment before use.
`accreditationList`	No	Required accreditations, such as `ANAB` or `HOKLAS`.

Custom Fields Prerequisite

The customFields section is optional, but it cannot be used until QIMA has configured the corresponding custom field definitions for your account in that environment (for example PP or PROD). Contact the QIMA development or business team to set up the required module, label, and allowed values before sending them in API requests.

Request Example

curl --location 'https://ppapi.qima.com/v1.2/lt/orders' \
  --header 'Ai-Api-Access-Token: {your api access token}' \
  --header 'Ai-User-Id: {your user ID}' \
  --header 'Authorization: Bearer {your token}' \
  --header 'Referer: https://preprodmy.qima.com/' \
  --data-raw '{
    "generalInformation": {
        "bookingRefNo": "BOOK-2026-001",
        "supplierId": "",
        "programId": "",
        "submissionType": "Testing",
        "testLocation": "Dongguan",
        "requestTurnAroundTime": "Regular",
        "accreditationRequired": "Yes",
        "description": "New lab testing order created via API"
    },
    "product": {
        "productName": "Children Toy Sample",
        "purchaseOrderNo": "PO-2026-001",
        "sku": "SKU-2026-001",
        "materials": "Cotton, Polyester",
        "ageGrade": "3+",
        "manufacturerFactoryName": "ABC Factory",
        "buyerName": "XYZ Company",
        "agencyName": "Agency ABC",
        "shipmentDate": "2025-12-31",
        "distributionRegions": ["Austria"],
        "distributionCountries": ["China"],
        "originCountries": ["Japan"]
    },
    "testAssignments": [
        {
            "testId": "24671365-76d4-4ed7-b6be-2b92d6bfa59f",
            "quantity": "1"
        }
    ],
    "sampleCollection": [
        {
            "method": "Courier",
            "carrier": "DHL",
            "trackingNo": "TRACK-2026-001",
            "remarks": "Handle with care",
            "sampleReceivedDate": "2025-12-11"
        }
    ],
    "additionalRecipients": {
        "reportEmailTo": "report@example.com",
        "reportEmailCC": "cc@example.com",
        "invoiceEmailTo": "invoice@example.com",
        "invoiceEmailCC": "invoice-cc@example.com",
        "quotationEmailTo": "quotation@example.com",
        "quotationEmailCC": "quotation-cc@example.com"
    },
    "specialInstruction": {
        "bookingRemark": "Please prioritize this order"
    },
    "customFields": [
        {
            "module": "SampleInfo",
            "label": "Test Field 3",
            "value": "Created by API integration"
        }
    ],
    "accreditationList": [
        "ANAB",
        "HOKLAS"
    ]
}'

Request Field Notes

Field	Notes
`generalInformation.bookingRefNo`	Required. Client-side booking reference number.
`generalInformation.submissionType`	Required. Common value: `Testing`.
`generalInformation.testLocation`	Required. Test location accepted by QIMA, such as `Dongguan`, `Shanghai`, or `Hong Kong`.
`generalInformation.programId`	Optional. Leave empty to use the default program when applicable.
`generalInformation.supplierId`	Optional. Use a valid supplier ID when the supplier already exists in QIMA.
`generalInformation.requestTurnAroundTime`	Turnaround time request, such as `Regular`.
`generalInformation.accreditationRequired`	Whether accreditation is required, for example `Yes` or `No`.
`product.productName`	Required. Product name for the LT order.
`testAssignments[].testId`	QIMA test ID to assign to the order.
`testAssignments[].quantity`	Quantity for the assigned test.
`sampleCollection[].method`	Sample collection method, such as `Courier`.
`customFields`	Optional. Only supported after QIMA development or business teams configure the custom field definitions in the target environment.
`customFields[].module`	Must match a module name configured by QIMA for your account.
`customFields[].label`	Must match a field label configured by QIMA for your account.
`customFields[].value`	Value to store for the configured custom field.
`accreditationList`	List of required accreditations for the order.

Successful Response

HTTP 200 OK means the order was created successfully. The response wraps the created order details in content.

{
  "message": "Success",
  "content": {
    "generalInformation": {
      "orderId": "70660b93-a29a-4def-b0da-9bd982adf7f3",
      "qimaRefNo": "T-26012277",
      "bookingRefNo": "BOOK-2026-001",
      "testDate": "",
      "reportDate": "",
      "status": "Validation",
      "client": "ABC QIMA Sandbox",
      "clientId": "0F521098B7154460A50303EEE7A61A16",
      "supplier": "",
      "supplierId": "",
      "submitter": "ABC QIMA Sandbox",
      "submitterId": "0F521098B7154460A50303EEE7A61A16",
      "program": "DEFAULT",
      "programId": "05ef9e73-479a-40c2-a2db-812daaed3e1e"
    },
    "product": {
      "productName": "Children Toy Sample",
      "purchaseOrderNo": "PO-2026-001",
      "sku": "SKU-2026-001",
      "materials": "Cotton, Polyester",
      "ageGrade": "3+",
      "program": "DEFAULT",
      "programId": "05ef9e73-479a-40c2-a2db-812daaed3e1e",
      "distributionRegions": ["Austria"],
      "distributionCountries": ["China"],
      "originCountries": ["Japan"],
      "manufacturerFactoryName": "ABC Factory",
      "agencyName": "Agency ABC",
      "buyerName": "XYZ Company",
      "shipmentDate": "",
      "bookingRemark": ""
    },
    "tests": [
      {
        "testId": "24671365-76d4-4ed7-b6be-2b92d6bfa59f",
        "clientTestId": null,
        "testName": "EN 71-3:2019-Toys-Migration of Certain Elements (Cat III) - All Inclusive",
        "testResult": null
      }
    ],
    "customFields": [
      {
        "module": "SampleInfo",
        "label": "Test Field 3",
        "value": "Created by API integration"
      }
    ],
    "sampleCollection": [
      {
        "method": "Courier",
        "carrier": "DHL",
        "trackingNo": "TRACK-2026-001",
        "remarks": "Handle with care",
        "inspectionOrderReference": null
      }
    ],
    "additionalRecipients": {
      "reportEmailTo": "report@example.com",
      "reportEmailCC": "cc@example.com",
      "invoiceEmailTo": "invoice@example.com",
      "invoiceEmailCC": "invoice-cc@example.com",
      "quotationEmailTo": "quotation@example.com",
      "quotationEmailCC": "quotation-cc@example.com"
    },
    "attachments": null
  }
}

Response Field Notes

Field	Notes
`content.generalInformation.orderId`	QIMA internal LT order ID. Store this value for later order detail, result, or attachment requests.
`content.generalInformation.qimaRefNo`	QIMA lab order reference number, for example `T-26012277`.
`content.generalInformation.status`	Initial order status after creation, commonly `Validation`.
`content.generalInformation.bookingRefNo`	Echo of the client booking reference sent in the request.
`content.tests`	Assigned tests with QIMA test names and IDs.
`content.attachments`	Attachments linked to the order. Usually `null` immediately after creation unless files were included elsewhere.

Store the returned orderId and qimaRefNo if you need to search, update, or upload attachments to the order later.

Common Errors

See common authentication errors for 401 and 403 responses.

Status	Meaning	Recommended Action
`400 Bad Request`	Request body failed validation.	Check required fields such as `bookingRefNo`, `submissionType`, `testLocation`, and `productName`. Verify test IDs, program configuration, and that any `customFields` were pre-configured by QIMA in the target environment.
`500 Internal Server Error`	Order creation failed on the server.	Contact QIMA support with the request time and booking reference.

Next Steps

Search lab testing orders to confirm the new order appears in the order list.
Retrieve full lab testing order details using the returned orderId.
Update the order if changes are needed — see the Order Update Guide.
Upload attachments to the order when supporting documents are available — see the Order Attachments Guide.

Documents