Lab Testing Introduction

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

Lab Testing (LT) APIs allow you to programmatically search orders, create bookings, retrieve order details, fetch test results with report download links, and upload attachments. All LT endpoints require authentication and share a common set of request headers.

This page documents the shared setup used by every Lab Testing guide. Each API-specific guide links back here for authentication, headers, and environment details.

Base URL

All Lab Testing APIs are served from the QIMA Public API host for your environment:

https://ppapi.qima.com

LT endpoints use the /v1.2/lt/ path prefix. For production integrations, replace the host with the QIMA API host provided for your environment.

Required Headers

Call the Auth API first (POST /auth/v2/token) before any Lab Testing request. See the Getting Started Guide or Get Token API for authentication setup.

You also need a QIMA customer account with permission for the target LT operation, and an Ai-Api-Access-Token for the target environment provided by QIMA. Each API guide lists additional operation-specific requirements.

Header / Parameter	Location	Source	Description
Ai-Api-Access-Token	Request header (all LT APIs)	Provided by QIMA	Request source identifier. Each client may have a different value per environment.
Ai-User-Id	Request header (all LT APIs)	Auth API response userId	Identifies the authenticated QIMA user.
Authorization	Request header (all LT APIs)	Auth API access token	Format: Bearer <access-token>. Use the token from the same Auth API session as the other headers.
Referer	Request header (all LT APIs)	Fixed value	https://preprodmy.qima.com/
clientId	Query parameter (order search only)	Auth API response companyId	Required when calling Search Orders. Most other LT APIs do not use clientId; the authenticated user context is passed through the headers above.

Common Authentication Errors

These errors apply to all Lab Testing APIs:

Status	Meaning	Recommended Action
401 Unauthorized	Token or user authentication failed.	Confirm the Authorization, Ai-User-Id (userId), and Ai-Api-Access-Token headers are from the same Auth API session and environment.
403 Forbidden	The user does not have access to the requested resource.	Verify account permissions and, for order search, that clientId matches the Auth API response companyId.

Each API guide includes additional operation-specific error codes.

Available APIs

API	Method	Endpoint	Guide	API Reference
Search orders	GET	/v1.2/lt/orders	Order Search Guide	API Reference
Create order	POST	/v1.2/lt/orders	Order Create Guide	API Reference
Get order details	GET	/v1.2/lt/orders/{orderId}	Order Detail Guide	API Reference
Get order results	GET	/v1.2/lt/order-results/{orderId}	Order Results Guide	API Reference
Upload attachments	POST	/v1.2/lt/orders/{orderId}/attachments	Order Attachments Guide	API Reference
Update order	PUT	/v1.2/lt/orders/{orderId}	Order Update Guide	API Reference

Integration Workflows

The diagrams below show recommended API sequences for common integration scenarios. Follow the linked guides for request examples, field notes, and error handling.

1. Authenticate (Required for All Flows)

All Lab Testing workflows begin with authentication. Store userId, companyId, and the access token from the response before calling any LT endpoint.

• Guide: Getting Started Guide
• API Reference: Get Token

2. View Test Results and Download Reports

Use this flow when you need to find an order and retrieve its test results, final report files, and attachment download links.

Typical steps:

1. Authenticate via the Auth API.
2. Call Search Orders with clientId (from companyId) to locate the target order and obtain orderId.
3. Call Get Order Results with that orderId.
4. Download files from finalReport.reportFile and attachments[].url before the signed URLs expire.

Step	Guide
Search orders	Order Search Guide
Get results & reports	Order Results Guide

3. Create a Lab Testing Order

Use this flow when you want to submit a new LT booking through the API.

Typical steps:

1. Authenticate via the Auth API.
2. Call Create Order with booking details in the request body.
3. Store the returned orderId and qimaRefNo from the response.
4. Optionally call Search Orders or Get Order Details to verify the order was created.

Step	Guide
Create order	Order Create Guide
Verify via search	Order Search Guide
Verify via detail	Order Detail Guide

Custom fields: If your booking payload includes customFields, the QIMA development or business team must configure those fields in the target environment before they can be used. See the Order Create Guide.

4. Upload Attachments to an Order

Use this flow when you need to attach supporting documents to an existing LT order.

Typical steps:

1. Authenticate via the Auth API.
2. Obtain the target orderId by calling Search Orders or Get Order Details.
3. Call Upload Attachments with the orderId and files as multipart/form-data.
4. Generate a new UUID for the Idempotency-Key header on each upload request to avoid duplicate uploads.

Step	Guide
Find order	Order Search Guide or Order Detail Guide
Upload attachments	Order Attachments Guide

5. Retrieve Full Order Details

Use this flow when you need complete order information — product details, tests, sample collection, recipients, and existing attachments — without test result report files.

Step	Guide
Search orders	Order Search Guide
Get order details	Order Detail Guide

6. Update an Existing Order

Use this flow when you need to modify booking details, product information, recipients, or custom fields on an existing order.

Typical steps:

1. Authenticate via the Auth API.
2. Obtain the target orderId by calling Search Orders or Get Order Details.
3. Call Update Order with the fields to change in the request body.
4. Optionally call Get Order Details again to verify the update.

Step	Guide
Find order	Order Search Guide or Order Detail Guide
Update order	Order Update Guide

Choosing the Right API

Your goal	Recommended APIs
List or filter LT orders	Search Orders
Submit a new LT booking	Create Order
Update an existing LT order	Update Order
View full order information	Get Order Details
Get pass/fail results and report download links	Get Order Results
Upload documents to an existing order	Upload Attachments

Related Documentation

• Getting Started Guide — Authentication and first API call
• Module Overview — Overview of all QIMA Public API modules
• API Reference — Interactive endpoint explorer for all Public APIs