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

Copied
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.

Sample Response (In Progress)

Copied
1{
2  "status": "IN_PROGRESS",
3  "extracted_data": null
4}

Sample Response (Completed)

Copied
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    },
11    {
12      "id": "790c629a-c945-4acc-96f8-84e866652323",
13      "type": "STATE_1040",
14      "year": 2023,
15      "state_name": "VA",
16      "adjusted_gross_income": 88016,
17      "total_tax_liability": 3723
18    }
19  ]
20}

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.

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

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 August 15, 2025