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

Custom Configurations

\n

Create a custom processing configuration when your company needs a repeatable extraction or enrichment workflow.

\n

Create a configuration in Shipwell

\n
    \n
  1. \nOpen \nDocument AI\n.\n
    2. \n
  2. \nSelect \nConfiguration\n.\n
    3. \n
  3. \nOpen \nProcessing Configuration\n.\n
    4. \n
  4. \nSelect \nNew Processing Config\n.\n
    5. \n
  5. \nEnter a unique name and a description that tells users when to select it.\n
    6. \n
  6. \nLeave \nEnabled\n selected if the configuration should immediately appear in upload and processing workflows.\n
    7. \n
  7. \nSelect \nCreate\n.\n
    8. \n
\n

\"Creating

\n

After creation, configure document enrichment, document structure, and extraction schemas.

\n

Configure document enrichment

\n

Generate per-page embeddings

\n

Enable embeddings when users or integrations should be able to find processed documents by meaning. A document must have embeddings to appear in semantic search results.

\n

Enable auto-description

\n

Enable auto-description to generate a concise natural-language description after a successful run.

\n

You can also:

\n\n

The generated description becomes the document's current description after a successful run.

\n

\"Document

\n

Configure document structure

\n

Enable Split into per-document slices when a single PDF may contain multiple logical documents, such as an invoice followed by a proof of delivery.

\n

Splitting applies to eligible PDFs. Each detected logical document is returned as a separate result while remaining associated with the uploaded parent document.

\n

Add extraction schemas

\n

An extraction schema tells Document AI what value to find and what JSON shape to return.

\n

For each schema:

\n
    \n
  1. \nEnter a stable, machine-readable name.\n
    2. \n
  2. \nWrite a focused extraction prompt.\n
    3. \n
  3. \nDefine the expected value with JSON Schema.\n
    4. \n
  4. \nChoose whether extraction applies to each segment or the whole document.\n
    5. \n
  5. \nChoose whether to return one result or multiple results.\n
    6. \n
  6. \nEnable source regions if users need to locate the value on a PDF or image.\n
    7. \n
\n

\"Building

\n

For example:

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"name\": \"purchase_order_number\",\n  \"prompt\": \"Extract the purchase order number. Return null when it is not present.\",\n  \"json_schema\": {\n    \"type\": [\"string\", \"null\"]\n  },\n  \"scope\": \"document\",\n  \"result_cardinality\": \"single\",\n  \"include_source_regions\": true\n}
\n
\n

See Extraction Schemas for schema design, JSON shapes, scope, cardinality, source regions, and the schema-generation helper.

\n

Save and test

\n
    \n
  1. \nSelect \nSave changes\n.\n
    2. \n
  2. \nUpload a representative synthetic document.\n
    3. \n
  3. \nSelect your custom configuration in \nUpload behavior\n.\n
    4. \n
  4. \nReview every extracted value and its source.\n
    5. \n
  5. \nTest missing values, repeated values, and documents with different layouts.\n
    6. \n
\n

Do not test with production-sensitive documents in a sandbox environment.

\n

Manage availability

\n

Disable a configuration to prevent it from being selected for new uploads and manual runs. Existing run history and results are not changed.

\n

Delete a custom configuration only when it is no longer needed. Platform-managed configurations cannot be deleted.

\n

Create a configuration through the API

\n\n
\n
\n curlpython\n
\n
\n
\n
" \\\\\n -H "Content-Type: application/json" \\\\\n -d '{\n "name": "Purchase order extraction",\n "description": "Extracts purchase order identifiers and totals.",\n "enabled": true,\n "pipeline_config": {\n "schemas": [\n {\n "name": "purchase_order_number",\n "prompt": "Extract the purchase order number. Return null when absent.",\n "json_schema": {"type": ["string", "null"]},\n "scope": "document",\n "result_cardinality": "single",\n "include_source_regions": true\n },\n {\n "name": "total_amount",\n "prompt": "Extract the total amount and currency.",\n "json_schema": {\n "type": ["object", "null"],\n "properties": {\n "amount": {"type": "number"},\n "currency": {"type": "string"}\n },\n "required": ["amount", "currency"],\n "additionalProperties": false\n },\n "scope": "document",\n "result_cardinality": "single"\n }\n ],\n "split": false,\n "embed": true,\n "describe": {\n "enabled": true,\n "key_facts": true\n }\n }\n }'`, `47775261474618610000`)\"\n >\n
Copy
\n
Copied
\n
\n 
curl -X POST "https://sandbox-api.shipwell.com/document-store/configs/processing-configs" \\\n  -H "Authorization: Token <user-token>" \\\n  -H "Content-Type: application/json" \\\n  -d '{\n    "name": "Purchase order extraction",\n    "description": "Extracts purchase order identifiers and totals.",\n    "enabled": true,\n    "pipeline_config": {\n      "schemas": [\n        {\n          "name": "purchase_order_number",\n          "prompt": "Extract the purchase order number. Return null when absent.",\n          "json_schema": {"type": ["string", "null"]},\n          "scope": "document",\n          "result_cardinality": "single",\n          "include_source_regions": true\n        },\n        {\n          "name": "total_amount",\n          "prompt": "Extract the total amount and currency.",\n          "json_schema": {\n            "type": ["object", "null"],\n            "properties": {\n              "amount": {"type": "number"},\n              "currency": {"type": "string"}\n            },\n            "required": ["amount", "currency"],\n            "additionalProperties": false\n          },\n          "scope": "document",\n          "result_cardinality": "single"\n        }\n      ],\n      "split": false,\n      "embed": true,\n      "describe": {\n        "enabled": true,\n        "key_facts": true\n      }\n    }\n  }'
\n
\n
"},\n json=payload,\n timeout=30,\n)\nresponse.raise_for_status()\nconfiguration = response.json()`, `25997508960452276000`)\"\n >\n
Copy
\n
Copied
\n
\n 
import requests\n\npayload = {\n    \"name\": \"Purchase order extraction\",\n    \"description\": \"Extracts purchase order identifiers and totals.\",\n    \"enabled\": True,\n    \"pipeline_config\": {\n        \"schemas\": [\n            {\n                \"name\": \"purchase_order_number\",\n                \"prompt\": \"Extract the purchase order number. Return null when absent.\",\n                \"json_schema\": {\"type\": [\"string\", \"null\"]},\n                \"scope\": \"document\",\n                \"result_cardinality\": \"single\",\n                \"include_source_regions\": True,\n            },\n            {\n                \"name\": \"total_amount\",\n                \"prompt\": \"Extract the total amount and currency.\",\n                \"json_schema\": {\n                    \"type\": [\"object\", \"null\"],\n                    \"properties\": {\n                        \"amount\": {\"type\": \"number\"},\n                        \"currency\": {\"type\": \"string\"},\n                    },\n                    \"required\": [\"amount\", \"currency\"],\n                    \"additionalProperties\": False,\n                },\n                \"scope\": \"document\",\n                \"result_cardinality\": \"single\",\n            },\n        ],\n        \"split\": False,\n        \"embed\": True,\n        \"describe\": {\"enabled\": True, \"key_facts\": True},\n    },\n}\n\nresponse = requests.post(\n    \"https://sandbox-api.shipwell.com/document-store/configs/processing-configs\",\n    headers={\"Authorization\": \"Token <user-token>\"},\n    json=payload,\n    timeout=30,\n)\nresponse.raise_for_status()\nconfiguration = response.json()
\n
\n
\n \n

Names must be unique within your company.

\n

Update or delete through the API

\n

Use PATCH /document-store/configs/processing-configs/{id} to update only the fields that should change.

\n

Use DELETE /document-store/configs/processing-configs/{id} to delete a company-owned configuration. A successful delete returns 204 No Content.

","headings":[{"value":"Custom Configurations","depth":1},{"value":"Create a configuration in Shipwell","depth":2},{"value":"Configure document enrichment","depth":2},{"value":"Generate per-page embeddings","depth":3},{"value":"Enable auto-description","depth":3},{"value":"Configure document structure","depth":2},{"value":"Add extraction schemas","depth":2},{"value":"Save and test","depth":2},{"value":"Manage availability","depth":2},{"value":"Create a configuration through the API","depth":2},{"value":"Update or delete through the API","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":"916b42ef-59c1-5f8f-b241-600744a424b4__redocly content/docs/ai/document-ai/custom-configurations/","seo":{"title":"Custom Configurations","description":null,"image":"","keywords":null,"jsonLd":null,"lang":null,"siteUrl":null},"pageId":"docs/ai/document-ai/custom-configurations.md","pageBaseUrl":"/docs/ai/document-ai/custom-configurations","type":"markdown","toc":{"enable":true,"maxDepth":4,"headings":[{"depth":1,"value":"Custom Configurations","id":"custom-configurations"},{"depth":2,"value":"Create a configuration in Shipwell","id":"create-a-configuration-in-shipwell"},{"depth":2,"value":"Configure document enrichment","id":"configure-document-enrichment"},{"depth":3,"value":"Generate per-page embeddings","id":"generate-per-page-embeddings"},{"depth":3,"value":"Enable auto-description","id":"enable-auto-description"},{"depth":2,"value":"Configure document structure","id":"configure-document-structure"},{"depth":2,"value":"Add extraction schemas","id":"add-extraction-schemas"},{"depth":2,"value":"Save and test","id":"save-and-test"},{"depth":2,"value":"Manage availability","id":"manage-availability"},{"depth":2,"value":"Create a configuration through the API","id":"create-a-configuration-through-the-api"},{"depth":2,"value":"Update or delete through the API","id":"update-or-delete-through-the-api"}]},"data":{"title":"Custom Configurations"},"catalogInfo":null,"link":"/docs/ai/document-ai/custom-configurations/","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"]}