---
updatedAt: 2025-11-24T20:55:14.000Z
agentTools:
  projectIndex: https://docs.sensible.so/llms.txt
---

# Classify document by type


Classify a document into one of the document types you defined in your Sensible account. For more information, see [Classifying documents by type](doc:classify).
To retrieve document's classification, poll the `download_link` in this endpoint's response until it returns a non-error response.

Use this endpoint:

 - In an extraction workflow. For example, determine which documents to extract prior to calling a Sensible extraction endpoint.
 - Outside an extraction workflow. For example, determine where to route each document or to label each document in a system of record.

To post the document bytes, specify the non-encoded document bytes as the entire request body,and specify the `Content-Type` header, for example,"application/pdf" or "image/jpeg".

For supported file size and types, see [Supported file types](doc:file-types).


# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://api.sensible.so/v0",
      "description": "Production server (uses live data)"
    }
  ],
  "info": {
    "title": "Classification",
    "version": "0.0.0",
    "license": {
      "name": "Sensible API",
      "url": "https://www.TBD.org/licenses/LICENSE-2.0.html"
    },
    "description": "Classify documents by type with the Sensible API."
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Document",
      "description": "Classify documents by type"
    }
  ],
  "paths": {
    "/classify/async": {
      "post": {
        "operationId": "classify-document",
        "summary": "Classify document by type",
        "description": "Classify a document into one of the document types you defined in your Sensible account. For more information, see [Classifying documents by type](https://docs.sensible.so/docs/classify).\nTo retrieve document's classification, poll the `download_link` in this endpoint's response until it returns a non-error response.\n\nUse this endpoint:\n\n - In an extraction workflow. For example, determine which documents to extract prior to calling a Sensible extraction endpoint.\n - Outside an extraction workflow. For example, determine where to route each document or to label each document in a system of record.\n\nTo post the document bytes, specify the non-encoded document bytes as the entire request body,and specify the `Content-Type` header, for example,\"application/pdf\" or \"image/jpeg\".\n\nFor supported file size and types, see [Supported file types](https://docs.sensible.so/docs/file-types).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/document_types"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/SupportedFileTypes"
        },
        "tags": [
          "Document"
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClassifyAsyncSingleResponse"
                }
              }
            },
            "description": "Download link for the classification response. Poll the link until it returns a non-error response.\n"
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "415": {
            "$ref": "#/components/responses/415"
          },
          "429": {
            "$ref": "#/components/responses/429"
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "400": {
        "description": "Bad Request",
        "content": {
          "text/plain": {
            "schema": {
              "title": "Bad Request",
              "type": "string",
              "example": "Messages related to the file content type, to reading or OCRing the file, or to classifying the document."
            }
          }
        }
      },
      "401": {
        "description": "Not authorized",
        "content": {
          "text/plain": {
            "schema": {
              "title": "Unauthorized",
              "type": "string",
              "example": "Unauthorized"
            }
          }
        }
      },
      "415": {
        "description": "Unsupported Media Type",
        "content": {
          "text/plain": {
            "schema": {
              "title": "Unsupported Media Type",
              "type": "string",
              "example": "Messages related to the file format of the document."
            }
          }
        }
      },
      "429": {
        "description": "Too Many Requests",
        "content": {
          "text/plain": {
            "schema": {
              "title": "Too Many Requests",
              "type": "string",
              "example": "One of the following error messages - Attempt limit exceeded, please retry after some time. Free accounts are limited to 150 API calls per month. Please upgrade your account to make additional calls. Pro accounts are limited to 5,000 API calls per month. Please upgrade your account to make additional calls."
            }
          }
        }
      },
      "500": {
        "description": "Internal Server Error",
        "content": {
          "text/plain": {
            "schema": {
              "title": "Sensible encountered an unknown error",
              "type": "string",
              "example": "Sensible encountered an unknown error"
            }
          }
        }
      }
    },
    "parameters": {
      "document_types": {
        "name": "document_types",
        "in": "query",
        "description": "Comma-delimited list of document types Sensible uses to classify the document.  If you don't specify this, Sensible uses all the document types you define in your account.",
        "schema": {
          "type": "string"
        },
        "example": "1040s,pay_stubs,bank_statements"
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Sensible uses API keys to authenticate requests. Keep your API keys secure and do not share them publicly accessible areas such as GitHub, client-side code, etc. Authentication to the API is performed via Bearer Authentication. Provide your API key as the bearer auth value."
      }
    },
    "requestBodies": {
      "SupportedFileTypes": {
        "description": "Supported [file types](https://docs.sensible.so/docs/file-types).",
        "required": true,
        "content": {
          "application/pdf": {
            "schema": {
              "$ref": "#/components/schemas/BinaryDocument"
            }
          },
          "image/jpeg": {
            "schema": {
              "$ref": "#/components/schemas/BinaryDocument"
            }
          },
          "image/png": {
            "schema": {
              "$ref": "#/components/schemas/BinaryDocument"
            }
          },
          "image/tiff": {
            "schema": {
              "$ref": "#/components/schemas/BinaryDocument"
            }
          },
          "application/vnd.openxmlformats-officedocument.wordprocessingml.document": {
            "schema": {
              "$ref": "#/components/schemas/BinaryDocument"
            }
          },
          "application/msword": {
            "schema": {
              "$ref": "#/components/schemas/BinaryDocument"
            }
          },
          "text/csv": {
            "schema": {
              "$ref": "#/components/schemas/BinaryDocument"
            }
          },
          "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
            "schema": {
              "$ref": "#/components/schemas/BinaryDocument"
            }
          },
          "application/vnd.ms-excel": {
            "schema": {
              "$ref": "#/components/schemas/BinaryDocument"
            }
          },
          "application/vnd.ms-excel.sheet.macroenabled.12": {
            "schema": {
              "$ref": "#/components/schemas/BinaryDocument"
            }
          }
        }
      }
    },
    "schemas": {
      "ClassifyAsyncSingleResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID for this classification response."
          },
          "content_type": {
            "type": "string",
            "description": "File format of the document for which you requested classification."
          },
          "download_link": {
            "description": "Poll until the download URL returns a non-error response. Links to a JSON download that contains the same response as from the synchronous Classify endpoint request.\n",
            "type": "string",
            "format": "url"
          }
        },
        "example": {
          "id": "49f844ba-4429-4974-919d-2f1bdfa95f7c",
          "content_type": "application/pdf",
          "download_link": "https://sensible-so-document-type-bucket-dev-us-west-2.s3.us-west-2.amazonaws.com/c024cd1c-5f33-4a82-b2ea-2c807e44988b/CLASSIFICATION/49f844ba-4429-4974-919d-2f1bdfa95f7c.json?AWSAccessKeyId=REST_REDACTED"
        }
      },
      "BinaryDocument": {
        "type": "string",
        "format": "binary",
        "description": "non-encoded document bytes as the entire request body"
      }
    }
  }
}
```