The get OCR results endpoint allows you to check the processing status and retrieve extracted data for a document that has been submitted for OCR processing. This endpoint should be called after initiating OCR processing with the Start OCR endpoint.

The response includes the current processing status and, when processing is complete, the extracted structured data from the document.

Endpoint

Method	Url
`GET`	`/v1.0/ocr/results/{document_id}`

Path Parameters

document_id

•

string

required

The unique identifier of the document for which to retrieve OCR results. This should be the same document ID used when starting OCR processing.

Sample Request

bashCopied
1curl -X GET 'https://api.worklayer.com/v1.0/ocr/results/1e910673-8e3a-4f82-a415-5833abb7a0f9' \
2  -H 'Authorization: Bearer {token}'

Response

The response contains the current processing status and extracted data when available.

status

•

string

The current status of OCR processing. Possible values:

NOT_FOUND - No OCR processing found for this document
IN_PROGRESS - OCR processing is currently running
FAILED - Processing encountered an error
COMPLETED - Processing finished successfully

extracted_data

•

array

An array of extracted fields objects. Only present when status is COMPLETED. Each object contains type-specific fields based on the document type.

estimated_refund

•

object

An object containing estimated refund amounts. This field is null until refund information has been extracted. See the Estimated Refund Properties section below.

Sample Response (In Progress)

jsonCopied
1{
2  "status": "IN_PROGRESS",
3  "extracted_data": null,
4  "estimated_refund": null
5}

Sample Response (Completed)

jsonCopied
1{
2  "status": "COMPLETED",
3  "extracted_data": [
4    {
5      "id": "e2d446e9-fd59-49fb-9c41-74dc2978ff7b",
6      "type": "1040",
7      "year": 2023,
8      "adjusted_gross_income": 88016,
9      "total_tax_liability": 6439,
10      "amount_owed": null,
11      "overpayment": 3000
12    },
13    {
14      "id": "790c629a-c945-4acc-96f8-84e866652323",
15      "type": "STATE_1040",
16      "year": 2023,
17      "state_name": "VA",
18      "adjusted_gross_income": 88016,
19      "total_tax_liability": 3723
20    }
21  ],
22  "estimated_refund": {
23    "federal_amount": 2450.0,
24    "amount_by_state": [
25      {
26        "state": "VA",
27        "amount": 375.5
28      }
29    ]
30  }
31}

Extracted Data Models

Federal 1040 Return

When processing federal tax returns, the extracted data includes:

type

•

string

Always "1040" for federal tax returns.

•

string

Unique identifier for this OCR result.

year

•

number

The tax year of the return.

adjusted_gross_income

•

number

The adjusted gross income from the tax return.

total_tax_liability

•

number

The total tax liability amount.

amount_owed

•

number

The amount owed, null otherwise.

overpayment

•

number

The amount overpaid, null otherwise.

State 1040 Return

When processing state tax returns, the extracted data includes:

type

•

string

Always "STATE_1040" for state tax returns.

•

string

Unique identifier for this OCR result.

year

•

number

The tax year of the return.

state_name

•

string

The two-letter US state abbreviation code (e.g., CA for California, NY for New York). See the complete list of state codes below.

adjusted_gross_income

•

number

The adjusted gross income from the state return.

total_tax_liability

•

number

The state tax liability amount.

US State Codes Reference

The state_name field in state tax return OCR results uses standard two-letter US state abbreviation codes:

Code	State	Code	State	Code	State	Code	State	Code	State
`AL`	Alabama	`CT`	Connecticut	`IA`	Iowa	`MN`	Minnesota	`NY`	New York
`AK`	Alaska	`DE`	Delaware	`KS`	Kansas	`MS`	Mississippi	`NC`	North Carolina
`AZ`	Arizona	`FL`	Florida	`KY`	Kentucky	`MO`	Missouri	`ND`	North Dakota
`AR`	Arkansas	`GA`	Georgia	`LA`	Louisiana	`MT`	Montana	`OH`	Ohio
`CA`	California	`HI`	Hawaii	`ME`	Maine	`NE`	Nebraska	`OK`	Oklahoma
`CO`	Colorado	`ID`	Idaho	`MD`	Maryland	`NV`	Nevada	`OR`	Oregon
`PA`	Pennsylvania	`IL`	Illinois	`MA`	Massachusetts	`NH`	New Hampshire	`WY`	Wyoming
`RI`	Rhode Island	`IN`	Indiana	`MI`	Michigan	`NJ`	New Jersey	`WV`	West Virginia
`SC`	South Carolina	`TX`	Texas	`UT`	Utah	`NM`	New Mexico	`WI`	Wisconsin
`SD`	South Dakota	`TN`	Tennessee	`VT`	Vermont	`VA`	Virginia	`WA`	Washington
`DC`	District of Columbia

Estimated Refund Properties

The estimated_refund object contains refund information.

federal_amount

•

number

The estimated federal refund amount as a decimal number, or null if no federal refund was extracted. A negative value indicates an amount owed.

amount_by_state

•

array

An array of state refund amounts. Each entry contains: - state - The two-letter US state abbreviation code (e.g., "CA", "NY"). - amount - The estimated refund amount for that state as a decimal number. A negative value indicates an amount owed.

Sample Estimated Refund

jsonCopied
1{
2  "federal_amount": 2450.0,
3  "amount_by_state": [
4    {
5      "state": "CA",
6      "amount": 375.5
7    }
8  ]
9}

Errors

Error Responses

The API returns standard HTTP status codes with descriptive error messages:

Status Code	Error Type	Description
`400`	Bad Request	Invalid document ID format
`401`	Unauthorized	Missing or invalid bearer token
`403`	Forbidden	User lacks permission
`404`	Not Found	Document not found, workspace not found, or OCR results not found

Last updated on March 23, 2026