---
title: Async operations
description: 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](/api) for the full requirement.

The response body holds the ID, and the `Location` header points at the job:

```http
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.

```bash
curl -sS "https://api.soljio.com/v0/jobs/JOB_ID" \
  -H "Authorization: Bearer $SOLJIO_TOKEN"
```

```json
{
  "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](/developers/rate-limits).

## 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](/developers/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](/developers/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.
