1"use strict";(self.webpackChunkdocumentpro_docs=self.webpackChunkdocumentpro_docs||[]).push([[8e3],{82:(e,s,n)=>{n.r(s),n.d(s,{assets:()=>l,contentTitle:()=>c,default:()=>h,frontMatter:()=>d,metadata:()=>i,toc:()=>a});const i=JSON.parse('{"id":"using-api/classify/create-classifier","title":"Create Classifier","description":"A Classifier is a reusable set of categories you define once and apply to many documents. Once created, you can run it against any document using Run Classification \u2014 no need to resend your label definitions with each request.","source":"@site/docs/using-api/classify/create-classifier.mdx","sourceDirName":"using-api/classify","slug":"/using-api/classify/create-classifier","permalink":"/docs/using-api/classify/create-classifier","draft":false,"unlisted":false,"tags":[],"version":"current","sidebarPosition":2,"frontMatter":{"sidebar_position":2},"sidebar":"tutorialSidebar","previous":{"title":"Classify Document","permalink":"/docs/using-api/classify/classify-document"},"next":{"title":"List Classifiers","permalink":"/docs/using-api/classify/list-classifiers"}}');var t=n(4848),r=n(8453);const d={sidebar_position:2},c="Create Classifier",l={},a=[{value:"API Endpoint",id:"api-endpoint",level:2},{value:"Headers",id:"headers",level:2},{value:"Request Body",id:"request-body",level:2},{value:"Example Implementation",id:"example-implementation",level:2},{value:"Using cURL",id:"using-curl",level:3},{value:"Using Python",id:"using-python",level:3},{value:"Response",id:"response",level:2},{value:"Successful Response (Status Code: 200)",id:"successful-response-status-code-200",level:3},{value:"Error Response (Status Codes: 400, 403, 500)",id:"error-response-status-codes-400-403-500",level:3},{value:"Response Fields Explained",id:"response-fields-explained",level:2},{value:"Next Steps",id:"next-steps",level:2}];function o(e){const s={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,r.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(s.header,{children:(0,t.jsx)(s.h1,{id:"create-classifier",children:"Create Classifier"})}),"\n",(0,t.jsxs)(s.p,{children:["A Classifier is a reusable set of categories you define once and apply to many documents. Once created, you can run it against any document using ",(0,t.jsx)(s.a,{href:"/docs/using-api/classify/run-classification",children:"Run Classification"})," \u2014 no need to resend your label definitions with each request."]}),"\n",(0,t.jsx)(s.p,{children:"Classifiers are best suited for automation pipelines where the same label set is applied to every incoming document (e.g. routing all inbound emails to the correct Workflow by document type)."}),"\n",(0,t.jsxs)(s.p,{children:["A Classifier can also map each label directly to an extraction template, so a single document can be classified ",(0,t.jsx)(s.strong,{children:"and"})," extracted in one call. See ",(0,t.jsx)(s.a,{href:"/docs/using-api/classify/classify-and-extract",children:"Classify + Extract in one call"}),"."]}),"\n",(0,t.jsx)(s.h2,{id:"api-endpoint",children:"API Endpoint"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{children:"POST https://api.documentpro.ai/v1/classifiers\n"})}),"\n",(0,t.jsx)(s.h2,{id:"headers",children:"Headers"}),"\n",(0,t.jsxs)(s.ul,{children:["\n",(0,t.jsxs)(s.li,{children:[(0,t.jsx)(s.code,{children:"x-api-key"})," (required): Your API key for authentication."]}),"\n",(0,t.jsxs)(s.li,{children:[(0,t.jsx)(s.code,{children:"Content-Type"}),": application/json"]}),"\n"]}),"\n",(0,t.jsx)(s.h2,{id:"request-body",children:"Request Body"}),"\n",(0,t.jsxs)(s.p,{children:["All fields below are sent ",(0,t.jsx)(s.strong,{children:"flat"})," in the request body (not nested under a ",(0,t.jsx)(s.code,{children:"configs"})," object). ",(0,t.jsx)(s.code,{children:"name"})," and ",(0,t.jsx)(s.code,{children:"classes"})," are required; everything else is optional."]}),"\n",(0,t.jsxs)(s.table,{children:[(0,t.jsx)(s.thead,{children:(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.th,{children:"Field"}),(0,t.jsx)(s.th,{children:"Type"}),(0,t.jsx)(s.th,{children:"Required"}),(0,t.jsx)(s.th,{children:"Description"})]})}),(0,t.jsxs)(s.tbody,{children:[(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"name"})}),(0,t.jsx)(s.td,{children:"string"}),(0,t.jsx)(s.td,{children:"Yes"}),(0,t.jsxs)(s.td,{children:["A descriptive name for this classifier (e.g. ",(0,t.jsx)(s.code,{children:'"Document Type Router"'}),")."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"classes"})}),(0,t.jsx)(s.td,{children:"array"}),(0,t.jsx)(s.td,{children:"Yes"}),(0,t.jsxs)(s.td,{children:["List of category objects. Each must have ",(0,t.jsx)(s.code,{children:"label"})," and ",(0,t.jsx)(s.code,{children:"description"}),", and may optionally include a ",(0,t.jsx)(s.code,{children:"template_id"}),". Minimum 2."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"default_template_id"})}),(0,t.jsx)(s.td,{children:"string"}),(0,t.jsx)(s.td,{children:"No"}),(0,t.jsxs)(s.td,{children:["Fallback extraction template used when the winning label has no ",(0,t.jsx)(s.code,{children:"template_id"})," mapped, or its confidence is below ",(0,t.jsx)(s.code,{children:"min_confidence"}),". Used by ",(0,t.jsx)(s.a,{href:"/docs/using-api/classify/classify-and-extract",children:"Classify + Extract"}),"."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"min_confidence"})}),(0,t.jsx)(s.td,{children:"number (0.0\u20131.0)"}),(0,t.jsx)(s.td,{children:"No"}),(0,t.jsxs)(s.td,{children:["If the winning label's confidence is below this threshold, routing falls back to ",(0,t.jsx)(s.code,{children:"default_template_id"}),". Only relevant when using this classifier with ",(0,t.jsx)(s.code,{children:"classifier_id"})," on an extract."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"classifier_t
1ype"})}),(0,t.jsx)(s.td,{children:"string"}),(0,t.jsx)(s.td,{children:"No"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.code,{children:'"document"'})," (default) classifies the whole document as one unit."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"query_model"})}),(0,t.jsx)(s.td,{children:"string"}),(0,t.jsx)(s.td,{children:"No"}),(0,t.jsxs)(s.td,{children:["AI model to use. Options: ",(0,t.jsx)(s.code,{children:'"gpt-4o-mini"'})," (default), ",(0,t.jsx)(s.code,{children:'"gpt-4o"'}),". Must be a supported (non-fine-tuned) model \u2014 invalid values return ",(0,t.jsx)(s.code,{children:"400"}),"."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"use_ocr"})}),(0,t.jsx)(s.td,{children:"boolean"}),(0,t.jsx)(s.td,{children:"No"}),(0,t.jsxs)(s.td,{children:["Defaults to ",(0,t.jsx)(s.code,{children:"true"}),"."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"page_range"})}),(0,t.jsx)(s.td,{children:"string"}),(0,t.jsx)(s.td,{children:"No"}),(0,t.jsxs)(s.td,{children:["Pages to use for classification (e.g. ",(0,t.jsx)(s.code,{children:'"1-2"'}),"). Defaults to all pages."]})]})]})]}),"\n",(0,t.jsxs)(s.p,{children:["Each item in ",(0,t.jsx)(s.code,{children:"classes"})," must have:"]}),"\n",(0,t.jsxs)(s.ul,{children:["\n",(0,t.jsxs)(s.li,{children:[(0,t.jsx)(s.code,{children:"label"})," (string): The category name returned when the document matches (e.g. ",(0,t.jsx)(s.code,{children:'"invoice"'}),")."]}),"\n",(0,t.jsxs)(s.li,{children:[(0,t.jsx)(s.code,{children:"description"})," (string): Plain-English description to help the AI distinguish this category."]}),"\n",(0,t.jsxs)(s.li,{children:[(0,t.jsx)(s.code,{children:"template_id"})," (string, optional): The extraction template to run when a document is classified as this label. Only used when this classifier is passed as ",(0,t.jsx)(s.code,{children:"classifier_id"})," to an extract \u2014 see ",(0,t.jsx)(s.a,{href:"/docs/using-api/classify/classify-and-extract",children:"Classify + Extract in one call"}),"."]}),"\n"]}),"\n",(0,t.jsx)(s.h2,{id:"example-implementation",children:"Example Implementation"}),"\n",(0,t.jsx)(s.h3,{id:"using-curl",children:"Using cURL"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-bash",children:'curl --location \'https://api.documentpro.ai/v1/classifiers\' \\\n--header \'x-api-key: YOUR_API_KEY\' \\\n--header \'Content-Type: application/json\' \\\n--data \'{\n "name": "Document Type Router",\n "classifier_type": "document",\n "classes": [\n { "label": "invoice", "description": "A document requesting payment for goods or services rendered", "template_id": "tmpl_invoice" },\n { "label": "purchase_order", "description": "A buyer-issued document authorizing a purchase from a supplier", "template_id": "tmpl_po" },\n { "label": "contract", "description": "A legally binding agreement between two or more parties" },\n { "label": "other", "description": "Any document that does not fit the above categories" }\n ],\n "default_template_id": "tmpl_generic",\n "min_confidence": 0.6,\n "query_model": "gpt-4o-mini",\n "page_range": "1-2"\n}\'\n'})}),"\n",(0,t.jsx)(s.h3,{id:"using-python",children:"Using Python"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-python",children:'import requests\nimport json\n\nurl = "https://api.documentpro.ai/v1/classifiers"\n\nheaders = {\n \'x-api-key\': \'YOUR_API_KEY\',\n \'Content-Type\': \'application/json\'\n}\n\npayload = {\n "name": "Document Type Router",\n "classifier_type": "document",\n "classes": [\n { "label": "invoice", "description": "A document requesting payment for goods or services rendered", "template_id": "tmpl_invoice" },\n { "label": "purchase_order", "description": "A buyer-issued document authorizing a purchase from a supplier", "template_id": "tmpl_po" },\n { "label": "contract", "description": "A legally binding agreement between two or more parties" },\n { "label": "other", "description": "Any document that does not fit the above categories" }\n ],\n "default_template_id": "tmpl_generic",\n "min_confidence": 0.6,\n "query_model": "gpt-4o-mini",\n "page_range": "1-2"\n}\n\nresponse = requests.post(url, headers=headers, data=json.dumps(payload))\n\nif response.status_code == 200:\n result = response.json()\n print(f"Classifier created. ID: {result[\'classifier_id\']}")\nelse:\n print(\'Failed to create classifier\')\n print(response.text)\n'})}),"\n",(0,t.jsx)(s.h2,{id:"response",children:"Response"}
1),"\n",(0,t.jsx)(s.h3,{id:"successful-response-status-code-200",children:"Successful Response (Status Code: 200)"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-json",children:'{\n "classifier_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",\n "name": "Document Type Router",\n "user_id": "4449b25a-9bba-4de4-be67-c06233d2f305",\n "configs": {\n "classifier_type": "document",\n "classes": [\n { "label": "invoice", "description": "A document requesting payment for goods or services rendered", "template_id": "tmpl_invoice" },\n { "label": "purchase_order", "description": "A buyer-issued document authorizing a purchase from a supplier", "template_id": "tmpl_po" },\n { "label": "contract", "description": "A legally binding agreement between two or more parties" },\n { "label": "other", "description": "Any document that does not fit the above categories" }\n ],\n "default_template_id": "tmpl_generic",\n "min_confidence": 0.6,\n "query_model": "gpt-4o-mini",\n "page_range": "1-2",\n "use_ocr": true\n },\n "created_at": "2024-07-25T14:16:44.540197",\n "updated_at": "2024-07-25T14:16:44.540223"\n}\n'})}),"\n",(0,t.jsx)(s.h3,{id:"error-response-status-codes-400-403-500",children:"Error Response (Status Codes: 400, 403, 500)"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-json",children:'{\n "success": false,\n "error": "error_code",\n "message": "descriptive error message"\n}\n'})}),"\n",(0,t.jsx)(s.h2,{id:"response-fields-explained",children:"Response Fields Explained"}),"\n",(0,t.jsxs)(s.ul,{children:["\n",(0,t.jsxs)(s.li,{children:[(0,t.jsx)(s.code,{children:"classifier_id"}),": The unique ID for this classifier. Use it to ",(0,t.jsx)(s.a,{href:"/docs/using-api/classify/run-classification",children:"run classifications"}),", ",(0,t.jsx)(s.a,{href:"/docs/using-api/classify/update-classifier",children:"update"}),", or ",(0,t.jsx)(s.a,{href:"/docs/using-api/classify/delete-classifier",children:"delete"})," this classifier."]}),"\n",(0,t.jsxs)(s.li,{children:[(0,t.jsx)(s.code,{children:"name"}),": The name you provided."]}),"\n",(0,t.jsxs)(s.li,{children:[(0,t.jsx)(s.code,{children:"configs"}),": The saved classification settings, including your full ",(0,t.jsx)(s.code,{children:"classes"})," list. Note that although the request body is flat, the response always nests these settings under ",(0,t.jsx)(s.code,{children:"configs"}),"."]}),"\n",(0,t.jsxs)(s.li,{children:[(0,t.jsx)(s.code,{children:"created_at"})," / ",(0,t.jsx)(s.code,{children:"updated_at"}),": UTC timestamps."]}),"\n"]}),"\n",(0,t.jsx)(s.admonition,{title:"Validation",type:"note",children:(0,t.jsxs)(s.p,{children:["An invalid ",(0,t.jsx)(s.code,{children:"query_model"})," returns ",(0,t.jsx)(s.code,{children:"400"}),". A ",(0,t.jsx)(s.code,{children:"min_confidence"})," outside the ",(0,t.jsx)(s.code,{children:"0.0\u20131.0"})," range returns ",(0,t.jsx)(s.code,{children:"400"}),"."]})}),"\n",(0,t.jsx)(s.h2,{id:"next-steps",children:"Next Steps"}),"\n",(0,t.jsxs)(s.ul,{children:["\n",(0,t.jsxs)(s.li,{children:[(0,t.jsx)(s.a,{href:"/docs/using-api/classify/run-classification",children:"Run Classification"})," using the ",(0,t.jsx)(s.code,{children:"classifier_id"})," to classify documents."]}),"\n",(0,t.jsxs)(s.li,{children:[(0,t.jsx)(s.a,{href:"/docs/using-api/classify/list-classifiers",children:"List your Classifiers"})," to see all classifiers in your account."]}),"\n",(0,t.jsxs)(s.li,{children:[(0,t.jsx)(s.a,{href:"/docs/using-api/classify/update-classifier",children:"Update a Classifier"})," to modify the label set or settings."]}),"\n"]})]})}function h(e={}){const{wrapper:s}={...(0,r.R)(),...e.components};return s?(0,t.jsx)(s,{...e,children:(0,t.jsx)(o,{...e})}):o(e)}},8453:(e,s,n)=>{n.d(s,{R:()=>d,x:()=>c});var i=n(6540);const t={},r=i.createContext(t);function d(e){const s=i.useContext(r);return i.useMemo((function(){return"function"==typeof e?e(s):{...s,...e}}),[s,e])}function c(e){let s;return s=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:d(e.components),i.createElement(r.Provider,{value:s},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.