> 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/use-cases/assessment-driven-handoff.md).

# Assessment-Driven Handoff

**One line:** Run the check in your product, then hand the traveller to VisaDoc for the whole visa journey.

**Best for:** The fastest end-to-end path, with the lowest data exposure. This is the recommended minimum integration.

## Flow

```mermaid
sequenceDiagram
  participant You
  participant VisaDoc
  participant Traveller
  You->>VisaDoc: POST /assessments/new
  VisaDoc-->>You: visa_required + entry_options[]
  You->>VisaDoc: POST /applicants/new (name + email)
  VisaDoc-->>You: applicant id
  opt Pre-create the case
    You->>VisaDoc: POST /applications/new (option + applicant)
    VisaDoc-->>You: application id
  end
  You->>VisaDoc: GET /magic_link (email)
  VisaDoc-->>You: token (60 min, single use)
  You->>Traveller: Redirect with the link (landing URL + token)
  Traveller->>VisaDoc: Profile, documents, submission
  loop Track progress
    You->>VisaDoc: POST /applications/search (by assessment)
    VisaDoc-->>You: status
  end
```

1. `POST /assessments/new` and read the result (see [Embedded Eligibility Check](/use-cases/embedded-eligibility-check.md) for how to interpret it). Continue when the trip is in scope and `visa_required` is `true`.
2. `POST /applicants/new` with `{ email, first_name, last_name, role: "Applicant" }` and keep the returned `id`. If the traveller may already exist, search first (see [Returning Traveller Fast Path](/use-cases/returning-traveller-fast-path.md)).
3. Choose where the traveller lands:
   * **Let them choose in VisaDoc (lighter).** Link to the assessment results, `…/magic_login?tab=assessment-form&assessment=<assessment id>`. The traveller picks an entry option and starts the application themselves.
   * **Pre-create the case.** `POST /applications/new` with the option you or the traveller chose (see the field note), then link to `…/magic_login?tab=application&application=<application id>`.
4. `GET /magic_link?email=…` returns a sign-in token. Add it to the landing URL from step 3 as `&token=<token>` and send the traveller the link. Request the token at the moment you redirect: it lasts 60 minutes and works once. See [Magic Link](/magic-link.md).
5. Track the case. If the traveller started the application in VisaDoc, you don't have its ID yet: find it with `POST /applications/search` and `{ "filters": { "assessment": ["<assessment id>", …] } }` (one call can cover many assessments). Then follow `status`, and after `Decision Made`, [read the outcome](/statuses.md#reading-the-outcome).

{% hint style="info" %}
**Field note: `applications/new`**

* `assessment_id`: the assessment's `id`.
* `entry_option_id`: the chosen option's `entry_option_details.id`.
* `applicant_id`: the applicant's `id`.
* `access_ids`: an array of the user IDs who can see the case. At least one: the applicant's `id`, plus any manager's.

Pass every ID exactly as the API returned it. The response includes the new application's `id`.
{% endhint %}

**Consider:** Only trip data plus the traveller's name and email transfer to VisaDoc; the traveller uploads passports and other documents directly in VisaDoc. This is the lowest-PII fulfilment path and the least code to maintain. If you already hold some of the traveller's documents, you can upload them to the case in advance (see [Document Verification Service](/use-cases/document-verification-service.md)) so they don't have to provide them twice.

**Endpoints:** `POST /assessments/new`, `POST /applicants/new`, `POST /applications/new` (optional), `GET /magic_link`, `POST /applications/search`, `GET /applications/{application_id}`.