Right to Work (Werkrecht)

Determines whether a candidate is legally permitted to work in a given country. The candidate completes a document capture step with liveness detection; a decision engine then evaluates nationality, the residence document and the work endorsement (arbeidsaantekening) on the back of that document, and returns a machine-readable outcome.

{
  "checkName": "right-to-work-data",
  "importance": "NOT_SKIPPABLE",
  "configuration": {
    "applicantLevelName": "id-and-liveness-right-to-work",
    "requiredValidity": "P3M",
    "workCountry": "NLD"
  }
}

Configuration Parameters

Parameter	Type	Required	Description
`applicantLevelName`	string	No	Document capture level used for this check
`requiredValidity`	string	No	ISO-8601 period (e.g. `P3M`). The residence document must remain valid at least this long
`workCountry`	string	No	ISO 3166-1 alpha-3 code of the country the placement is worked in. Decides which country's rule set applies. Defaults to `NLD`

Result Fields

These fields are the stable contract. Build your integration on these.

Field	Type	Values / Format
`outcomeCode`	STRING	`OUTCOME_ALLOWED` / `OUTCOME_REVIEW` / `OUTCOME_LIKELY_NOT_ALLOWED`
`reasonCode`	STRING	`NONE` or `R1`–`R11` (see below)
`classification`	STRING	Work-right classification derived from the endorsement (see below)
`documentValidUntil`	DATE	Expiry date of the residence/work document the decision was based on
`workCountry`	STRING	ISO 3166-1 alpha-3 code of the country whose rules produced this outcome
`ruleSetVersion`	STRING	Audit — version of the rule set that produced this outcome
`reviewState`	STRING	`CONFIRMED` / `OVERRIDDEN` / `NOT_APPLICABLE`. Absent until reviewed
`decisionOutcomeCode`	STRING	The reviewing organisation's own outcome when it differs from `outcomeCode`. `null` until reviewed, and `null` again after a plain confirm

Outcome Codes

Value	Meaning
`OUTCOME_ALLOWED`	Work is permitted
`OUTCOME_REVIEW`	The engine could not decide with certainty. A person must assess the case
`OUTCOME_LIKELY_NOT_ALLOWED`	Work is likely not permitted

Reason Codes

reasonCode is NONE when nationality or the work endorsement established the right to work directly. Otherwise it carries exactly one of:

Value	Meaning
`R1_DOC_MISSING`	Right to work cannot be established; residence document is missing
`R2_TWV_REQUIRED`	A work permit (TWV) is required
`R3_EMPLOYER_BOUND`	The permit is employer-bound; this employer needs its own TWV/GVVA
`R4_NOT_ALLOWED`	Work is not permitted
`R5_NO_ANNOTATION`	No work endorsement present, which means work is not permitted
`R6_EXPIRED`	The residence document has expired
`R7_UNREADABLE`	The endorsement is illegible or unclear
`R8_LAPSED`	The right to work may have lapsed. Produced by expiry monitoring, not by the initial decision
`R9_ANNOTATION_NOT_RECOGNIZED`	The endorsement was read successfully but matches no known pattern. A person must read the extracted text and judge it
`R10_NATIONALITY_UNKNOWN`	Nationality was absent or not a recognised ISO 3166-1 alpha-3 code, so neither assessment route applies
`R11_DOCUMENT_COUNTRY_MISMATCH`	The residence document was issued by a country other than the work country

Classification

Describes what the work endorsement permits. This is never the document type — see documentEvidenceClass below for that.

Value	Meaning
`FREELY_ALLOWED`	Work freely permitted
`ALLOWED_WITH_TWV`	Work permitted subject to a TWV/GVVA
`CONDITIONAL`	Work conditionally permitted
`NOT_ALLOWED`	Work not permitted
`ABSENT`	No work endorsement present
`UNREADABLE`	Endorsement illegible

Two Rules Your Integration Must Follow

Branch on outcomeCode, not on check status

A check with status SUCCESS and outcomeCode of OUTCOME_REVIEW is not a green light. It means the engine could not reach a conclusion and a person must assess the case. Treating check status alone as a pass will let candidates through who were never cleared.

A reviewer's decision never overwrites outcomeCode

outcomeCode always remains Otentica's advisory outcome. When a reviewer overrides it, their decision is written to decisionOutcomeCode and reviewState becomes OVERRIDDEN. If you read only outcomeCode, you will miss the override. Read decisionOutcomeCode first and fall back to outcomeCode when it is null.

Supporting Fields

These fields exist to explain a decision to a person reading the report. They are not part of the stable contract: their wording and values may change without that counting as a breaking change. Do not build logic on them.

Field	Type	Description
`rightToWorkBasis`	STRING	Human-readable basis for the outcome, e.g. `EU/EEA/CH nationality (NLD)`
`specialCategories`	STRING	Comma-separated: `STUDENT`, `TURKISH_NATIONAL`, `KNOWLEDGE_MIGRANT`, `UKRAINE_O_DOCUMENT`, `ASYLUM_APPLICANT`
`documentEvidenceClass`	STRING	`NONE`, `RESIDENCE_PERMIT_CARD`, `W_DOCUMENT`, `W2_DOCUMENT`, `O_DOCUMENT`, `FOREIGN_PASSPORT_WITH_IND_STICKER`, `UNKNOWN`
`residencePermitCategory`	STRING	`TYPE_I` to `TYPE_V`, or `UNKNOWN`. Read off the document front; does not feed the decision engine
`workAnnotation`	STRING	The endorsement classification as read from the document
`workAnnotationText`	STRING	The endorsement text as extracted from the document
`workAnnotationFlagReasons`	STRING	Comma-separated list of auto-propose gate conditions that failed; empty when auto-proposed
`annotationTableVersion`	STRING	Audit — version of the endorsement lookup table active for this result
`permitEmployerName`	STRING	Employer named on a recorded TWV/GVVA
`permitEmployerKvk`	STRING	KvK number of that employer
`validTwvGvvaConfirmedForEmployer`	BOOLEAN	Whether a valid TWV/GVVA was confirmed for that employer
`reviewedBy`	STRING	Display name of the reviewer
`reviewedAt`	STRING	ISO-8601 instant of the confirm/override action
`overrideNote`	STRING	Reviewer's note on an override; `null` for a plain confirm

The check also returns the usual document fields: identityDocument, identityDocumentBackside, selfie, identityDocumentType, identityDocumentNumber, identityDocumentDateOfExpiry, nationality, documentIssuingCountry, documentFirstName, documentLastName, documentDateOfBirth and placeOfBirth.

Example Result

{
  "checkIdentifier": "right-to-work-data",
  "status": "SUCCESS",
  "contentType": "application/vnd.otentica.singlecheck.check.right-to-work-data+json",
  "importance": "NOT_SKIPPABLE",
  "completedAsExpected": false,
  "results": [
    {
      "group": null,
      "checkName": "right-to-work-data",
      "fieldName": "outcomeCode",
      "value": "OUTCOME_REVIEW",
      "verified": true,
      "verifiedBy": "otentica",
      "verifiedOn": "2026-09-18T09:15:36.157982Z"
    },
    {
      "group": null,
      "checkName": "right-to-work-data",
      "fieldName": "reasonCode",
      "value": "R2_TWV_REQUIRED",
      "verified": true,
      "verifiedBy": "otentica",
      "verifiedOn": "2026-09-18T09:15:36.158214Z"
    },
    {
      "group": null,
      "checkName": "right-to-work-data",
      "fieldName": "classification",
      "value": "ALLOWED_WITH_TWV",
      "verified": true,
      "verifiedBy": "otentica",
      "verifiedOn": "2026-09-18T09:15:36.158390Z"
    },
    {
      "group": null,
      "checkName": "right-to-work-data",
      "fieldName": "documentValidUntil",
      "value": "2028-04-30",
      "verified": true,
      "verifiedBy": "otentica",
      "verifiedOn": "2026-09-18T09:15:36.158561Z"
    },
    {
      "group": null,
      "checkName": "right-to-work-data",
      "fieldName": "workCountry",
      "value": "NLD",
      "verified": true,
      "verifiedBy": "otentica",
      "verifiedOn": "2026-09-18T09:15:36.158702Z"
    }
  ]
}

Reviewer Endpoints

A reviewer in the Otentica dashboard can act on a right-to-work outcome. The same endpoints are available over the API.

Confirm or Override the Outcome

PUT https://[api-url]/validation-flow/check/{id}/right-to-work/review
Authorization: Bearer yourapikeyhere
Authorization-Method: api-token
Content-Type: application/json

{
  "action": "OVERRIDE",
  "overrideOutcomeCode": "OUTCOME_ALLOWED",
  "note": "Verified manually against the original document."
}

action is CONFIRM or OVERRIDE. overrideOutcomeCode is required for OVERRIDE and ignored for CONFIRM. note is optional.

Record an Employer-Held TWV/GVVA

PUT https://[api-url]/validation-flow/check/{id}/right-to-work/twv-gvva
Content-Type: application/json

{
  "permitEmployerName": "Acme Uitzendbureau B.V.",
  "permitEmployerKvk": "12345678",
  "confirmed": true
}

A TWV/GVVA is held by the employer, never uploaded by the candidate. This endpoint is how it is recorded against the flow.

Correct the Document Evidence Class

PUT https://[api-url]/validation-flow/check/{id}/right-to-work/document-evidence-class
Content-Type: application/json

{
  "documentEvidenceClass": "O_DOCUMENT"
}

Use this when the captured document was classified as a generic residence permit but is in fact a W-, W2- or O-document, which route through different legal branches. The value is validated against the allowed set and is never silently defaulted.

This check processes the BSN

When the document carries a valid BSN (Dutch citizen service number), it is returned unmasked in the result field personalNumber. A residence permit additionally yields the V-number (vreemdelingennummer) as vNumber, which is never a substitute for the BSN.

The BSN is a highly sensitive identifier. Under article 46 of the Dutch UAVG it may only be processed where a statutory basis exists; for right to work that basis is the verification and retention duty under the Wet arbeid vreemdelingen. As an integration partner this means:

Purpose limitation. Use personalNumber and vNumber only to establish and evidence the right to work. Never as a customer number, lookup key or join field, and never for other processes.
Storage limitation. Only copy these fields into your own systems if you have your own statutory basis and retention period for them. If you do not, filter them out on receipt. You do not need them for the outcome: that is fully expressed by outcomeCode and reasonCode.
Retention. The screening is irreversibly anonymised on its expiry date, or earlier via the archive endpoint. That anonymisation covers the data held by Otentica only — anything you copied is yours to clean up.
Access control. Restrict access to these fields to the people who actually assess the right to work, and log that access.

Configuration Parameters​

Result Fields​

Outcome Codes​

Reason Codes​

Classification​

Two Rules Your Integration Must Follow​

Supporting Fields​

Example Result​

Reviewer Endpoints​

Confirm or Override the Outcome​

Record an Employer-Held TWV/GVVA​

Correct the Document Evidence Class​

Privacy & Data Processing (AVG / GDPR)​