Lab Testing Order Attachments Guide

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

Use the lab testing order attachments API to upload one or more supporting documents to an existing LT order.

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

Endpoint

POST https://ppapi.qima.com/v1.2/lt/orders/{orderId}/attachments

This API requires:

Content-Type: multipart/form-data (set automatically when using --form in curl)
Idempotency-Key request header to prevent duplicate uploads

Prerequisites

In addition to the required headers and authentication setup:

Permission to upload attachments to lab testing orders
The LT orderId from an order search, order create, or order detail response
One or more files ready to upload

Path Parameters

Parameter	Required	Description
`orderId`	Yes	QIMA internal LT order ID, for example `ba70d368-801d-447e-ba55-0d1269d81188`.

Request Headers

In addition to the common LT headers:

Header	Required	Description
`Idempotency-Key`	Yes	A unique identifier for this specific upload request. See Idempotency-Key below.

Idempotency-Key

The Idempotency-Key header prevents the same upload from being processed more than once — for example when a network timeout causes your client to retry a request that already reached the server.

Each upload request must use its own independent ID. Do not reuse the same key across different uploads (different files, different orders, or a new upload you intend to send separately). Generate a fresh value every time you send a new upload request — a UUID is a common and recommended choice.

Scenario	Idempotency-Key
First upload of document A	New UUID, e.g. `a1b2c3d4-e5f6-7890-abcd-ef1234567890`
Later upload of document B (separate request)	New UUID — do not reuse the key from document A
Retry after timeout (same files, same intent)	Same UUID as the original attempt — so the server can recognize the duplicate and avoid uploading twice

Example — generate a UUID when sending the request:

# Bash / macOS / Linux: create a new UUID for each upload request
IDEMPOTENCY_KEY=$(uuidgen)

curl --location 'https://ppapi.qima.com/v1.2/lt/orders/<order-id>/attachments' \
  --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/' \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --form 'files=@"/path/to/document.pdf"'

In application code, generate a new UUID before each upload call. For example:

JavaScript: crypto.randomUUID()
Python: str(uuid.uuid4())
Java: UUID.randomUUID().toString()

Only reuse an existing Idempotency-Key when you are retrying the exact same upload request after a transient failure. For every new upload you initiate, create a new UUID.

Query Parameters

Parameter	Required	Description
`fileLabel`	No	Attachment label applied to uploaded file(s). Defaults to `Client Document for Review` when omitted.
`fileDescription`	No	Optional description for the uploaded attachment(s).
`sourceId`	No	Source ID passed to AIMS. Defaults to the order ID when omitted.

Form Data

Field	Required	Description
`files`	Yes	One or more files to upload. Repeat the `files` field for each file in the same request.

Request Example

Upload two files in a single request:

curl --location 'https://ppapi.qima.com/v1.2/lt/orders/<order-id>/attachments' \
  --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/' \
  --header 'Idempotency-Key: <unique-idempotency-key>' \
  --form 'files=@"/path/to/document-1.docx"' \
  --form 'files=@"/path/to/document-2.odt"'

Optional query parameters example:

curl --location 'https://ppapi.qima.com/v1.2/lt/orders/<order-id>/attachments?fileLabel=Client%20Document%20for%20Review&fileDescription=Supporting%20spec%20sheet' \
  --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/' \
  --header 'Idempotency-Key: <unique-idempotency-key>' \
  --form 'files=@"/path/to/document.pdf"'

Request Field Notes

Field	Notes
`files`	Required. Send at least one file. Use multiple `--form 'files=@...'` entries to upload several files in one request.
`Idempotency-Key`	Required. Generate a new UUID for each upload request. Reuse the same key only when retrying the exact same request after a failure. Reusing a key across unrelated uploads, or reusing a fixed value such as `userId`, can cause `409 Conflict` or unexpected behavior.
`fileLabel`	Optional query parameter. When omitted, uploaded files receive the default label `Client Document for Review`.
`fileDescription`	Optional query parameter. Applies to the uploaded attachment(s) in the request.
`sourceId`	Optional query parameter. Usually omitted so the attachment is linked to the order automatically.

Successful Response

HTTP 200 OK means the files were uploaded successfully. The response wraps an array of upload results in content, with one entry per uploaded file.

{
  "message": "Success",
  "content": [
    {
      "id": "a77b8c59-5ae5-4d81-b55e-ee53ed2330b5",
      "label": "Client Document for Review",
      "fileName": "Products to inspect 1503-100J - L14-102.docx",
      "fileSize": 3623478,
      "description": "",
      "fileHashcode": "E1125F8540544B05B43932B33E6FF22E",
      "sourceId": null,
      "status": "Active",
      "message": null,
      "createTime": "2026-06-23T06:40:53.375+00:00",
      "updateTime": "2026-06-23T06:40:53.375+00:00",
      "createdBy": null,
      "updatedBy": null
    },
    {
      "id": "84d552e0-150d-457f-aa2d-5684be15b413",
      "label": "Client Document for Review",
      "fileName": "QF-51-21A+Gulf+G-Mark+Certificate+Template+29+V1.9.odt",
      "fileSize": 3091916,
      "description": "",
      "fileHashcode": "D4D2DA37DDC24DC081EBAF2E84A8EA27",
      "sourceId": null,
      "status": "Active",
      "message": null,
      "createTime": "2026-06-23T06:40:53.375+00:00",
      "updateTime": "2026-06-23T06:40:53.375+00:00",
      "createdBy": null,
      "updatedBy": null
    }
  ]
}

Response Field Notes

Field	Notes
`content`	Array of upload results, one object per uploaded file.
`content[].id`	Attachment ID assigned by QIMA.
`content[].label`	Attachment label, for example `Client Document for Review`.
`content[].fileName`	Original file name from the upload request.
`content[].fileSize`	File size in bytes.
`content[].fileHashcode`	QIMA file service identifier for the uploaded file.
`content[].status`	Upload status for the attachment, for example `Active`.
`content[].message`	Status message or error detail when an individual file upload fails. Usually `null` on success.
`content[].createTime`	Timestamp when the attachment was created.
`content[].updateTime`	Timestamp when the attachment was last updated.

Store the returned attachment id values if you need to reference uploaded files later. To confirm attachments appear on the order, call Get Order Details.

Common Errors

See common authentication errors for 401 and 403 responses.

Status	Meaning	Recommended Action
`400 Bad Request`	Required input is missing or invalid.	Confirm `orderId`, at least one `files` form field, and the `Idempotency-Key` header are present.
`403 Forbidden`	The order does not exist or the user has no access.	Confirm the `orderId` is correct and belongs to the authenticated account.
`409 Conflict`	A request with the same `Idempotency-Key` is already being processed.	If retrying the same upload after a timeout, wait and retry with the same key. If this is a new upload, generate a new UUID and send again.
`500 Internal Server Error`	Attachment upload failed on the server.	Contact QIMA support with the request time, `orderId`, and file names.

Next Steps

Retrieve full lab testing order details to confirm attachments appear on the order — see the Order Detail Guide.
Update the order if additional booking details need to change — see the Order Update Guide.
Retrieve lab testing order test results when the report is available — see the Order Results Guide.

Documents