Migration workflows
Migrating a reCAPTCHA recognition integration to easycaptcha
Migrating a reCAPTCHA recognition integration to easycaptcha. Follow practical setup steps and checks for your easycaptcha reCAPTCHA workflow.
By the easycaptcha team · Published

Identify whether your current integration requests image classification or a token. easycaptcha reCAPTCHA support provides recognition. Record instruction format, image encoding, grid names, selection indexes, and polling behavior before selecting a replacement endpoint.
Choose native or compatibility requests
The native API uses recaptcha_recognition and returns booleans. Compatibility adapters cover documented NopeCHA recognition, 2Captcha GridTask, and CapSolver ReCaptchaV2Classification formats. Use the matching compatibility hostname and review the adapter contract.
Run a small representative pilot
Include 3×3, 4×4, and replacement rounds in a controlled evaluation. Compare selection mapping, request counts, application completion, and errors. Do not assume a vendor-specific task ID or result format can be reused on another endpoint.
Audit what the existing integration actually consumes
Read the code immediately after the current service returns. If it expects a verification token, it cannot consume a boolean classification array without a different workflow. If it expects selected image indexes, document whether those indexes are zero-based, one-based, or wrapped in a vendor-specific object. The answer contract matters as much as the request.
Next, inventory how the client collects instructions and images. Some existing adapters accept raw base64 or legacy grid names that the native API does not. Write down these assumptions before changing a hostname. This gives the migration an explicit conversion boundary instead of scattering vendor-specific exceptions through capture, polling, and click handling.
Choose a contract and convert at one boundary
| Existing need | Migration consideration |
|---|---|
| Native image recognition | Use recaptcha_recognition and native snapshots |
| NopeCHA recognition | Review the documented recognition adapter |
2Captcha GridTask |
Review the matching JSON or legacy endpoint |
| CapSolver classification | Account for the documented direct solution response |
| Token submission | Not supported by this recognition contract |
Keep request preparation and result conversion together for the chosen contract. Compatibility endpoints translate documented formats, but that does not mean every operation from another vendor is supported. Use the compatibility documentation to establish the precise boundary before testing.
Pilot a complete replacement sequence
A single completed grid request proves little about the existing application’s dynamic handling. Include a full grid followed by nonadjacent replacements, an all-false dynamic answer, and a changed instruction while work is outstanding. Check that the integration stores the new service’s full task ID and applies each answer to its own snapshot.
Compare request counts and observed completion alongside latency. A migrated client that creates another task every time polling is slow can appear responsive while generating duplicate paid work. Simulate a creation timeout and a lookup timeout separately, then inspect what the client retries and whether it retains known task IDs.
Define rollout and rollback evidence
Start with a controlled cohort whose inputs and outcomes you can observe. Record the selected contract, release version, grid mode, round depth, task errors, and final workflow outcome. Keep unknown outcomes visible. Avoid claims of equivalent behavior based only on receiving a successful HTTP response from both endpoints.
Retain the old configuration until the pilot establishes that the new mapping and recovery paths work. If you roll back, route new work to the chosen integration while continuing to identify already submitted tasks by their original service and task ID. A task identifier is not portable simply because two APIs expose similarly named retrieval methods.
Document semantic differences in the migration handoff
A successful pilot should leave behind more than a new base URL. Document the selected endpoint contract, accepted grid names, image encoding, result envelope, index convention, and completion behavior. Include the error and retry rules that the existing client relied on. These details help the next maintainer understand why a conversion function exists and what must remain stable.
If the migration introduces a native boolean array where the old service returned selected indexes, convert at one boundary and retain the original positions while doing so. Test empty positive selections and sparse dynamic batches, because those cases reveal index-base and ordering assumptions that an all-positive sample hides.
Keep a short sanitized request and response fixture for each supported mode. The fixtures should contain no paid key and should label image placeholders clearly. They can serve as contract checks during later SDK or application updates without claiming to measure live recognition quality. The migration is reviewable when another engineer can follow those fixtures from original input through the new result mapping and recovery path.
Frequently asked questions
Can I migrate a reCAPTCHA token task to this recognition API?
No. Recognition returns selections and is not a replacement contract for token submission.
What should a migration pilot cover?
Test full grids, sparse replacements, changed instructions, response conversion, and separate creation versus retrieval timeouts.
Can task IDs move between service endpoints?
Do not assume they are portable. Preserve the original service and task identity and use the documented retrieval contract.