# Work visa text: what the advert says

work_visa_text quotes what the employer's own advert says about visa sponsorship, work permits, relocation and the right to work, and sorts it into four evidence levels by a fixed rule.

**What this covers:** What the field says; The evidence levels; The statement codes; The quotes are verbatim; Coverage; Filtering on it; The legal note.

**Assumed knowledge:** [The fields reference](./api-fields-and-values.md).

**Canonical HTML:** https://jobopportunitiesapi.org/docs/api/work-visa-text  
**Machine-readable index:** https://jobopportunitiesapi.org/docs/ai/index.md  
**Last verified:** 2026-11-14  
**Superseded by:** the live API at https://api.jobopportunitiesapi.org and its spec at https://jobopportunitiesapi.org/openapi.json. Where this file and the API disagree, the API is right.

---

<a id="wvt-what"></a>

## 1. What the field says

Every job carries `work_visa_text`: the employer's own statements about visas and permits, each with a quote copied word for word from the advert, and an `evidence_level`.

### 1.1 In depth

The field describes the advert. It is not advice and not a decision on any person's case, and it says nothing about whether a visa or permit is granted: that depends on the person, the employer and the authority, which an advert does not show. The same reading is shown to every reader.

The quotes are the employer's words. The codes are JOA's reading of them: a language model finds and codes the statements, and code checks that every quote is found exactly in the advert before it is stored. A reading is shown only while the title and the text are exactly the ones that were read (a hash of that text, compared byte for byte; a change of any other field of the job does not count). Adverts longer than 8,000 characters are read as their first 5,000 and last 3,000 characters.

> **Silence is the normal case**: Most adverts say nothing about visas, also at employers that hire from abroad. `no_information` means the advert is silent. It is not a refusal.

### 1.3 Worked examples

A job whose advert asks for an existing work permit.

```json
{
  "work_visa_text": {
    "evidence_level": "stated_closed",
    "statements": [
      {
        "code": "text_permit_required",
        "quote": "Eine gültige Arbeitserlaubnis für Deutschland ist Voraussetzung.",
        "quote_lang": "de",
        "method": "published_by_employer"
      }
    ],
    "method_version": "eu-signals-v1",
    "as_of": "2026-11-14",
    "legal_note_code": "immigration_information"
  }
}
```

<a id="wvt-levels"></a>

## 2. The evidence levels

Four values, by a fixed rule over the codes: a closing statement wins over every other statement.

### 2.1 In depth

- **`stated_closed`**: At least one statement is text_no_sponsorship, text_permit_required or text_citizenship_restriction. This wins over every other statement of the same advert, an offer of help included.
- **`stated_open`**: A statement is text_permit_support, and no statement closes the job.
- **`no_information`**: JOA read the advert and found no statement of these kinds, or only text_relocation_support. The advert is silent; that is not a refusal. Most adverts say nothing of this kind, also at employers that hire from abroad.
- **`not_assessed`**: No current reading: the job was not read yet (only the countries under Coverage are read), or its title or text changed since it was read (JOA compares a hash of the exact text that was read, byte for byte; a change of any other field does not count), or a quote cannot be shown exactly as the employer wrote it, or the field is switched off.

<a id="wvt-codes"></a>

## 3. The statement codes

Five codes. Each statement carries one, with the quote it was read from.

### 3.1 In depth

- **`text_permit_support`**: The advert says the employer helps with or pays for a visa, a work or residence permit, an EU Blue Card or the immigration process for this job.
- **`text_relocation_support`**: The advert offers help to relocate: a relocation package, moving costs, help to find housing, or a relocation bonus or service. On its own it says nothing about permits.
- **`text_permit_required`**: The advert asks for an existing right to work in the country (a valid work or residence permit, a named permit type, settled status), or says the employer does not help candidates who need one.
- **`text_no_sponsorship`**: The advert says the employer does not or cannot sponsor visas or work permits.
- **`text_citizenship_restriction`**: The advert limits the job to citizens or nationals of a country, or of the EU or EEA, or asks for a security clearance that needs citizenship.

<a id="wvt-quotes"></a>

## 4. The quotes are verbatim

A quote is copied character for character from the advert title or description, in the advert's own language. It is never translated, shortened or corrected.

### 4.1 In depth

- `quote`: the employer's words, as the advert shows them on this job.
- `quote_lang`: the ISO 639-1 code of the language JOA detected for the advert text (the job's `language`), null when it was not detected.
- `method`: always `published_by_employer`: the statement is in the employer's own advert.
- A statement is shown only with its quote. When a quote cannot be shown exactly as the employer wrote it (for example because it contains contact details, which JOA removes from advert text), the whole field reads `not_assessed`. A quote is never edited.
- `method_version` names the reading method (for example `eu-signals-v1`) and `as_of` the day the advert was read.

<a id="wvt-coverage"></a>

## 5. Coverage

Read so far: jobs in Germany (DE), France (FR) and Italy (IT) that were live when they were read, up to 2026-11-14. Every other job reads `not_assessed`.

### 5.1 In depth

A job first seen after it was read, or changed since, reads `not_assessed` until it is read again. /v1/help lists the same coverage under `work_visa_text.coverage`.

<a id="wvt-filter"></a>

## 6. Filtering on it

`visa_text=stated_open` or `visa_text=stated_closed` keeps only the jobs with that evidence level. Jobs not read never match.

### 6.1 In depth

The filter works on /v1/jobs, /v1/jobs/similar, /v1/jobs/closed and /v1/export, and combines with every other filter. Any other value is a 422 `bad_visa_text` and nothing is charged. Metering is unchanged.

### 6.3 Worked examples


```bash
curl -H "Authorization: Bearer $JOA_KEY" \
  "https://api.jobopportunitiesapi.org/v1/jobs?country=DE&visa_text=stated_open&limit=20"
```

<a id="wvt-legal-note"></a>

## 7. The legal note

A job whose `work_visa_text` carries a statement carries the legal note `immigration_information`. Show it with the field.

### 7.1 In depth

It is the same note as for `sponsor_registers` and `visa_checks` (`legal_note_code`, `legal_note`). A field without a statement carries no note.

**See also**

- [The job object](./api-fields-and-values.md#fv-job)

---

## Where to go next

This file is part of **API**. Others in the same group:

- [API overview](./api-overview.md): Hosts, versioning, caching, CORS and the HTTP conventions every endpoint follows. Read the hosts section first: getting it wrong costs people hours.
- [Authentication](./api-authentication.md): One header, three accepted spellings, and a deliberate refusal to tell an attacker which kind of wrong a wrong key is.
- [Keyless access](./api-keyless.md): What /public/* gives you with no account: real aggregate numbers against the live ledger (coverage, facets, freshness, providers, the price list, the spec). Job and company ROWS are not part of that anymore: they need a free key, full stop.
- [Rate limits](./api-rate-limits.md): Two independent ceilings (requests per minute and per day) plus a monthly record allowance that is a licence rather than a throttle. They fail differently.
- [Pagination](./api-pagination.md): Keyset cursors, not offsets. One rule matters more than the rest: hand next_cursor back exactly as you received it.

Always useful:

- [index.md](./index.md): the map of every file here
- [BUILD-A-SITE.md](./BUILD-A-SITE.md): the paste-whole brief for building against this API
- [quickstart.md](./quickstart.md): zero to a first authenticated response
- [api-errors.md](./api-errors.md): every status code and whether to retry it
