Skip to main content
An Auto Apply integration is one loop with two blocking calls:
Your backend saves the application ID and supplies answers the candidate approved, or answers generated under their AI acknowledgement. Blocking calls can return 202 before work finishes, so recovery is part of the loop. No inbound webhook is needed (Local development). Start with the first-request example. All paths are relative to https://connect.jobo.world and need the X-Api-Key header. The samples read $JOBO_API_KEY. Sandbox applications are visible only to sandbox keys, so set it to a sandbox key while you develop.

1. Create blocks until the fields arrive

POST /api/auto-apply/applications holds the connection for up to 90 seconds while Jobo validates the target, opens the form, and extracts its fields. A ready response has status: "awaiting_answers" and current_step. This one is abbreviated; your field IDs and deadlines will differ:
A form Jobo cannot complete (login wall, CAPTCHA, unsupported field) comes back from the same call as status: "failed" with a failure code. Set your HTTP client timeout above 120 seconds. After 90 seconds the server answers 202 with a snapshot; see Recovery.

2. Submit and validate answers

POST /api/auto-apply/applications/{id}/answers takes the complete answer snapshot for the current step. For a step with first_name and email:
Save the body as answers.json, set APPLICATION_ID, and send it from your backend:
Use your step’s real field IDs; this body does not fit every sandbox scenario. Jobo checks every answer against the step’s typed fields before touching the employer’s form. A wrong type, an unknown option, or a missing required field returns 400 validation_failed at once, with per-field errors:
A validation failure neither advances the form nor uses an ATS correction round. Fix the answers and send them again. correction_round is optional, but always send the current value: a stale one gets 409 stale_correction_round instead of being accepted for another round. Once the answers are accepted, Jobo fills the page and advances the form. You never send a separate submit: intermediate pages continue and the final page submits automatically. The call then blocks until one of three outcomes: If processing outlasts the wait, the endpoint returns 202. That is neither a completed step nor a successful submission.

3. Correction rounds

When the employer’s ATS rejects a value after filling, the same step comes back with correction_round incremented and command_errors listing what was rejected:
Answer it like any other step. After 3 failed rounds the application fails with correction_limit_exceeded.

4. Deadlines

While a step waits for answers, the employer’s form is held open. Each answerable step carries answers_expire_at: Trust the returned timestamp, not these defaults. Answer promptly even when the deadline is null: a resumed application must reopen the form, and a null deadline does not mean unlimited application lifetime. A verification code is an ordinary answer: read it from the candidate’s inbox however you already do and submit it like any other. Connected mailboxes can fetch the code or confirmation link for you, but the loop never requires them.

5. Recovery

A deploy, a proxy timeout, or a crashed process can drop any blocking call. A network failure never proves that the application failed or that the employer did not receive it. Read the saved application with a waiting GET:
Keep waiting on queued or running, answer awaiting_answers, and stop on submitted, failed, or canceled.

A create dropped

Repeat the same POST with the same Idempotency-Key. The replay re-attaches to the in-flight application and resumes the same wait.
  • Persist the key before you send create, and the application ID as soon as you have it.
  • A different body with a reused key returns 409 idempotency_key_reuse.
  • Keys expire after 24 hours. Don’t replay a create after that: it can create another application.

An answers call dropped

Fetch the application and compare current_step.id, sequence, and correction_round with your saved step. correction_round guards the round; it does not identify a step across pages.

A call returned 202

The server’s 90-second hold expired while the application was still working. The body is a snapshot, not a result. Repeat the waiting GET above until the application is answerable or terminal.

SDK and workers

The TypeScript SDK retries transient request failures, and run() re-attaches to 202 snapshots. Your application still owns persistence and recovery after a process restart. Run at most one answer-producing worker per application, so two callers never answer different snapshots.

6. Local development

The loop needs no inbound connectivity, so it runs from localhost, CI, or a notebook. The one exception is file answers (resumes): you supply a public HTTPS URL that Jobo downloads, such as a signed object-storage URL. A localhost URL is rejected with unsafe_file_url. See file answers for the full requirements.

7. Cancel

POST /api/auto-apply/applications/{id}/cancel requests cancellation and returns 202 with a summary. Fetch the application until it is terminal. Queued applications cancel immediately; others stop at the next safe checkpoint. A submission the ATS already confirmed wins the race: the application ends submitted, with cancel_requested: true recording the attempt.