> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scaledown.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Pull structured data from unstructured text using a schema you define in plain English.

## What it does

The `/extract` endpoint runs Named Entity Recognition (NER) over arbitrary text - but instead of a fixed set of entity types (person, place, organization), you define exactly what you're looking for in plain English. The model interprets your descriptions and finds matching spans in the text, returning each one with a confidence score, character offsets, and surrounding context.

This makes it practical to extract domain-specific entities that generic NER models don't support: contract parties, product SKUs, medical terms, financial figures, custom identifiers, or anything else you can describe.

## When to use it

**You need structured data from unstructured text.** If your pipeline involves parsing documents, emails, web pages, or transcripts to pull out specific values, Extract replaces brittle regex patterns and rigid NLP pipelines with a flexible, description-driven approach.

**Your entity types don't fit standard NER.** Off-the-shelf NER handles names, locations, and organizations. Extract handles whatever you define - lease terms, part numbers, clinical findings, competitor mentions, or any other domain-specific concept.

**You need confidence scores.** Extract returns a confidence score for every result. You can set per-entity thresholds to filter out low-confidence hits, or use the scores to route extractions to a human review queue.

**You want context alongside every result.** Every extracted span comes with 500 characters of surrounding text on each side, so you can verify the extraction in context without going back to the source document.

**Your source is an image or scan, not text.** Extract has built-in OCR (AWS Textract). Send a base64-encoded photo, scan, or PDF in the `document` field and it recovers the text before extraction - so receipts, invoices, IDs, business cards, and scanned forms work without a separate OCR step. See [Extracting from an image (OCR)](/api-reference/extract#extracting-from-an-image-ocr).

**Some of your fields are decisions, not spans.** Booleans and small categories - "is this account past due?", "electric or gas?" - have no verbatim span to pull. Mark those keys with a `labels` list and Extract routes them to the classification model, which is purpose-built for categorical decisions, while extracting the rest as normal. Each label can be a plain string, or an object with a `rubric` describing when it applies - rubrics meaningfully improve accuracy. See [Classification keys](/api-reference/extract#classification-keys).

## Common use cases

| Use case                        | Example entities                                              |
| ------------------------------- | ------------------------------------------------------------- |
| Contract analysis               | Parties, effective dates, termination clauses, governing law  |
| Resume parsing                  | Name, email, skills, companies, job titles, education         |
| Medical records                 | Diagnoses, medications, dosages, lab values, dates of service |
| Financial documents             | Revenue figures, dates, entities, regulatory references       |
| Customer support tickets        | Product names, error codes, account identifiers               |
| News / media monitoring         | People, organizations, locations, quoted statements           |
| E-commerce                      | Product names, prices, SKUs, brands, specifications           |
| Scanned images & receipts (OCR) | Merchant, total, date, line items, tax from a photo or scan   |

## How it fits into your workflow

Extract sits between your document ingestion step and whatever system consumes structured data - a database, a downstream process, or a human review interface.

```
[Ingest document] → [POST /extract] → [Structured entity list] → [Database / downstream system]
```

Each entity in the response includes character offsets (`start`, `end`), so you can highlight or link back to the exact location in the source document.

## Tips for better results

The entity name and description are treated as part of the model's prompt - how you phrase them directly affects extraction quality.

* **Use lowercase or Title Case labels.** The model was trained with lowercase entity names. `person`, `company`, and `date` work better than `PERSON` or `DATE`.
* **Be specific, and test synonyms.** `person` and `full name` find slightly different things. If results are missing or noisy, try rephrasing the label name.
* **Labels can be descriptive phrases.** `"capital city and population center"` is a perfectly valid label name and will outperform a bare `"city"` when you need that distinction.
* **Descriptions can be instructions.** Write `"Find the first and last name of the person in the text"` rather than just `"Name"`. Full instructions consistently outperform short noun phrases.
* **Don't mix overlapping granularities.** Including both `"location"` and `"city"` in the same call forces the model to split results between them unpredictably. Pick one level of granularity per concept.

## Compared to traditional NER

|                              | Traditional NER                    | ScaleDown Extract                                 |
| ---------------------------- | ---------------------------------- | ------------------------------------------------- |
| Entity types                 | Fixed (person, place, org, ...)    | You define them in plain English                  |
| Domain specificity           | General-purpose                    | Works for any domain                              |
| Confidence scores            | Varies by model                    | Always included                                   |
| Per-entity thresholds        | Not typically supported            | Supported                                         |
| Context window               | Usually sentence-level             | Full document                                     |
| Structured / nested output   | Not supported                      | Supported via nested object and array schemas     |
| Categorical / boolean fields | Extracted as text (lower accuracy) | Routed to a purpose-built classifier via `labels` |
| Document / image input       | Not supported                      | Supported via base64 + OCR                        |