> For the complete documentation index, see [llms.txt](https://api-docs.visadoc.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.visadoc.co/statuses.md).

# Statuses

Four enumerations drive the platform. Filter and branch on these values.

## Application status

The case lifecycle. Advancement is automatic: a case moves to the next stage when that stage's tasks complete (the exact per-stage gating comes from the flow template for the visa type).

| Status                  | Meaning                                                                                                                               |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `created` / `draft`     | Transitional states before the case is fully opened. If the traveller doesn't finish onboarding, the case is discarded automatically. |
| `New Application`       | Case opened from an assessment; scaffolding done                                                                                      |
| `Documents`             | Collecting and verifying required documents                                                                                           |
| `Profile`               | Traveller profile / applicant data being completed                                                                                    |
| `Application Form`      | Government / embassy form being filled                                                                                                |
| `Submission to Embassy` | Case being submitted to the authority                                                                                                 |
| `In Embassy`            | With the authority, awaiting outcome                                                                                                  |
| `Decision Made`         | Workflow complete. **This is not the outcome:** see [Reading the outcome](#reading-the-outcome)                                       |
| `Border Entry`          | Post-decision stage, after the authority has decided                                                                                  |

What you can change at each stage is on [Trip changes and erasure](/trip-changes-and-erasure.md).

## Reading the outcome

`Decision Made` tells you the workflow is complete. It doesn't tell you whether the visa was granted. Read the outcome like this:

1. **Visa flows: the "Issued Visa" document.** Every application gets an `Issued Visa` document slot when it's created. List the case's documents with `POST /documents/search` (`{ "filters": { "application_id": "…" } }`) and find the one titled `Issued Visa`. When its status is no longer `Required` and its `data` is not `null`, the visa was granted, and the extracted visa details are in `data`.
2. **ETA / ESTA flows** don't produce an Issued Visa document. The result is the application's `eta_confirmation_number`.
3. **The signal only works one way.** A populated Issued Visa document means granted. An empty one does **not** mean refused: the visa may not be uploaded yet, or the case may still be finalising. Treat it as "not yet determined".
4. **Refusals aren't exposed through the API yet.** Don't infer a refusal from missing data.

When you read `data`:

* Treat every field inside `data` as optional. Fields can be partial or absent depending on the flow and on what's legible on the document.
* Don't confuse `Issued Visa` with `Previous Visas`. Previous Visas is visa history the traveller supplied, not the visa VisaDoc obtained.
* Don't use the application's `visa_json` for issued-visa facts. It's a snapshot of the visa product chosen when the application was created, not the visa that was issued.

## Payment status

| Value        | Meaning                            |
| ------------ | ---------------------------------- |
| `processing` | Payment initiated, not yet settled |
| `paid`       | Settled                            |
| `failed`     | Attempt failed                     |

There is **no `unpaid` value**. A case that has never been paid has this field empty / absent, so "find unpaid cases" means filtering for absence, not for a value.

## Document status

The verification pipeline. It is **asynchronous**: status keeps moving after upload, so never treat the immediate upload response as final.

| Status                                               | Meaning                                         |
| ---------------------------------------------------- | ----------------------------------------------- |
| `Required`                                           | Slot exists, no file yet                        |
| `Uploaded`                                           | File received                                   |
| `Sent to Verification` / `Accepted for Verification` | Queued with / accepted by the checker           |
| `Verified by AI`                                     | Passed automated checks                         |
| `Verified by human`                                  | Passed human review                             |
| `Data Extracted`                                     | Structured fields pulled into the `data` object |
| `Error`                                              | Failed a check: see `error_notes` / `issues`    |

## Role

One email is one user with one role. Roles don't stack.

| Role         | Who                                                                                         |
| ------------ | ------------------------------------------------------------------------------------------- |
| `Applicant`  | The traveller                                                                               |
| `Manager`    | Books and manages travellers' cases                                                         |
| `Admin`      | Access to the whole instance; can generate API tokens and switch between live and demo mode |
| `Sales`      | Works in demo mode only (demos and testing)                                                 |
| `superAdmin` | VisaDoc internal                                                                            |

`POST /applicants/new` only accepts `Applicant` or `Manager`. The other roles are assigned by VisaDoc.