Supplier Create Guide

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

Use this API to register a new supplier under your client account. If a supplier with the same name or identification code already exists, the request is rejected.

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

Endpoint

POST https://ppapi.qima.com/user/v2/{userId}/supplier

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

Prerequisites

In addition to the required headers and authentication setup:

Permission to create suppliers for the target client
Geographic parameter values (continent/country/province/city IDs) from the Parameter module
Product line values from Get All Product Families

Path Parameters

Parameter	Required	Description
`userId`	Yes	QIMA client user login ID.

Request Body Fields

The request body uses the SupplierDetailBean schema. See the interactive API reference for the complete field list.

Field	Required	Notes
`entityName`	Yes	Supplier's legal/business name.
`chineseName`	No	Supplier name in local language.
`continent` / `country` / `province` / `city`	`country`, `city` required	Geographic IDs from the Parameter module.
`district` / `districtName`	No	District ID/name, if applicable.
`address`	Yes	Supplier's address.
`addressCn`	No	Address in local language.
`identificationCode`	No	Your own identifier code for this supplier — use this to link the supplier between your system and QIMA's.
`mainProductLines`	Yes	Product family IDs from Get All Product Families.
`contactInfo.main` / `contactInfo.alternate`	`main` required	Contact details (`name`, `department`, `title`, `phone`, `mobile`, `email`). Separate multiple emails with a semicolon.
`type`	No	Supplier type, for example `SUPPLIER`.
`businessLicenseNo`	No	Business license number.
`salesTurnover` / `noOfEmployees`	No	Business scale indicators.

Request Example

curl --location --request POST 'https://ppapi.qima.com/user/v2/<qima-user-id>/supplier' \
  --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 '{
    "entityName": "JiXieChang-Supplier2",
    "chineseName": "机械厂",
    "continent": "24865671",
    "country": "23424781",
    "province": "12578016",
    "city": "12687656",
    "district": "",
    "address": "NO.1, A ROAD, B STREET, C DISTRICT",
    "addressCn": "深圳市南山区某路1号",
    "postcode": "518000",
    "nearestOffice": "Shenzhen office",
    "website": "https://www.example-supplier.com",
    "salesTurnover": "5000000",
    "noOfEmployees": "10",
    "userId": "<qima-user-id>",
    "type": "SUPPLIER",
    "businessLicenseNo": "91440300MA5XXXXXXX",
    "title": "Mr.",
    "identificationCode": "CLIENT-SUP-002",
    "cityName": "Shenzhen",
    "districtName": "Nanshan",
    "countryName": "China",
    "mainProductLines": ["bigCat1_s2", "bigCat1_s3"],
    "contactInfo": {
      "main": {
        "name": "Bill Gates",
        "department": "Quality",
        "title": "Quality Manager",
        "phone": "+86 0755 81112222",
        "mobile": "13811112222",
        "email": "aaa@bbb.com;ccc@ddd.com"
      },
      "alternate": {
        "name": "Jane Doe",
        "department": "Sales",
        "title": "Sales Manager",
        "phone": "+86 0755 83334444",
        "mobile": "13922223333",
        "email": "jane.doe@example.com"
      }
    }
  }'

Successful Response

HTTP 200 OK returns the newly created supplier, including a generated id.

{
    "message": null,
    "content": {
        "id": "A7B918B5222D4B0F98061168865EAF17",
        "entityName": "JiXieChang-Supplier2",
        "chineseName": "机械厂",
        "continent": "24865671",
        "country": "23424781",
        "province": "12578016",
        "city": "12687656",
        "district": null,
        "address": "NO.1, A ROAD, B STREET, C DISTRICT",
        "postcode": "518000",
        "nearestOffice": "Shenzhen office",
        "website": "https://www.example-supplier.com",
        "salesTurnover": "5000000",
        "noOfEmployees": "10",
        "userId": "4C6E94072DFC4918B60752F701DE544A",
        "type": "SUPPLIER",
        "businessLicenseNo": "91440300MA5XXXXXXX",
        "title": "Mr.",
        "addressCn": "深圳市南山区某路1号",
        "identificationCode": "CLIENT-SUP-002",
        "cityName": "Shenzhen",
        "districtName": null,
        "countryName": "China",
        "mainProductLines": ["bigCat1_s2", "bigCat1_s3"],
        "contactInfo": {
            "main": {
                "name": "Bill Gates",
                "department": "Quality",
                "title": "Quality Manager",
                "phone": "+86 0755 81112222",
                "mobile": "13811112222",
                "email": "aaa@bbb.com;ccc@ddd.com"
            },
            "alternate": {
                "name": "Jane Doe",
                "department": "Sales",
                "title": "Sales Manager",
                "phone": "+86 0755 83334444",
                "mobile": "13922223333",
                "email": "jane.doe@example.com"
            }
        },
        "accessMaps": [],
        "qualityDocs": [
            { "id": null, "docType": "", "fileName": null, "fileSize": 0, "url": null }
        ],
        "createBy": "",
        "updateBy": ""
    }
}

The real capture returns 7 empty placeholder entries in qualityDocs — trimmed to 1 above. These look like pre-allocated document slots rather than actual uploaded documents (all fields are null/empty).

Response Field Notes

Field	Notes
`id`	The new supplier ID. Store this for Get, Update, and Delete calls.
`district` / `districtName`	`null` when not provided at creation, even if you pass an empty string.
`accessMaps`	List of uploaded access map files (see the File module). Empty when none uploaded.
`qualityDocs`	List of quality document slots/files. May contain empty placeholder entries.

Common Errors

See common authentication errors for 401 and 403 responses.

Status	Meaning	Recommended Action
`412 Precondition Failed`	`"The supplier with the same name or identification code already exists"`.	Use Search Suppliers to check for an existing match before creating, or update the existing supplier instead.
`500 Internal Server Error`	Supplier creation failed on the server.	Contact QIMA support with the request time and payload reference.

Next Steps

Use the returned id with Get Supplier Details to verify the created record, or when booking an Inspection/Audit/Lab Testing order.

Documents