Async operations
How to follow jobs started by invitations, custom domains, payment connections, and notification previews, and how reports are prepared.
Some commands start work that finishes after the response. Soljio accepts the command, answers right away with 202 Accepted, and runs the work in the background. You follow it with a job.
A 202 means the work was accepted, not that it succeeded. A queued invitation email, for example, has not necessarily been delivered.
Which commands return a job
| Command | What it starts | Scope |
|---|---|---|
invite_staff |
Emails a staff invitation | staff.invite |
resend_staff_invitation |
Replaces an invitation and emails it | staff.invite |
send_household_claim |
Emails a household invitation to claim their account | participants.write |
request_custom_domain |
Requests a custom domain; check DNS verification with get_job and list_custom_domains |
domains.write |
refresh_custom_domain |
Rechecks a custom domain’s status | domains.write |
disable_custom_domain |
Disables a custom domain | domains.write |
sync_payment_connection |
Refreshes the connected Stripe account’s capabilities | payments.write |
disconnect_payment_connection |
Disconnects the payment account | payments.write |
preview_notification_template |
Renders a notification template with sample content | communications.read |
The list of scopes above is each command’s first required scope. Check x-required-scopes in the API reference for the full requirement.
The response body holds the ID, and the Location header points at the job:
HTTP/2 202
location: /v0/jobs/JOB_ID
{"data":{"invitation_id":"INVITATION_ID","job_id":"JOB_ID"},"idempotent_replay":false,"request_id":"00000000-0000-4000-8000-000000000004"}
send_household_claim returns 200 with "status": "already_claimed" when the household has already claimed its account. Only a queued invitation returns 202 and a job_id.
Follow a job
Read the job with either GET /v0/jobs/JOB_ID or POST /v0/queries/get_job with {"job_id":"JOB_ID"}. Both return the same body.
curl -sS "https://api.soljio.com/v0/jobs/JOB_ID" \
-H "Authorization: Bearer $SOLJIO_TOKEN"
{
"data": {
"id": "JOB_ID",
"status": "complete",
"created_at": "2026-01-05T17:04:11.000Z",
"updated_at": "2026-01-05T17:04:13.000Z",
"result": {}
},
"request_id": "00000000-0000-4000-8000-000000000005"
}
| Field | Meaning |
|---|---|
status |
queued, running, complete, or failed |
result |
Present when the job produced something. Fields are connected, delivered, domain_id, domain_status (pending, active, or disabled), hostname, message, source, and version, depending on the job |
error_code |
A short, safe code when the job failed |
created_at, updated_at |
RFC 3339 UTC instants |
A job read needs two grants: organization.read and the scope of the command that started the job. A job ID from another school, or one you cannot see, returns 404. A GET on a job path takes no query-string parameters.
Poll with some delay and stop when status is complete or failed. The contract does not set a polling interval; a few seconds between reads is reasonable, and each read costs one request against your rate limit.
Failed jobs
A failed job has status: "failed" and an error_code:
| Code | Meaning |
|---|---|
authorization_changed |
The token was revoked, expired, or lost the needed scope before the job started. The work did not run |
operation_failed |
The work started and could not finish |
operation_abandoned |
The job stayed in running for more than 15 minutes and was marked failed |
Soljio rechecks the credential and its scope before it does the work, so revoking a token also stops its queued jobs.
The command that started a failed job already succeeded, so its idempotency key is used up. After you address the cause, send the command again with a new key. See Idempotency.
Reports
Reports use their own lifecycle rather than the shared job one:
POST /v0/commands/request_reportwith an optionalstarts_atandends_at. It needsreports.writeand returns the report job’s ID indata.POST /v0/queries/get_reportwith{"job_id":"..."}untilstatusiscomplete(it can also berunningorfailed). It needsreports.readand returns a summary with row counts.POST /v0/queries/get_report_rowswith thejob_id, akindofattendance,capacity, orrevenue, andpagination_optsto read the rows. See Pagination.
Row reads and exports are scoped and written to the audit log.
Troubleshooting
- A job stays
queued. Keep polling for a short while. If it ends asfailedwithauthorization_changed, check that the token is still active and still holds the scope. - 404 or 403 on a job you just created. A job belongs to one school, and reading it needs
organization.readplus the scope of the command that created it. Check the token holds both. - Complete, but the email did not arrive. A completed invitation job means Soljio handed the email off. It is not proof of delivery.