> 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/embedded-eligibility-check.md).

# Embedded Eligibility Check

**One line:** Check whether a traveller needs a visa for a trip, inline in your booking or policy flow.

**Best for:** Booking and policy gating, when you only need the eligibility answer, not fulfilment.

## Flow

```mermaid
sequenceDiagram
  participant You
  participant VisaDoc
  You->>VisaDoc: POST /assessments/new (trip details)
  VisaDoc-->>You: visa_required + entry_options[]
  You->>You: Gate booking / show the answer
```

1. `POST /assessments/new` with the trip:
   * Required: `destination`, `residency`, `nationality`, `location`, `departure_date`, `return_date`. Countries are ISO3; dates are `YYYY-MM-DD`.
   * `requested_activity`: the purpose of the trip in plain words, for example `"Quarterly board meeting with the Tokyo office"`. The more specific, the better the result.
   * Number of entries isn't an input. VisaDoc returns single- and multiple-entry options as relevant.
2. Read `result.visa_required` and `result.entry_options[]` using the rules below.

## Reading the result

**Scope comes first.** VisaDoc assesses **business travel**: meetings, conferences, negotiations and similar visits. It classifies `requested_activity` before anything else, and `activity_category` tells you how it was classified:

| `activity_category`             | What VisaDoc does                                                                                       |
| ------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `business`                      | Full visa assessment                                                                                    |
| `work`                          | Out of scope (employment, long-term work visas). VisaDoc refers these cases to its immigration partners |
| `tourist`, `other`, `not_clear` | Out of scope. No visa search is performed                                                               |

{% hint style="warning" %}
**An out-of-scope result is not "no visa needed".** It comes back as `visa_required: false` with no entry options and an explanation in `notes` (for example `"Out of scope. Please contact our partners"`). Only treat `visa_required: false` as "no visa needed" when `activity_category` is `business`.
{% endhint %}

For an in-scope trip:

* **`visa_required` is the trigger.** `true` means the traveller needs a visa or an ETA; offer the entry options. `false` means no visa is needed for this trip.
* **ETAs are entry options too.** An ETA / ESTA comes back as an entry option and is fulfilled like any visa.
* **Several options?** Sort by `entry_option_score`. The highest score is VisaDoc's recommended option.
* **Option details** (visa type and title, fees, processing time, validity, maximum stay) are in each option's `entry_option_details`. Field definitions are in the [Assessments reference](/api-reference/assessments.md).

## Coming back to a result

`GET /assessments/{assessment_id}` returns the stored result without running a new check, so use it rather than re-running `POST /assessments/new` for the same trip. The result reflects the rules at the time the check ran.

**Consider:** Only trip data leaves your side: the lowest-exposure pattern. You can stop here, or pass the chosen option into an application (see [Assessment-Driven Handoff](/use-cases/assessment-driven-handoff.md)).

**Endpoints:** `POST /assessments/new`, `GET /assessments/{assessment_id}`.