{
  "openapi": "3.1.0",
  "info": {
    "title": "Right To Work Checker API",
    "version": "1.0.0",
    "summary": "Verify UK right-to-work share codes against gov.uk.",
    "description": "POST a share code, applicant DOB, and employer company name. The service drives a real browser session against gov.uk/view-right-to-work and returns a structured JSON result including outcome, applicant photo, gov.uk PDF, conditions, and audit reference.",
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "/",
      "description": "This origin"
    }
  ],
  "paths": {
    "/api/check": {
      "post": {
        "summary": "Check a UK right-to-work share code",
        "operationId": "check",
        "description": "Requires `Authorization: Bearer rtw_live_<key>` (or `rtw_test_<key>` for the sandbox; sandbox requests are unmetered and never call gov.uk). Each successful response includes monthly-quota and request-id headers.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RtwCheckRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Check succeeded.",
            "headers": {
              "X-RateLimit-Limit": {
                "description": "Monthly included checks for the caller's tier.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Included checks left in the current month.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "description": "Unix timestamp (seconds) when the included quota resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-Request-Id": {
                "description": "Server-generated request identifier (use in support tickets).",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RtwCheckResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RtwErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RtwErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment required: subscription is past_due / unpaid (PAYMENT_REQUIRED) or free-tier monthly quota exhausted (QUOTA_EXCEEDED).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RtwErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Share code not found or DOB mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RtwErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Includes Retry-After header. Returned by per-key RPS limiter and by the soft-throttle at 1.5× the monthly cap.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RtwErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RtwErrorResponse"
                }
              }
            }
          },
          "502": {
            "description": "Unexpected gov.uk response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RtwErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Server busy. Retry after the Retry-After interval.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RtwErrorResponse"
                }
              }
            }
          },
          "504": {
            "description": "Timed out talking to gov.uk.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RtwErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorCode": {
        "type": "string",
        "enum": [
          "INVALID_INPUT",
          "NOT_FOUND",
          "DOB_MISMATCH",
          "BUSY",
          "GOVUK_UNEXPECTED",
          "TIMEOUT",
          "INTERNAL",
          "UNAUTHENTICATED",
          "INVALID_KEY",
          "QUOTA_EXCEEDED",
          "PAYMENT_REQUIRED",
          "RATE_LIMITED"
        ]
      },
      "RtwCheckRequest": {
        "type": "object",
        "required": [
          "share_code",
          "date_of_birth",
          "company_name"
        ],
        "properties": {
          "share_code": {
            "type": "string",
            "description": "9-character UK share code. Spaces are tolerated and stripped server-side.",
            "example": "AB1 CD2 EF3"
          },
          "date_of_birth": {
            "type": "string",
            "format": "date",
            "description": "Applicant date of birth in ISO YYYY-MM-DD format.",
            "example": "1990-01-01"
          },
          "company_name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Employer company name. Recorded in gov.uk's audit trail.",
            "example": "Acme Ltd"
          }
        }
      },
      "RtwCheckResponse": {
        "type": "object",
        "required": [
          "outcome",
          "title",
          "name",
          "date_of_birth",
          "conditions",
          "restrictions",
          "share_code",
          "checked_at"
        ],
        "properties": {
          "outcome": {
            "type": "string",
            "enum": [
              "ACCEPTED",
              "REJECTED"
            ]
          },
          "title": {
            "type": "string",
            "enum": [
              "Right to work",
              "Right to rent"
            ]
          },
          "name": {
            "type": "string"
          },
          "date_of_birth": {
            "type": "string",
            "format": "date"
          },
          "nationality": {
            "type": [
              "string",
              "null"
            ]
          },
          "permission_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "start_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "expiry_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "conditions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "restrictions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "share_code": {
            "type": "string"
          },
          "photo_data_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Base64 data URL of the applicant's photo (JPEG)."
          },
          "pdf_data_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Base64 data URL of the gov.uk-rendered PDF."
          },
          "checked_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp when the check completed."
          }
        }
      },
      "RtwErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "$ref": "#/components/schemas/ErrorCode"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}