DocumentsUpload a Document

Upload your Documents

Uploads one supporting document to Wholechain using multipart/form-data. Document metadata is provided through X-Document-* headers. A successful upload returns a Document ID that can be attached to one or more events.

curl -X POST "https://connect.wholechain.com/Integration/Documents" \
  -H "X-API-KEY: example_string" \
  -H "X-Document-Title: Purchase Order 450001" \
  -H "X-Document-Type: PurchaseOrder" \
  -H "X-Document-Type-Name: John Doe" \
  -H "X-Document-Id: PO-450001" \
  -H "X-Document-Expiration-Date: 2027-08-17" \
  -H "X-Document-Company: supplier_001" \
  -H "X-Document-Location: warehouse_001" \
  -H "X-Document-Product: product_001" \
  -H "X-Document-Privacy: Private" \
  --form file=example_string
{
  "documents": [
    {
      "documentId": "PO-450001",
      "title": "Purchase Order 450001",
      "documentType": "PurchaseOrder",
      "documentTypeName": null,
      "fileName": "purchase-order-450001.pdf",
      "fileType": "application/pdf",
      "expirationDate": "2027-08-17",
      "company": "supplier_001",
      "location": "warehouse_001",
      "product": "product_001",
      "privacy": "Private",
      "status": "Uploaded",
      "error": null
    }
  ]
}
POST
/Integration/Documents
POST
Base URLstring

Target server for requests. Edit to use your own host.

Content-Typestring
Required

The media type of the request body

Options: multipart/form-data
header
X-API-KEYstring
Required

Your Wholechain Connect API key.

header
X-Document-Titlestring
Required

Display name of the document in Wholechain. Leading and trailing spaces are trimmed.

Max length: 200
header
X-Document-Typestring
Required

Document type. Values are not case-sensitive.

Options: Certification, PurchaseOrder, BOL, Other
header
X-Document-Type-Namestring

Custom document type name. Required when X-Document-Type is Other.

header
X-Document-Idstring

Optional external Document ID. Must be unique within the Wholechain account, ignoring case. If omitted, Wholechain generates an ID in the format DOC-<32 hex characters>.

Min length: 1 • Max length: 100 • Pattern: ^[A-Za-z0-9._#-]+$
header
X-Document-Expiration-Datestring

Optional document expiration date in YYYY-MM-DD format.

Format: date
header
X-Document-Companystring

External ID of a trade partner in your Wholechain account.

header
X-Document-Locationstring

External ID of a location in your Wholechain account.

header
X-Document-Productstring

External ID of a product in your Wholechain account.

header
X-Document-Privacystring

Document privacy setting. Values are not case-sensitive. Defaults to Private.

Options: Public, Private
filefile
Required

Document file to upload. Supported extensions: .pdf, .xlsx, .xls, .csv, .docx, .doc, .jpeg and .jpg. One file per request.

Format: binary
Request Preview
Response

Response will appear here after sending the request

Responses

documentsarray
Required

Introduction

The Documents API lets you upload supporting documents to Wholechain, ready to attach to traceability events, with no manual steps in the Wholechain UI.

Use it for purchase orders, invoices, bills of lading, packing lists, certificates, inspection records and similar files. Documents uploaded through the API appear in the Wholechain Documents section and on each event they are attached to, just like documents uploaded in the UI.

Attaching a document takes two steps:

  1. Upload the document with POST /Integration/Documents. Send one file per request. The response returns the Document ID: either the one you supplied or one Wholechain generated.
  2. Reference the Document ID in an event. Add it to the DocumentIds array of any event you send. Wholechain attaches the document when it creates the event. This step is covered in the Events API documentation.

A document can be attached to any number of events, and its ID can be used as soon as the upload succeeds.

Authentication

Authenticate every request with your existing Wholechain Connect API key in the X-API-KEY header.

Documents belong to the account that owns the API key. An event can only attach documents from that same account.

Upload a document

POST /Integration/Documents uploads one file as multipart/form-data, with its metadata sent in X-Document-* headers.

Headers

HeaderRequiredDescription
X-API-KEYYesYour Wholechain Connect API key.
X-Document-TitleYesDisplay name shown in Wholechain. Max 200 characters. Leading and trailing spaces are trimmed.
X-Document-TypeYesCertification, PurchaseOrder, BOL or Other. Not case-sensitive.
X-Document-Type-NameWhen type is OtherYour label for the document type, such as Invoice or Packing List.
X-Document-IdNoYour own ID for the document, such as the ID in your ERP. 1–100 characters: letters, digits, ., _, - and #. Must be unique in your account, ignoring case. If omitted, Wholechain generates an ID in the form DOC-<32 hex characters>.
X-Document-Expiration-DateNoExpiration date in YYYY-MM-DD format, such as 2027-08-17.
X-Document-CompanyNoExternal ID of a trade partner in your account.
X-Document-LocationNoExternal ID of a location in your account.
X-Document-ProductNoExternal ID of a product in your account.
X-Document-PrivacyNoPublic or Private. Not case-sensitive. Defaults to Private.

File

Send the file in a multipart form field named file. Each request takes exactly one file.

RuleValue
Allowed extensions.pdf, .xlsx, .xls, .csv, .docx, .doc, .jpeg, .jpg (not case-sensitive)
Maximum size20 MB
Empty filesRejected

Set the file's content type in the request (for example type=application/pdf with curl). Wholechain determines the stored content type from the file; the fileType in the response shows the stored value.

Example request

curl -X POST "https://connect.wholechain.com/Integration/Documents" \
  -H "X-API-KEY: <api-key>" \
  -H "X-Document-Title: Purchase Order 450001" \
  -H "X-Document-Type: PurchaseOrder" \
  -H "X-Document-Id: PO-450001" \
  -H "X-Document-Expiration-Date: 2027-08-17" \
  -H "X-Document-Company: <trade-partner-id>" \
  -H "X-Document-Location: <location-id>" \
  -H "X-Document-Product: <product-id>" \
  -H "X-Document-Privacy: Private" \
  -F "file=@purchase-order-450001.pdf;type=application/pdf"

For a custom type, send Other together with a type name:

curl -X POST "https://connect.wholechain.com/Integration/Documents" \
  -H "X-API-KEY: <api-key>" \
  -H "X-Document-Title: Invoice INV-12345" \
  -H "X-Document-Type: Other" \
  -H "X-Document-Type-Name: Invoice" \
  -F "file=@INV-12345.xlsx;type=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"

Upload response

The response holds a documents array with one result for the uploaded file. Check status: Uploaded means success; Failed means nothing was stored, and error says why.

Status codes

HTTP statusMeaning
200 OKDocument uploaded. status is Uploaded.
422 Unprocessable ContentValidation failed. status is Failed and error gives the reason. Nothing is stored.
401 UnauthorizedAPI key missing or not valid.
413 Request Entity Too LargeFile exceeds the size limit.

Fields

FieldDescription
documentIdThe Document ID: yours, or the one Wholechain generated. Use it in events.
titleThe stored title.
documentTypeCertification, PurchaseOrder, BOL or Other.
documentTypeNameThe custom type name, when the type is Other.
fileNameThe original file name.
fileTypeThe file's content type, such as application/pdf.
expirationDateExpiration date (YYYY-MM-DD), or null.
companyTrade partner external ID, or null.
locationLocation external ID, or null.
productProduct external ID, or null.
privacyPublic or Private.
statusUploaded or Failed.
errorWhy the upload failed, or null.

Success example

{
  "documents": [
    {
      "documentId": "PO-450001",
      "title": "Purchase Order 450001",
      "documentType": "PurchaseOrder",
      "documentTypeName": null,
      "fileName": "purchase-order-450001.pdf",
      "fileType": "application/pdf",
      "expirationDate": "2027-08-17",
      "company": "<trade-partner-id>",
      "location": "<location-id>",
      "product": "<product-id>",
      "privacy": "Private",
      "status": "Uploaded",
      "error": null
    }
  ]
}

Failure example: duplicate Document ID

An ID already in use is rejected, and the existing document is left unchanged.

{
  "documents": [
    {
      "documentId": "PO-450001",
      "title": "Purchase Order 450001",
      "documentType": "PurchaseOrder",
      "documentTypeName": null,
      "fileName": "purchase-order-450001.pdf",
      "fileType": "application/pdf",
      "expirationDate": null,
      "company": null,
      "location": null,
      "product": null,
      "privacy": "Private",
      "status": "Failed",
      "error": "Document ID 'PO-450001' is already in use."
    }
  ]
}

Failure example: unsupported file type

{
  "documents": [
    {
      "documentId": "PO-450001",
      "fileName": "invoice.txt",
      "fileType": "text/plain",
      "status": "Failed",
      "error": "The file type is not supported. Allowed types are pdf, xlsx, xls, csv, docx, doc, jpeg, and jpg."
    }
  ]
}

Attaching documents to events

After a successful upload, add the returned documentId to the DocumentIds array of an event. See the Events API documentation for the field, the supported event types, and how IDs that can't be found are reported.

  • The Document ID can be used as soon as the upload returns status: Uploaded.
  • One document can be attached to any number of events.
  • Only documents from the same account as the API key can be attached.

Errors reference

Every validation failure returns 422 with status: Failed and one of these messages in error. Nothing is stored.

error messageCause
Document title is required.X-Document-Title missing or blank.
Document title must not be longer than 200 characters.Title over 200 characters.
Document type is required and must be Certification, PurchaseOrder, Other, or BOL.X-Document-Type missing or not one of the four values.
Document type name is required when the document type is Other.Type is Other without X-Document-Type-Name.
Document ID must be 1-100 characters and must not contain control characters.The document ID is empty, longer than 100 characters, or contains a control character. Letters, digits, periods, underscores, hyphens, and # are accepted; spaces are rejected.
Document ID '<id>' is already in use.The ID already exists in your account, in any letter case.
Expiration date must be an ISO date (YYYY-MM-DD).Wrong format or not a real date, such as 2027-02-29.
Privacy must be Public or Private.Any other privacy value.
Company not found: <id>No trade partner with that external ID.
Location not found: <id>No location with that external ID.
Product not found: <id>No product with that external ID.
Please add a document file.No file field, or the file is empty.
The file type is not supported. Allowed types are pdf, xlsx, xls, csv, docx, doc, jpeg, and jpg.File type not in the allowed list.
Send one file per request.More than one file in the request. Note: this error body is a plain JSON string, not a documents array.

Non-validation errors:

HTTP statusCause
401API key not valid. Body: {"type":"https://tools.ietf.org/html/rfc9110#section-15.5.2","title":"The API key is not valid.","status":401,"traceId":"…"}
400X-API-KEY header empty (The apiKey field is required.).
413File over the size limit. The response body is an HTML page from the web server, not JSON.