Create a supplier inquiry

Two endpoints write to a supplier conversation: one starts it, one continues it. Both take the same questions array and both accept an Idempotency-Key.

Create an inquiry

POST /v1/supplier-inquiries — scope supplier_inquiry:write.

Request body

Field	Required	Description
`product_url`	Yes	Absolute 1688 or Taobao product link, max 2048 characters
`questions`	Yes	1–10 questions, see question types
`sku`	No	`{ "id": "...", "label": "..." }`, 200 characters each — narrows the question to one variant
`attachments`	No	Up to 5 file references, see attachments

POST /v1/supplier-inquiries
Authorization: Bearer hio_live_...
Idempotency-Key: inq-2026-05-20-001
 
{
  "product_url": "https://detail.1688.com/offer/554456348334.html",
  "sku": { "id": "3245:12345", "label": "Black / XL" },
  "questions": [
    { "type": "packed_weight", "note": "Weight with the retail box" },
    { "type": "carton_info" },
    { "type": "neutral_packaging" }
  ]
}

Response

201 Created, or 200 OK when an Idempotency-Key replays an earlier request.

{
  "id": "sinq_9f2c...",
  "status": "waiting_supplier",
  "product": {
    "channel": "1688",
    "source_product_id": "554456348334",
    "product_url": "https://detail.1688.com/offer/554456348334.html",
    "canonical_product_url": "https://detail.1688.com/offer/554456348334.html",
    "title": "...",
    "image": "...",
    "shop_id": "...",
    "shop_name": "..."
  },
  "sku": {
    "id": "3245:12345",
    "label": "Black / XL"
  },
  "message_count": 1,
  "last_message_at": "2026-05-20T08:31:12.000Z",
  "created_at": "2026-05-20T08:31:11.000Z",
  "updated_at": "2026-05-20T08:31:12.000Z",
  "message": {
    "id": "smsg_1a4b...",
    "type": "initial",
    "status": "waiting_supplier"
  },
  "request_id": "req_..."
}

title, image, shop_id and shop_name are filled on a best-effort basis. Enriching them uses the product detail API, which needs a marketplace authorization your application may not hold — when it is unavailable these fields stay null and the inquiry proceeds normally.

One active inquiry per product

If the product already has an active inquiry, the call fails:

409 Conflict
{
  "error": {
    "code": "ACTIVE_INQUIRY_EXISTS",
    "message": "An active supplier inquiry already exists for this product.",
    "details": { "inquiry_id": "sinq_9f2c...", "next_action": "add_message" }
  }
}

Use the returned inquiry_id to post a follow-up. If the previous conversation is completed or failed, the create call reopens it instead of failing, and the new message is recorded as a follow_up.

Ask a follow-up

POST /v1/supplier-inquiries/{inquiry_id}/messages — scope supplier_inquiry:write.

POST /v1/supplier-inquiries/sinq_9f2c.../messages
{
  "questions": [
    { "type": "lead_time", "note": "For 500 units" },
    { "type": "moq" }
  ],
  "attachments": [
    {
      "type": "image",
      "url": "https://cdn.example.com/packaging-example.jpg",
      "filename": "packaging-example.jpg",
      "mime_type": "image/jpeg"
    }
  ]
}

201 Created
{
  "inquiry_id": "sinq_9f2c...",
  "status": "waiting_supplier",
  "message": {
    "id": "smsg_77de...",
    "type": "follow_up",
    "status": "waiting_supplier",
    "questions": [
      { "id": "sqst_...", "type": "lead_time", "note": "For 500 units", "question": null, "status": "pending", "answer": null }
    ],
    "attachments": [
      {
        "id": "satt_...",
        "type": "image",
        "url": "https://cdn.example.com/packaging-example.jpg",
        "filename": "packaging-example.jpg",
        "mime_type": "image/jpeg",
        "source": "developer",
        "expires_at": null,
        "created_at": "2026-05-20T10:02:00.000Z"
      }
    ],
    "provider_note": null,
    "created_at": "2026-05-20T10:02:00.000Z",
    "answered_at": null
  },
  "request_id": "req_..."
}

A cancelled inquiry rejects new messages with 409 INQUIRY_NOT_ACTIVE. A completed or failed one is reopened.

Attachments

Both write endpoints accept an optional attachments array — a reference photo, a SKU screenshot, a dimension drawing, a specification PDF. Attachments belong to the message you send them with, so each round of the conversation carries its own.

Field	Required	Description
`url`	Yes	`https://` only, max 2048 characters. `http:`, `file:`, `data:`, `javascript:` and `ftp:` are rejected with `INVALID_ATTACHMENT_URL`
`type`	No	`image`, `document` or `other`; defaults to `other`
`filename`	No	Max 255 characters
`mime_type`	No	Max 128 characters — your declared value, stored as-is

At most five attachments per message, otherwise 400 TOO_MANY_ATTACHMENTS.

HIOBuy stores the metadata and the URL, never the file: it does not upload, download, copy or proxy attachment content, and it never fetches the URL you send. Host the file yourself and make sure the URL is reachable by the inquiry service for as long as the conversation is open.

Idempotency

Send Idempotency-Key (or X-Idempotency-Key, max 200 characters) on both write endpoints. A repeated key within the same application returns the message created the first time, with status 200 instead of 201, and never contacts the supplier twice.

Always retry a timed-out create with the same key — without one, a retry may open a second conversation or hit ACTIVE_INQUIRY_EXISTS.

Get Support

Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days

Email support