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:
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:
answers.json, set APPLICATION_ID, and send it from your
backend:
400 validation_failed at once, with per-field errors:
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 withcorrection_round incremented and command_errors listing what was
rejected:
correction_limit_exceeded.
4. Deadlines
While a step waits for answers, the employer’s form is held open. Each answerable step carriesanswers_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:queued or running, answer awaiting_answers, and stop on
submitted, failed, or canceled.
A create dropped
Repeat the samePOST 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 comparecurrent_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, andrun() 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 isfile 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.
