Audit Order Create Guide

Latest Update Time: 2026-07-01 00:00:00

Use the audit order create API to submit a new audit booking.

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

Endpoint

POST https://ppapi.qima.com/v1.0/audit

Prerequisites

In addition to the required headers and authentication setup:

Permission to create audit orders for the target client
A valid supplierCode, or the supplier's name, contact details, location, address, and product lines
If factory auto-confirmation is needed: a valid factoryCode, or the factory's name, contact details, location, address, and product lines
Product category, family, and geographic parameter values accepted by QIMA (see the Parameter module)

Request Body Fields

The request body uses the AuditOrder schema. Required fields are marked below; see the interactive API reference for the complete field list and types.

Field	Required	Notes
`userId`	Yes	QIMA client user login ID. Must match the value sent in the `Ai-User-Id` header.
`serviceDate`	Yes	Planned audit date. Use `dd-MMM-yyyy`, for example `19-Dec-2022`.
`shipDate`	Yes	Planned shipment date. Use `dd-MMM-yyyy`.
`serviceType`	No	QIMA audit service type. Mandatory if `previousOrderNumber` is not provided. One of `ma` (Manufacturing Audit), `ea` (Ethical Audit), `enva` (Environmental Audit), `dr` (Desktop Review), `ghp` (Food Hygiene Audits), `gmp` (Food Good Manufacturing Practices Audits), `gfsi` (Food Certified), `ctpat` (C-TPAT Audit), `stra` (Structural Audit).
`announcementType`	No	One of `Announced`, `Semi-Announced`, `Un-Announced`.
`workersCount`	Yes	Number of workers at the factory.
`factoryAreaSqm`	Yes	Factory area in square meters.
`totalNumberOfBuilding`	Yes	Total number of buildings at the factory.
`auditWindowFrom` / `auditWindowTo`	No	Audit window date range. Use `dd-MMM-yyyy`.
`supplierCode`	No	Supplier's identification code in your system. Mandatory when supplier name, city, and contact are not provided, and must be a valid code already known to QIMA.
`supplierName`, `supplierContactName`, `supplierContactPhone`, `supplierContactEmail`	Yes	Supplier identification and contact details.
`supplierContinentID`	Yes	Supplier's continent ID in QIMA's system. See Get All Continents.
`supplierCountryID`, `supplierCityID`	No*	Supplier's country/city ID in QIMA's system. Mandatory when `supplierCode` is not provided. See the Parameter module APIs.
`supplierAddress`	Yes	Supplier's street address.
`supplierProductLines`	Yes	Supplier product lines. Get valid values from Get All Product Families.
`factoryCode`	No	Factory's identification code in your system. Mandatory when auto factory confirmation is needed and other factory fields are not provided.
`factoryName`, `factoryContactName`, `factoryContactPhone`, `factoryContactEmail`, `factoryContinentID`, `factoryCountryID`, `factoryProvinceID`, `factoryCityID`, `factoryAddress`, `factoryProductLines`	No*	Factory identification, contact, location, and product lines. Mandatory when auto factory confirmation is needed and `factoryCode` is not provided.
`referenceNumber`	No	Your own reference number for this order.
`additionalComment`	No	Free-text comment for the audit order.
`specificField`	No	Audit order specific field.

Request Example

Replace all placeholder values before sending the request. Do not reuse access tokens across environments.

curl --location --request POST 'https://ppapi.qima.com/v1.0/audit' \
  --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 '{
    "userId": "<qima-user-id>",
    "serviceDate": "10-Oct-2026",
    "shipDate": "10-Oct-2026",
    "serviceType": "ea",
    "referenceNumber": "2107-0-02026",
    "factoryAreaSqm": 1,
    "totalNumberOfBuilding": "3",
    "announcementType": "Semi-Announced",
    "workersCount": 1,
    "auditWindowFrom": "10-Oct-2026",
    "auditWindowTo": "12-Oct-2026",
    "additionalComment": "test",
    "supplierCode": "SF-TL90",
    "supplierName": "Sample Supplier Co.",
    "supplierContactName": "Supplier Manager",
    "supplierContactPhone": "13800000001",
    "supplierContactEmail": "supplier.contact@example.com",
    "supplierContinentID": "24865671",
    "supplierCountryID": "23424781",
    "supplierCityID": "12687656",
    "supplierAddress": "LuoHuQu ChunFenglu 999",
    "supplierProductLines": ["bigCat1_s2", "bigCat1_s3"],
    "factoryCode": "SF-99-i56",
    "factoryName": "Sample Factory Co.",
    "factoryContactName": "Factory Manager",
    "factoryContactPhone": "13800000004",
    "factoryContactEmail": "factory.contact@example.com",
    "factoryContinentID": "24865671",
    "factoryCountryID": "23424781",
    "factoryProvinceID": "12578019",
    "factoryCityID": "12687656",
    "factoryAddress": "LuoHuQu ChunFenglu 777",
    "factoryPostalCode": "511464",
    "factoryProductLines": ["bigCat1_s2", "bigCat1_s3"],
    "supplierAlternateContactName": "Alternate Supplier Contact",
    "supplierAlternateContactPhone": "13800000002",
    "supplierAlternateContactEmail": "supplier.alt@example.com",
    "factoryAlternateContactName": "Alternate Factory Contact",
    "factoryAlternateContactPhone": "13800000003",
    "factoryAlternateContactEmail": "factory.alt@example.com"
  }'

Successful Response

HTTP 200 OK means the audit order was created. HTTP 202 Accepted means the request was accepted but the factory confirmation step did not fully succeed.

202 — Factory Confirmation Not Completed

{
    "message": "Supplier confirm audit order failed!Confirm audit failed. Cannot confirm audit because of the factory service is down!",
    "content": {
        "invalidSupplier": false,
        "draft": {
            "draftId": null,
            "isAnOrderNotADraft": true,
            "draftSteps": null
        },
        "orderGeneralInfo": {
            "orderId": "2E1C54F73CD44CA89224EF484977233D",
            "orderPlacer": "apiuser001",
            "status": "20",
            "statusText": "WAITING_FOR_VALIDATION",
            "serviceType": "9",
            "serviceTypeText": "EA",
            "bookingDate": "01-Jul-2026",
            "orderNumber": "Q2600365241-PP",
            "companyId": "23EC09AB0F3C46BBA4F79718DCED16D0",
            "userId": "<qima-user-id>",
            "allowChangeInspectionDate": true,
            "supplierValidateCode": "816354",
            "clientRefNb": "2107-0-02026",
            "expectedInspectionDate": "10-Oct-2026",
            "actualInspectionDate": "10-Oct-2026",
            "expectedShipDate": "10-Oct-2026",
            "copyReportMailTo": ["supplier.contact@example.com", "factory.contact@example.com"],
            "confirmed": false
        },
        "orderExtra": {
            "orderId": "2E1C54F73CD44CA89224EF484977233D",
            "cancelable": false,
            "editable": false,
            "isReInspection": false,
            "nbOfInspectors": 1,
            "quickBooking": false,
            "multiSupplierOrder": false
        },
        "orderFactory": {
            "factoryName": "Sample Factory Co.",
            "factoryMGRName": "Factory Manager",
            "factoryMGRNumber": "13800000004",
            "factoryMGREmail": ["factory.contact@example.com"],
            "factoryAddress": "LuoHuQu ChunFenglu 777",
            "factoryCity": "12687656",
            "factoryProvince": "12578019",
            "factoryCountry": "23424781",
            "factoryContinent": "24865671",
            "factoryProductLines": ["bigCat1_s2", "bigCat1_s3"],
            "nbOfWorkers": 1
        },
        "orderSupplier": {
            "orderId": "2E1C54F73CD44CA89224EF484977233D",
            "supplierName": "Sample Supplier Co.",
            "supplierMGRName": "Supplier Manager",
            "supplierMGRNumber": "13800000001",
            "supplierMGREmail": ["supplier.contact@example.com"],
            "supplierAddress": "LuoHuQu ChunFenglu 999",
            "supplierCity": "12687656",
            "supplierCountry": "23424781",
            "supplierContinentID": "24865671",
            "supplierProductLines": ["bigCat1_s2", "bigCat1_s3"],
            "supplierId": "9CB3F02222CA46FC8791D790D5422582"
        },
        "orderAuditGeneral": {
            "orderId": "2E1C54F73CD44CA89224EF484977233D",
            "sampleSize": "1",
            "contactFactoryOrNot": true,
            "guidelines": 0,
            "totalNumberOfBuilding": 1,
            "additionalComment": "test",
            "announcementType": "Semi-Announced",
            "auditWindowFrom": 1791561600000,
            "auditWindowTo": 1791734400000,
            "additiveFactors": "LOASP"
        },
        "orderAuditFieldsList": [
            {
                "id": "374A53BF25394525B079E0BF1A44BB12",
                "orderId": "2E1C54F73CD44CA89224EF484977233D",
                "fieldType": "AI_ETHICAL",
                "fieldId": "CBD9F32199C077B5E0530100007FEB05",
                "specificField": "",
                "weight": "1",
                "selected": true,
                "fieldName": "Health & Safety, Hygiene",
                "description": "Occupational health and safety, building safety, fire safety, machinery safety, electrical safety, chemical safety, hygiene management, etc. The audit includes production and living spaces.",
                "classification": "EA_QIMA_FIELDS",
                "fieldVersion": 3
            },
            {
                "id": "84C53E63F6F54953AAA8CFE8AEEB7A95",
                "orderId": "2E1C54F73CD44CA89224EF484977233D",
                "fieldType": "EA_SMETA",
                "fieldId": "CBD9F32199C577B5E0530100007FEB05",
                "specificField": "",
                "weight": "1",
                "selected": false,
                "fieldName": "Freely Chosen Employment",
                "description": "There is no forced, bonded, or involuntary prison labor. Workers are not required to lodge \u201cdeposits\u201d or their identity papers with their employer and are free to leave their employer after reasonable notice.",
                "classification": "EA_SMETA_2_PILLAR_FIELDS",
                "fieldVersion": 3
            }
        ],
        "auditGuidelineOtherFields": null,
        "utm": null
    }
}

The example above is trimmed to 2 items for readability. The real orderAuditFieldsList array returns the full checklist for every guideline QIMA supports for this audit type — 75 items in this capture, grouped by classification: EA_QIMA_FIELDS (5), EA_SMETA_2_PILLAR_FIELDS (13), EA_SMETA_4_PILLAR_FIELDS (14), EA_BSCI_FIELDS (14), EA_ICS_FIELDS (9), EA_RJC_FIELDS (10), EA_HIGG_FIELDS (10). This is the full checklist, not just the guideline the client selected — use selected to see which fields actually apply to this order.

200 — Order Created Successfully

The 200 response uses the same content shape as the 202 response above, with an empty message:

{
    "message": "",
    "content": {
        "invalidSupplier": false,
        "draft": {
            "draftId": null,
            "isAnOrderNotADraft": true,
            "draftSteps": null
        },
        "orderGeneralInfo": {
            "orderId": "2E1C54F73CD44CA89224EF484977233D",
            "orderPlacer": "apiuser001",
            "status": "20",
            "statusText": "WAITING_FOR_VALIDATION",
            "serviceType": "9",
            "serviceTypeText": "EA",
            "bookingDate": "01-Jul-2026",
            "orderNumber": "Q2600365241-PP",
            "companyId": "23EC09AB0F3C46BBA4F79718DCED16D0",
            "userId": "<qima-user-id>",
            "allowChangeInspectionDate": true,
            "supplierValidateCode": "816354",
            "clientRefNb": "2107-0-02026",
            "expectedInspectionDate": "10-Oct-2026",
            "actualInspectionDate": "10-Oct-2026",
            "expectedShipDate": "10-Oct-2026",
            "copyReportMailTo": ["supplier.contact@example.com", "factory.contact@example.com"],
            "confirmed": false
        },
        "orderExtra": {
            "orderId": "2E1C54F73CD44CA89224EF484977233D",
            "cancelable": false,
            "editable": false,
            "isReInspection": false,
            "nbOfInspectors": 1,
            "quickBooking": false,
            "multiSupplierOrder": false
        },
        "orderFactory": {
            "factoryName": "Sample Factory Co.",
            "factoryMGRName": "Factory Manager",
            "factoryMGRNumber": "13800000004",
            "factoryMGREmail": ["factory.contact@example.com"],
            "factoryAddress": "LuoHuQu ChunFenglu 777",
            "factoryCity": "12687656",
            "factoryProvince": "12578019",
            "factoryCountry": "23424781",
            "factoryContinent": "24865671",
            "factoryProductLines": ["bigCat1_s2", "bigCat1_s3"],
            "nbOfWorkers": 1
        },
        "orderSupplier": {
            "orderId": "2E1C54F73CD44CA89224EF484977233D",
            "supplierName": "Sample Supplier Co.",
            "supplierMGRName": "Supplier Manager",
            "supplierMGRNumber": "13800000001",
            "supplierMGREmail": ["supplier.contact@example.com"],
            "supplierAddress": "LuoHuQu ChunFenglu 999",
            "supplierCity": "12687656",
            "supplierCountry": "23424781",
            "supplierContinentID": "24865671",
            "supplierProductLines": ["bigCat1_s2", "bigCat1_s3"],
            "supplierId": "9CB3F02222CA46FC8791D790D5422582"
        },
        "orderAuditGeneral": {
            "orderId": "2E1C54F73CD44CA89224EF484977233D",
            "sampleSize": "1",
            "contactFactoryOrNot": true,
            "guidelines": 0,
            "totalNumberOfBuilding": 1,
            "additionalComment": "test",
            "announcementType": "Semi-Announced",
            "auditWindowFrom": 1791561600000,
            "auditWindowTo": 1791734400000,
            "additiveFactors": "LOASP"
        },
        "orderAuditFieldsList": [
            {
                "id": "374A53BF25394525B079E0BF1A44BB12",
                "orderId": "2E1C54F73CD44CA89224EF484977233D",
                "fieldType": "AI_ETHICAL",
                "fieldId": "CBD9F32199C077B5E0530100007FEB05",
                "specificField": "",
                "weight": "1",
                "selected": true,
                "fieldName": "Health & Safety, Hygiene",
                "description": "Occupational health and safety, building safety, fire safety, machinery safety, electrical safety, chemical safety, hygiene management, etc. The audit includes production and living spaces.",
                "classification": "EA_QIMA_FIELDS",
                "fieldVersion": 3
            }
        ],
        "auditGuidelineOtherFields": null,
        "utm": null
    }
}

This is the same capture as the 202 example above, with message set to "" per confirmation. The content shape is identical in both cases — the response is 202 when a downstream sub-step (like factory confirmation) reports an issue, and 200 with an empty message when everything succeeds.

400 — Validation Error

{
    "message": "[serviceDate can't be empty]",
    "content": ""
}

Response Field Notes

Field	Notes
`message`	Human-readable status message. Empty (`""`) on a clean success; populated when a sub-step (like factory confirmation) failed.
`orderGeneralInfo.orderId`	Internal QIMA order ID. Use this to search or retrieve the audit report later.
`orderGeneralInfo.orderNumber`	Client-facing QIMA order number, for example `Q2600365241-PP`.
`orderGeneralInfo.status` / `statusText`	Numeric status code and its text label. Confirmed value: `20` = `WAITING_FOR_VALIDATION`.
`orderGeneralInfo.serviceType` / `serviceTypeText`	Numeric service type code and its text label, for example `9` / `EA`. Note this differs from the `serviceType` enum (`ea`, `ma`, ...) used in the request body.
`orderGeneralInfo.supplierValidateCode`	Verification code associated with the supplier for this booking.
`orderAuditGeneral.guidelines`	Audit guideline used: `0` = AI Ethical (matches this example), per the schema `1` = SMETA 2-Pillar, `2` = SMETA 4-Pillar.
`orderAuditGeneral.sampleSize`	Sample size indicator. Per the schema, `1` when the sample size is 500 or more, otherwise `0`.
`orderAuditFieldsList[].fieldType`	Per the source definition: "The type of field, `1`: mandatory; `2`: optional; `3`: specific, `4`: EA_SA8000; `5`: EA_SMETA." Observed values in real responses include audit-guideline-specific codes such as `AI_ETHICAL` and `EA_SMETA`.
`orderAuditFieldsList[].classification`	Groups fields by guideline, for example `EA_QIMA_FIELDS`, `EA_SMETA_2_PILLAR_FIELDS`, `EA_HIGG_FIELDS`.
`orderAuditFieldsList[].selected`	`true` if this checklist field applies to the order being created.
`auditGuidelineOtherFields`	Additional guideline-specific fields beyond the standard checklist. `null` when not applicable to the selected guideline.
`invalidSupplier`	`true` if the supplier information provided could not be validated.

Store the returned orderId (from orderGeneralInfo) if you need to search or retrieve the audit report later.

Common Errors

See common authentication errors for 401 and 403 responses.

Status	Meaning	Recommended Action
`400 Bad Request`	`serviceDate` and `shipDate` cannot be null, and `announcementType` must be a valid value. See the real example above (`[serviceDate can't be empty]`).	Check the request body against the required fields listed above.
`500 Internal Server Error`	Audit order creation failed on the server.	Contact QIMA support with the request time and payload reference.

Next Steps

Search audit reports once the audit has been completed and a report is available.
Retrieve full audit report details using the report ID from the search results.

Documents