> 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/bring-your-own-engine.md).

# Bring Your Own Engine

**One line:** You already decide the visa; use VisaDoc as the execution / fulfilment layer.

**Best for:** Partners with their own visa logic who want VisaDoc to execute, verify, and submit.

## How it works

Applications are always created from a VisaDoc assessment: `POST /applications/new` requires an `assessment_id` and an `entry_option_id`. So even when your engine makes the call, you still run `POST /assessments/new` for the trip. Your engine decides **whether** to proceed and **which** visa; you map that decision onto one of the entry options VisaDoc returns.

## Flow

```mermaid
sequenceDiagram
  participant You
  participant VisaDoc
  You->>You: Your engine decides: visa needed + which one
  You->>VisaDoc: POST /assessments/new (same trip)
  VisaDoc-->>You: entry_options[]
  You->>You: Map your choice to an entry option
  You->>VisaDoc: POST /applicants/new
  You->>VisaDoc: POST /applications/new (mapped option)
  Note over You,VisaDoc: Then fulfil via handoff or white-label
```

{% stepper %}
{% step %}

## Decide in your engine

Your engine decides that a visa is needed and which type, under your policy.
{% endstep %}

{% step %}

## Run the VisaDoc assessment

`POST /assessments/new` with the same trip data. This registers the trip and returns the entry options VisaDoc can fulfil.
{% endstep %}

{% step %}

## Map your choice to an entry option

Match your engine's choice to one of the returned options using its `entry_option_details` (visa type and title, validity, maximum stay). The match gives you the `entry_option_id`.

VisaDoc can only fulfil an option it returned. If none matches your choice, or the assessment comes back out of scope, decide up front which side wins, and talk to VisaDoc before you build the mapping.
{% endstep %}

{% step %}

## Create the applicant and application

`POST /applicants/new`, then `POST /applications/new` with the assessment `id` and the mapped `entry_option_id` (see the [handoff field note](/use-cases/assessment-driven-handoff.md)).
{% endstep %}

{% step %}

## Fulfil the application

Hand the traveller to VisaDoc with a [magic link](/magic-link.md), or collect documents yourself as in the [white-label flow](/use-cases/white-label-flow.md).
{% endstep %}
{% endstepper %}

**Consider:** This pattern is about who **decides**, not who executes: you keep policy and routing; VisaDoc keeps execution, verification, and submission.

**Endpoints:** `POST /assessments/new`, `POST /applicants/new`, `POST /applications/new`, then magic link or documents + application endpoints.