Integration concepts
How to read reCAPTCHA recognition boolean results
How to read reCAPTCHA recognition boolean results. Learn the inputs, limits, and result handling for easycaptcha reCAPTCHA recognition.
By the easycaptcha team · Published

The create response may report queued or running. Save task_id and retrieve that task until its status is completed or failed. A successful HTTP response can still contain a failed task; inspect status before accessing result.
Preserve row and image order
Full-grid booleans are arranged left to right, top to bottom. For a zero-based position i, the row is floor(i / columns) and the column is i modulo columns. Use three columns for imageselect and four for tileselect.
Handle dynamic arrays differently
A dynamic response follows image_data order rather than the position of every cell on screen. Store each submitted tile with its original cell position. Validate the result length against your submitted images before applying selections.
Translate a full-grid answer into positions
For a 3×3 grid, indexes zero through two describe the first row, three through five the second, and six through eight the third. For a 4×4 grid, the first row occupies indexes zero through three. The column count comes from the submitted grid mode, so hardcoding three columns will misplace selections for a valid sixteen-value answer.
For example, [true, false, false, false, true, false, false, false, false] selects the top-left and center cells in a 3×3 grid. Keep the unselected positions in the array until mapping is finished. Filtering out false values before calculating positions removes the information that makes each remaining true meaningful.
Map sparse replacement results explicitly
A dynamic batch containing images from cells with local indexes one, four, and seven can produce [false, true, false]. The positive selection belongs to cell four because it was the second submitted image. It does not belong to cell one, and the three-value response does not describe a three-cell slice at the top of the page.
Store the ordered cell list alongside the task ID instead of reconstructing it from the page after the response arrives. The page may have changed by then. If you cannot establish that the stored cell still contains the submitted image, treat the answer as stale and collect current inputs rather than clicking a plausible-looking position.
Validate the answer before applying it
A completed result should have the expected number of boolean entries: nine, sixteen, or the number of dynamic images you submitted. Check element types as well as length in an untyped integration. Strings such as "false" are truthy in some languages, so permissive coercion can turn a malformed response wrapper into incorrect positive selections.
An all-false answer is a legitimate classification result for the submitted images. It is different from a missing result, an empty array of unexpected length, or a failed task. Handle each case distinctly. That distinction makes logs and feedback useful because a recognition decision is no longer confused with an error parsing the task snapshot.
Keep output interpretation separate from acceptance
The boolean array answers an image question. It does not state whether the browser accepted the interaction, whether replacements finished loading, or whether the user’s form passed validation. Record those later outcomes only when your application observes them. This prevents API completion from inflating your end-to-end success metric.
For investigation, keep the task ID, expected array length, selected positions, and round identity. Avoid retaining complete challenge images in general analytics when a small mapping record will explain the issue. The success-rate guide shows how to report completed tasks, accepted challenges, and application completion as separate stages.
Keep recognition results distinct from transport wrappers
The completed native snapshot contains the boolean array in result. A compatibility API may place its output in a different envelope or use a vendor-specific selection representation. Validate the contract at the endpoint boundary before passing values into a shared mapper. Reading whichever field happens to exist can hide a migration error until a particular response shape appears.
Also distinguish an absent value from an explicit false. In an array of decisions, false preserves both a classification and its position. An absent element means the expected answer structure was not provided. Padding a short result with false values invents decisions the recognizer did not return; silently dropping extra values similarly conceals an inconsistency worth investigating.
For local debugging, print a compact mapping such as index, original cell position, and decision, with no image data or account keys. Compare it against a fixture with positives on different rows and in nonadjacent dynamic cells. This makes ordering defects visible without needing a live website to accept or reject repeated attempts.
Frequently asked questions
What does false mean in a recognition result?
It means leave that submitted image unselected; it is not a task failure.
How are full-grid selections ordered?
Read left to right, top to bottom, using three columns for imageselect and four for tileselect.
Is an all-false result a failed task?
No. It is a valid set of negative image decisions when the task completed and the result has the expected shape.