Skip to content
Soljio Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

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:

  1. POST /v0/commands/request_report with an optional starts_at and ends_at. It needs reports.write and returns the report job’s ID in data.
  2. POST /v0/queries/get_report with {"job_id":"..."} until status is complete (it can also be running or failed). It needs reports.read and returns a summary with row counts.
  3. POST /v0/queries/get_report_rows with the job_id, a kind of attendance, capacity, or revenue, and pagination_opts to 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 as failed with authorization_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.read plus 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.

Was this page helpful?