Classifying text in documents

Classify your input files into schema definitions for certain common document types or schemas for custom documents. By pre-processing the documents, the text in the classified document can be extracted more efficiently.

Before you use schema-based key-value pair extraction with your document, you can classify the document by defining multiple schemas in the text classification REST API request body. You can provide a combination of schemas for supported pre-defined document types or custom documents. By classifying the document in advance, the extraction process can be limited to the fields defined in the provided schema. If the key-value pair data in your document does not match a schema, the text classification API indicates that the document is not classified.

You can use the text classification REST API to classify an input file that is stored in your project as an asset.

Required permissions: To classify documents, you must have the Admin or Editor role in a project.
Required credentials: You must generate credentials to authenticate with watsonx.ai APIs. For details, see Generating a bearer token.

Before you begin

Your administrator must install a set of machine learning models that process documents. The ID for the set of required models is wdu.
Prepare your documents as follows before you add them to your project:
- Remove any password protection from your document.
- If your PDF document is digitally certified, convert your document to another file format, like DOC or DOCX.
Decide the parameters to include in your text classification request to fit your specific use case. For details, see Text classification parameters.

Procedure

Follow these high-level steps to classify a business document by using the REST API:

Add the file from which you want to classify to a storage asset. You can also specify the storage asset in which to store the results of the text extraction process.

You can use the following storage types:
Connected storage asset

Store your document as a connection asset in your project, and then reference the files in the API by a connection ID. Only connection assets that use the Access key and Secret key pair for credentials are supported. For details, see Adding files to reference from the API.

Container in a project or deployment space
To store your input documents in a container in a deployment space or project, upload your input file directly with the asset files API. For details, see Data & AI Common Core Software API documentation.

The input file are referenced in the API by the file path as follows:
```
"document_reference": {
  "type": "container",
  "location": {
    "path": "dummy_path/ibm-annual-report-2024-pt1_1-20-1.pdf"
  }
},
"results_reference": {
  "type": "container",
  "location": {
    "path": "dummy_path/results/"
  }
}
```
Use the Start a text classification request API method to start the classification process. For API request details, see the REST API request example.

Note the ID that is returned in the metadata.id field. You use this ID to check the status of your request later.
Use the Get the results of the request API method to check the status of your request.

Checking the status is the only way to find out whether the process failed for any reason.

When the status is completed, the results field contains the details of the document classification process results.

REST API request example

The following command submits a request to extract text from the retail_guidebook.pdf file stored in a Cloud Object Storage bucket in the project and saves the extracted results in the results_data folder.

curl -X POST \
  'https://cpd-<namespace-name>.apps.<OCP-domain>/ml/v1/text/classifications?version=2025-10-08' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJraWQiOi...'

The request body is as follows:

{
    "project_id": "e40e5895-ce4d-42a3-b699-8ac764b89a09",
    "document_reference": {
      "type": "connection_asset",
      "connection": {
        "id": "5c0cefce-da57-408b-b47d-58f7785de3ee"
      },
      "location": {
        "bucket":"my-cloud-object-storage-bucket",
        "file_name": "retail_guidebook.pdf"
      }
    },
    "parameters": {
      "languages": [
        "en"
      ],
      "ocr_mode": "enabled",
      "classification_mode": "exact",
      "semantic_config": {
        "schemas": [ {
           "document_type": "Auto_Insurance_Application",
           "document_description": "A California Personal Auto Application form used to collect information necessary for initiating or updating an auto insurance policy. It includes agency, applicant, carrier, and policy details such as contact information, address, policy number, and effective/expiration dates.",
           "additional_prompt_instructions": "Return phone numbers and policy numbers exactly as they appear in the document.",
           "fields": {
              "agency_name": {
                "default": "",
                "example": "Spring Insurance",
                "description": "Name of the insurance agency handling the auto application."
              },
              "applicant_name": {
                "default": "",
                "example": "John Smith",
                "description": "Full name of the person applying for auto insurance."
              },
              "applicant_address": {
                "default": "",
                "example": "245 W 52nd St, Apt 8B, New York, NY 10019",
                "description": "Mailing address of the applicant including street, apartment, city, state, and ZIP code."
              },
              "applicant_phone": {
                "default": "",
                "example": "(917) 555-2843",
                "description": "Phone number for contacting the applicant."
              },
              "applicant_email": {
                "default": "",
                "example": "john.smith@gmail.com",
                "description": "Email address of the applicant."
              },
              "carrier_name": {
                "default": "",
                "example": "Tower Insurance Company",
                "description": "Name of the insurance carrier providing the policy."
              },
              "policy_number": {
                "default": "",
                "example": "10",
                "description": "Unique identifier for the insurance policy."
              },
              "effective_date": {
                "default": "",
                "example": "2023-01-01",
                "description": "Date when the insurance policy becomes effective."
              },
              "expiration_date": {
                "default": "",
                "example": "2024-01-01",
                "description": "Date when the insurance policy expires."
              }
           }
        } ]
      }
    }
  }

From the response, you can find the classification results in the response from the results attribute:

"results": {
  "completed_at": "2025-10-08T09:05:42.880Z",
  "running_at": "2025-10-08T09:05:27.345Z",
  "status": "completed",
  "document_classified": "True",
  "document_type": "Auto_Insurance_Application"
}

What to do next

You can use the results of the text classification request to decide how to use the key-value pair schema definition to extract text from your document more efficiently. For details, see Text extraction.