{"componentChunkName":"component---src-templates-simple-markdown-js","path":"/docs/ai/document-ai/uploading-documents/","matchPath":"","result":{"data":{"markdownRemark":{"html":"

Uploading Documents

\n

You can upload documents from the Shipwell interface or through the API. At upload time, choose whether to store the file only or start a processing run.

\n

Upload in Shipwell

\n
    \n
  1. \nOpen \nDocument AI\n.\n
    2. \n
  2. \nSelect \nUpload documents\n.\n
    3. \n
  3. \nAdd one or more files.\n
    4. \n
  4. \nOptionally associate the files with a Shipwell resource.\n
    5. \n
  5. \nChoose an upload behavior:\n\n
    6. \n
  6. \nReview the files and submit the upload.\n
    7. \n
\n

\"Adding

\n\n

Associate documents with other resources

\n

Associations make a document easier to find from another business object. Each association contains:

\n\n

An upload cannot contain the same entity_type and entity_id pair more than once.

\n\n

Upload through the API

\n

The API supports three upload patterns:

\n
    \n
  1. \nMultipart upload for one or more files\n
    2. \n
  2. \nBase64 JSON for one file\n
    3. \n
  3. \nA two-step direct upload for large files\n
    4. \n
\n

Multipart upload

\n

Send up to 20 files in one multipart/form-data request. The payload form field is a JSON string.

\n\n
\n
\n curlpython\n
\n
\n
\n
" \\\\\n -F 'payload={\n "processing_config_id": "",\n "files": [{"filename": "bol.pdf"}]\n }' \\\\\n -F "files=@bol.pdf"`, `719871321240495000`)\"\n >\n
Copy
\n
Copied
\n
\n 
curl -X POST "https://sandbox-api.shipwell.com/document-store/documents" \\\n  -H "Authorization: Token <user-token>" \\\n  -F 'payload={\n    "processing_config_id": "<processing-config-id>",\n    "files": [{"filename": "bol.pdf"}]\n  }' \\\n  -F "files=@bol.pdf"
\n
\n
"},\n data={"payload": json.dumps({\n "processing_config_id": "",\n "files": [{"filename": "bol.pdf"}],\n })},\n files={"files": ("bol.pdf", document_file, "application/pdf")},\n timeout=60,\n )\nresponse.raise_for_status()\nupload = response.json()`, `14905436052649690000`)\"\n >\n
Copy
\n
Copied
\n
\n 
import json\n\nimport requests\n\nwith open(\"bol.pdf\", \"rb\") as document_file:\n    response = requests.post(\n        \"https://sandbox-api.shipwell.com/document-store/documents\",\n        headers={\"Authorization\": \"Token <user-token>\"},\n        data={\"payload\": json.dumps({\n            \"processing_config_id\": \"<processing-config-id>\",\n            \"files\": [{\"filename\": \"bol.pdf\"}],\n        })},\n        files={\"files\": (\"bol.pdf\", document_file, \"application/pdf\")},\n        timeout=60,\n    )\nresponse.raise_for_status()\nupload = response.json()
\n
\n
\n \n

The response contains:

\n\n

When processing is requested, each accepted document includes its newly created run in latest_run.

\n

Base64 JSON upload

\n

Use base64 JSON when your client cannot send multipart data:

\n

Send filename, content_base64, and content_type as JSON to POST /document-store/documents.

\n

This format accepts one file per request and returns one document.

\n

Direct upload

\n

For clients that should upload bytes directly, use a two-step flow.

\n

Request an upload URL, upload the bytes, and commit the document:

\n
    \n
  1. \nRequest an upload URL with \nPOST /document-store/documents/presigned-uploads\n.\n
    2. \n
  2. \nUpload the bytes to the returned \nupload_url\n.\n
    3. \n
  3. \nCommit the document with \nPOST /document-store/documents/{id}:commit\n.\n
    4. \n
\n

The prepare response contains upload_url, object_key, document_id, and expires_in. Upload URLs are valid for five minutes. Send the same Content-Type when uploading bytes.

\n

The upload URL is temporary. Treat it as sensitive and do not log or share it.

\n

Choose processing behavior

\n

For every upload method:

\n\n

See Choosing a Configuration before using inline pipeline_config.

\n

File eligibility

\n

Allowed file types and limits can vary by account and MIME type. Retrieve the current catalog before validating uploads in your application:

\n

Use GET /document-store/configs/upload-file-types.

\n

See Errors and Limits for the meaning of storage and processing limits.

","headings":[{"value":"Uploading Documents","depth":1},{"value":"Upload in Shipwell","depth":2},{"value":"Associate documents with other resources","depth":2},{"value":"Upload through the API","depth":2},{"value":"Multipart upload","depth":3},{"value":"Base64 JSON upload","depth":3},{"value":"Direct upload","depth":3},{"value":"Choose processing behavior","depth":2},{"value":"File eligibility","depth":2}]},"contentItem":{"data":{"lastModified":"2026-07-17T16:00:10.000Z","enableToc":null,"disableLastModified":null,"tocMaxDepth":null,"requestLogin":false}},"siteConfig":{"enableToc":true,"disableLastModified":false,"tocMaxDepth":4}},"pageContext":{"matchPath":"","id":"5e7e03e7-7991-5a6e-a27d-90f489f3ad1e__redocly content/docs/ai/document-ai/uploading-documents/","seo":{"title":"Uploading Documents","description":null,"image":"","keywords":null,"jsonLd":null,"lang":null,"siteUrl":null},"pageId":"docs/ai/document-ai/uploading-documents.md","pageBaseUrl":"/docs/ai/document-ai/uploading-documents","type":"markdown","toc":{"enable":true,"maxDepth":4,"headings":[{"depth":1,"value":"Uploading Documents","id":"uploading-documents"},{"depth":2,"value":"Upload in Shipwell","id":"upload-in-shipwell"},{"depth":2,"value":"Associate documents with other resources","id":"associate-documents-with-other-resources"},{"depth":2,"value":"Upload through the API","id":"upload-through-the-api"},{"depth":3,"value":"Multipart upload","id":"multipart-upload"},{"depth":3,"value":"Base64 JSON upload","id":"base64-json-upload"},{"depth":3,"value":"Direct upload","id":"direct-upload"},{"depth":2,"value":"Choose processing behavior","id":"choose-processing-behavior"},{"depth":2,"value":"File eligibility","id":"file-eligibility"}]},"data":{"title":"Uploading Documents"},"catalogInfo":null,"link":"/docs/ai/document-ai/uploading-documents/","sidebarName":"developerPortal","isLanding":false,"showPrevButton":null,"showNextButton":null,"apiVersions":null,"apiVersionId":null,"isDefaultApiVersion":null}},"staticQueryHashes":["1123603147","1302185487","1344209882","1398840060","1520077861","1975142765","2667623876","2950305614","3240152602","3743992808","561138138"]}