{
    "openapi": "3.1.0",
    "info": {
        "title": "FindMyPub API",
        "version": "1.0.0",
        "description": "The latest documentation for the FindMyPub REST API.\n\nAccess JSON endpoints for API discovery. Authenticate using your client id and\nsecret, then use a bearer token to authorise against endpoints such as\nscreening.",
        "x-logo": {
            "url": "https://mypubgroup.github.io/api-docs/assets/fmp-logo.png",
            "altText": "FindMyPub"
        }
    },
    "servers": [
        {
            "url": "https://api.findmypub.com"
        }
    ],
    "tags": [
        {
            "name": "API Versions"
        },
        {
            "name": "Summary"
        },
        {
            "name": "Auth"
        },
        {
            "name": "Screening"
        }
    ],
    "paths": {
        "/": {
            "get": {
                "operationId": "api::index",
                "description": "Return endpoint links to the available API versions.",
                "summary": "Get the API Versions",
                "tags": [
                    "API Versions"
                ],
                "responses": {
                    "200": {
                        "description": "`Versions`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Versions"
                                        },
                                        "links": {
                                            "type": "object",
                                            "properties": {
                                                "1": {
                                                    "type": "string"
                                                },
                                                "current": {
                                                    "type": "string"
                                                }
                                            },
                                            "required": [
                                                "1",
                                                "current"
                                            ]
                                        }
                                    },
                                    "required": [
                                        "data",
                                        "links"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthenticationException"
                    }
                }
            }
        },
        "/1": {
            "get": {
                "operationId": "api::v1.index",
                "description": "Return endpoint links to the main resources available in this API version.",
                "summary": "Get the API Endpoint Summary",
                "tags": [
                    "Summary"
                ],
                "responses": {
                    "200": {
                        "description": "`Summary`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Summary"
                                        },
                                        "links": {
                                            "type": "object",
                                            "additionalProperties": {
                                                "type": "string"
                                            }
                                        }
                                    },
                                    "required": [
                                        "data",
                                        "links"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthenticationException"
                    }
                }
            }
        },
        "/1/login": {
            "post": {
                "operationId": "api::v1.login",
                "description": "Authenticate a client_id and client_secret credential pair, then return\na bearer token that is valid for 10 minutes.",
                "summary": "Log In",
                "tags": [
                    "Auth"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/LoginRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "`Success`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Success"
                                        }
                                    },
                                    "required": [
                                        "data"
                                    ]
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationException"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthenticationException"
                    }
                }
            }
        },
        "/1/logout": {
            "post": {
                "operationId": "api::v1.logout",
                "description": "Revoke the bearer token used to authenticate the current request.",
                "summary": "Log Out",
                "tags": [
                    "Auth"
                ],
                "responses": {
                    "200": {
                        "description": "`Logout`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Logout"
                                        }
                                    },
                                    "required": [
                                        "data"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthenticationException"
                    }
                }
            }
        },
        "/1/create-token": {
            "post": {
                "operationId": "api::v1.create-token",
                "description": "Create a named bearer token with optional abilities and expiry duration.\nRequested abilities are narrowed to those already granted to the app;\nthey default to the app's full set of abilities when none are given.",
                "summary": "Create an Access Token",
                "tags": [
                    "Auth"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreateTokenRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "`Token`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Token"
                                        }
                                    },
                                    "required": [
                                        "data"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthenticationException"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationException"
                    }
                }
            }
        },
        "/1/myrecruitai": {
            "post": {
                "operationId": "api::v1.myrecruitai",
                "description": "Evaluate a candidate's answers against a client's qualification rules and\nreturn the business outcome: `pass`, or `fail` with one or more reasons.\nNothing is persisted.",
                "summary": "Screen a Candidate (MyRecruitAI)",
                "tags": [
                    "Screening"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ScreeningRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "`Pass`\n\n`Fail`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "anyOf": [
                                        {
                                            "$ref": "#/components/schemas/Pass"
                                        },
                                        {
                                            "$ref": "#/components/schemas/Fail"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Rule configuration missing",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "integer",
                                            "description": "HTTP status code.",
                                            "examples": [
                                                409
                                            ]
                                        },
                                        "message": {
                                            "type": "string",
                                            "description": "Error overview."
                                        },
                                        "code": {
                                            "type": "string",
                                            "description": "Machine-readable error code."
                                        }
                                    },
                                    "required": [
                                        "status",
                                        "message",
                                        "code"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthenticationException"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationException"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "CreateTokenRequest": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Human-readable name used to identify the token.",
                        "maxLength": 255
                    },
                    "abilities": {
                        "type": "array",
                        "description": "Sanctum abilities granted to the token, narrowed to those already granted to the app. Defaults to the app's own abilities.",
                        "items": {
                            "type": "string",
                            "description": "An individual Sanctum ability.",
                            "maxLength": 255
                        }
                    },
                    "expires_in": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "description": "Number of minutes until the token expires. Defaults to 10.",
                        "minimum": 1
                    }
                },
                "required": [
                    "name"
                ],
                "title": "CreateTokenRequest"
            },
            "Fail": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "const": "fail"
                    },
                    "reasons": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                },
                "required": [
                    "status",
                    "reasons"
                ],
                "title": "Fail"
            },
            "Failed": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string"
                    },
                    "message": {
                        "type": "string"
                    }
                },
                "required": [
                    "status",
                    "message"
                ],
                "title": "Failed"
            },
            "LoginRequest": {
                "type": "object",
                "properties": {
                    "client_id": {
                        "type": "string",
                        "description": "Public client identifier issued to the API app."
                    },
                    "client_secret": {
                        "type": "string",
                        "description": "Client secret issued alongside the client identifier."
                    }
                },
                "required": [
                    "client_id",
                    "client_secret"
                ],
                "title": "LoginRequest"
            },
            "Logout": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "integer",
                        "const": 200
                    },
                    "message": {
                        "type": "string",
                        "const": "Logout successful."
                    }
                },
                "required": [
                    "status",
                    "message"
                ],
                "title": "Logout"
            },
            "Pass": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "const": "pass"
                    }
                },
                "required": [
                    "status"
                ],
                "title": "Pass"
            },
            "ScreeningRequest": {
                "type": "object",
                "properties": {
                    "agreement_type": {
                        "type": "array",
                        "description": "One or more agreement type names used to select the client's qualification rules. Accepts a single name or an array of names.",
                        "items": {
                            "type": "string",
                            "description": "An agreement type name.",
                            "maxLength": 255
                        },
                        "minItems": 1
                    },
                    "candidate": {
                        "type": "object",
                        "description": "Candidate answers evaluated by the screening rules.",
                        "properties": {
                            "bankrupt": {
                                "type": "boolean",
                                "description": "Whether the candidate has been declared bankrupt."
                            },
                            "ccj": {
                                "type": "boolean",
                                "description": "Whether the candidate has a county court judgment (CCJ)."
                            },
                            "uk_resident": {
                                "type": "boolean",
                                "description": "Whether the candidate is a UK resident."
                            },
                            "personal_licence": {
                                "type": "boolean",
                                "description": "Whether the candidate holds a personal licence."
                            },
                            "peat": {
                                "type": "boolean",
                                "description": "Whether the candidate satisfies the PEAT screening criterion."
                            },
                            "has_visited": {
                                "type": [
                                    "boolean",
                                    "null"
                                ],
                                "description": "Whether the candidate has visited the vacancy. Defaults to true."
                            },
                            "rejected_by_fmp": {
                                "type": [
                                    "boolean",
                                    "null"
                                ],
                                "description": "Whether the candidate was previously rejected by FindMyPub."
                            },
                            "rejected_by_client": {
                                "type": [
                                    "boolean",
                                    "null"
                                ],
                                "description": "Whether the candidate was previously rejected by the client."
                            },
                            "minimum_cleared_funds": {
                                "type": [
                                    "number",
                                    "null"
                                ],
                                "description": "Candidate's minimum cleared funds in whole pounds (GBP).",
                                "minimum": 0
                            },
                            "planned_investment": {
                                "type": [
                                    "number",
                                    "null"
                                ],
                                "description": "Candidate's planned investment in whole pounds (GBP).",
                                "minimum": 0
                            },
                            "types_of_pubs_looking_for": {
                                "type": [
                                    "array",
                                    "null"
                                ],
                                "description": "Types of pubs the candidate is looking for.",
                                "items": {
                                    "type": "string",
                                    "description": "A type of pub the candidate is looking for.",
                                    "maxLength": 255
                                }
                            }
                        },
                        "required": [
                            "bankrupt",
                            "ccj",
                            "uk_resident",
                            "personal_licence",
                            "peat"
                        ]
                    },
                    "vacancy": {
                        "type": "object",
                        "description": "Vacancy details used by the screening rules.",
                        "properties": {
                            "total_ingoing": {
                                "type": [
                                    "number",
                                    "null"
                                ],
                                "description": "Vacancy's total ingoing costs in whole pounds (GBP).",
                                "minimum": 0
                            }
                        }
                    }
                },
                "required": [
                    "agreement_type",
                    "candidate"
                ],
                "title": "ScreeningRequest"
            },
            "Success": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "integer",
                        "const": 200
                    },
                    "message": {
                        "type": "string",
                        "const": "Login successful."
                    },
                    "token": {
                        "type": "string"
                    }
                },
                "required": [
                    "status",
                    "message",
                    "token"
                ],
                "title": "Success"
            },
            "Summary": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "integer",
                        "const": 200
                    },
                    "message": {
                        "type": "string",
                        "const": "OK"
                    },
                    "version": {
                        "type": "integer",
                        "const": 1
                    }
                },
                "required": [
                    "status",
                    "message",
                    "version"
                ],
                "title": "Summary"
            },
            "Token": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "integer",
                        "const": 201
                    },
                    "message": {
                        "type": "string",
                        "const": "Personal access token created successfully."
                    },
                    "token": {
                        "type": "string"
                    },
                    "id": {
                        "type": "integer"
                    },
                    "name": {
                        "type": "string"
                    },
                    "abilities": {
                        "type": "object",
                        "additionalProperties": {}
                    },
                    "created_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "expires_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    }
                },
                "required": [
                    "status",
                    "message",
                    "token",
                    "id",
                    "name",
                    "abilities",
                    "created_at",
                    "expires_at"
                ],
                "title": "Token"
            },
            "Versions": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "integer",
                        "const": 200
                    },
                    "message": {
                        "type": "string",
                        "const": "OK"
                    }
                },
                "required": [
                    "status",
                    "message"
                ],
                "title": "Versions"
            }
        },
        "responses": {
            "ValidationException": {
                "description": "Validation error",
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "status": {
                                    "type": "integer",
                                    "description": "HTTP status code.",
                                    "examples": [
                                        422
                                    ]
                                },
                                "message": {
                                    "type": "string",
                                    "description": "Errors overview."
                                },
                                "errors": {
                                    "type": "object",
                                    "description": "A detailed description of each field that failed validation.",
                                    "additionalProperties": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    }
                                }
                            },
                            "required": [
                                "status",
                                "message",
                                "errors"
                            ]
                        }
                    }
                }
            },
            "AuthenticationException": {
                "description": "Unauthenticated",
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "status": {
                                    "type": "integer",
                                    "description": "HTTP status code.",
                                    "examples": [
                                        401
                                    ]
                                },
                                "message": {
                                    "type": "string",
                                    "description": "Error overview."
                                }
                            },
                            "required": [
                                "status",
                                "message"
                            ]
                        }
                    }
                }
            }
        }
    }
}