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

# Contract Scanning

> Extract assignment details from contracts and job ad screenshots using Claude AI.

TaxHomeBase uses Anthropic's Claude API to extract details from staffing agency contracts and job board screenshots. Upload a document or screenshot, and Claude extracts the relevant fields automatically.

## Contract Scanning (Assignments)

The "Scan Contract" button on the assignment form extracts up to 12 fields from formal staffing agency contracts.

<Steps>
  <Step title="Open the assignment form in create mode">
    The "Scan Contract" button is only available when creating a new assignment (not editing). The button is hidden if the server doesn't have an Anthropic API key configured.
  </Step>

  <Step title="Upload the contract">
    * Supported formats: PDF, JPEG, PNG
    * Maximum file size: 10MB
    * The file is uploaded to S3 via a presigned URL
  </Step>

  <Step title="Claude extracts the data">
    Claude reads the contract and extracts:

    | Field                | Description                        |
    | -------------------- | ---------------------------------- |
    | **Facility**         | Hospital or facility name          |
    | **Location**         | City                               |
    | **State**            | 2-letter state code                |
    | **Agency**           | Staffing agency name               |
    | **Start Date**       | Contract start date                |
    | **End Date**         | Contract end date                  |
    | **Base Pay**         | Weekly pre-tax base pay (in cents) |
    | **Housing Stipend**  | Weekly housing stipend (in cents)  |
    | **M\&IE Stipend**    | Weekly meals stipend (in cents)    |
    | **Sign-On Bonus**    | One-time bonus (in cents)          |
    | **Completion Bonus** | End-of-contract bonus (in cents)   |
    | **Referral Bonus**   | Referral bonus (in cents)          |
  </Step>

  <Step title="Review auto-filled fields">
    Only empty fields are populated. Review the extracted data and adjust as needed — contracts vary widely in format, and some fields may not be present in every contract.
  </Step>
</Steps>

<Frame caption="Claude extracts facility, location, dates, pay rates, and stipends from the contract PDF.">
  <img src="https://mintcdn.com/stipendguard/rYTODjwsgR5TPzB9/images/guides/assignment-scan.png?fit=max&auto=format&n=rYTODjwsgR5TPzB9&q=85&s=e713bc72b61ed3b5d67855e9bc0a4274" alt="Assignment form with all 12 fields auto-filled from a scanned staffing agency contract" style={{ maxWidth: '300px' }} width="786" height="1760" data-path="images/guides/assignment-scan.png" />
</Frame>

## Job Ad Scanning (Compare)

The "Scan Job Ad" button on the Compare page's custom contract form extracts details from job board screenshots (Vivian, AMN, Aya, Medical Solutions, etc.).

<Steps>
  <Step title="Select a custom contract slot">
    On the Compare page, select "+ Custom contract" in either slot. The "Scan Job Ad" button appears at the top of the form when an Anthropic API key is configured.
  </Step>

  <Step title="Upload a screenshot">
    * Supported formats: JPEG, PNG (screenshots only, no PDF)
    * Maximum file size: 10MB
    * Take a screenshot of the job ad from any staffing site or app
  </Step>

  <Step title="Claude extracts the data">
    Claude reads the job ad and extracts:

    | Field               | Description                                  |
    | ------------------- | -------------------------------------------- |
    | **Facility**        | Hospital or facility name                    |
    | **Location**        | City, state                                  |
    | **State**           | 2-letter state code                          |
    | **Agency**          | Staffing company name                        |
    | **Weekly Gross**    | Total weekly pay (midpoint if a range)       |
    | **Base Pay**        | Weekly taxable base if broken out separately |
    | **Housing Stipend** | Weekly housing if broken out separately      |
    | **M\&IE Stipend**   | Weekly M\&IE if broken out separately        |
    | **Bonuses**         | Sign-on, completion, referral                |
    | **Weeks**           | Contract duration                            |
    | **Hours/Week**      | Scheduled hours                              |
    | **Shift**           | Day, night, or rotating                      |
    | **Benefits**        | Weekly benefits value                        |
    | **ZIP Code**        | Facility ZIP if visible                      |
  </Step>

  <Step title="Review auto-filled fields">
    Only empty fields are populated. If the job ad shows a blended weekly pay range with no stipend breakdown (which is common), the midpoint is entered as base pay and an info note appears:

    > Only total weekly pay found — entered as base pay. Adjust the housing and M\&IE split if known.

    You can then manually split the amount between base pay, housing, and M\&IE if you know the breakdown.
  </Step>
</Steps>

<Info>
  Job ads from sites like Vivian typically show a blended weekly pay range (e.g., "$2,411–$2,560/wk") without separating taxable base from tax-free stipends. The scanner handles this by using the midpoint as base pay, which you can adjust once you have the full breakdown from the agency.
</Info>

## Pay Rate Conversion

Both scanners automatically convert pay rates expressed in different formats:

| Contract Format | Conversion                            |
| --------------- | ------------------------------------- |
| Hourly rate     | × hours/week (or 36 if not specified) |
| Daily rate      | × 7 days                              |
| Monthly rate    | ÷ 4.33 weeks                          |
| Pay range       | Midpoint of range                     |
| Dollar amounts  | × 100 (to cents)                      |

## Contract Storage

Uploaded contracts (from Assignments) are saved with the assignment:

* **contract\_s3\_key** stored in the database
* "View Contract" button on the expanded assignment card
* Opens via presigned S3 download URL in a new tab

<Tip>
  Job ad screenshots uploaded via Compare are stored in S3 but not linked to a saved record. They are used only for the extraction step.
</Tip>

## Feature Availability

Both scanning features require the optional `ANTHROPIC_API_KEY` environment variable:

* **Key configured**: Scan buttons visible, `GET /contracts/status` returns `{ available: true }`
* **Key not configured**: Scan buttons hidden, features gracefully disabled
* The rest of TaxHomeBase works fully without it

## Error Handling

Step-specific errors with retry:

* **Presign failure** — Problem generating the upload URL
* **Upload failure** — Problem uploading to S3
* **Claude extraction failure** — Problem parsing the document (e.g., unreadable format, missing data)

Each step shows a distinct error message with an inline retry button.