{
    "openapi": "3.0.3",
    "info": {
        "title": "Driving Licence Checking API",
        "version": "1.0.0",
        "description": "Check a UK driving licence using the holder's licence number and a DVLA \"view your driving licence\" share code. Returns the driving status, validity dates, photocard expiry, full entitlements and any penalty-point endorsements.\n\nBuilt for rental, fleet, insurance and gig-economy onboarding where you need to confirm someone can legally drive before handing over the keys."
    },
    "servers": [
        {
            "url": "https://vehiclematic.com/products/driving-licence-checking-service/api/live",
            "description": "Live"
        }
    ],
    "security": [
        {
            "ApiKeyAuth": []
        }
    ],
    "tags": [
        {
            "name": "Licence",
            "description": "Check a UK driving licence by licence number and DVLA share code."
        }
    ],
    "paths": {
        "/check": {
            "post": {
                "tags": [
                    "Licence"
                ],
                "operationId": "check",
                "summary": "Check a driving licence",
                "description": "Verifies a UK driving licence using the holder's licence number and a DVLA \"view your driving licence\" share code. Costs \u00a31.50 per lookup on Tier 1, down to \u00a31.10 on the largest top-up tier.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "licence_number",
                                    "share_code"
                                ],
                                "properties": {
                                    "licence_number": {
                                        "type": "string",
                                        "description": "UK (16-char) or Republic of Ireland (10-digit) driving licence number.",
                                        "example": "MORGA657054SM9IJ"
                                    },
                                    "share_code": {
                                        "type": "string",
                                        "description": "The 8-character DVLA share code (case-sensitive) obtained from \"Share your driving record\".",
                                        "example": "Ab12Cd34"
                                    }
                                }
                            },
                            "example": {
                                "licence_number": "MORGA657054SM9IJ",
                                "share_code": "Ab12Cd34"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful check.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "licence_number": {
                                                    "type": "string"
                                                },
                                                "driving_status": {
                                                    "type": "string"
                                                },
                                                "valid_from": {
                                                    "type": "string"
                                                },
                                                "valid_to": {
                                                    "type": "string"
                                                },
                                                "photocard_expiry": {
                                                    "type": "string"
                                                },
                                                "entitlements": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "category": {
                                                                "type": "string"
                                                            },
                                                            "valid_from": {
                                                                "type": "string"
                                                            },
                                                            "valid_to": {
                                                                "type": "string"
                                                            }
                                                        }
                                                    }
                                                },
                                                "endorsements": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "code": {
                                                                "type": "string"
                                                            },
                                                            "points": {
                                                                "type": "integer"
                                                            },
                                                            "offence_date": {
                                                                "type": "string"
                                                            },
                                                            "valid_to": {
                                                                "type": "string"
                                                            }
                                                        }
                                                    }
                                                },
                                                "total_points": {
                                                    "type": "integer"
                                                },
                                                "total_offences": {
                                                    "type": "integer"
                                                }
                                            }
                                        },
                                        "credit_balance": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "example": {
                                    "data": {
                                        "licence_number": "MORGA657054SM9IJ",
                                        "driving_status": "Current full licence",
                                        "valid_from": "2017-09-14",
                                        "valid_to": "2027-09-13",
                                        "photocard_expiry": "2027-09-13",
                                        "entitlements": [
                                            {
                                                "category": "B",
                                                "valid_from": "2017-09-14",
                                                "valid_to": "2027-09-13"
                                            },
                                            {
                                                "category": "BE",
                                                "valid_from": "2017-09-14",
                                                "valid_to": "2027-09-13"
                                            }
                                        ],
                                        "endorsements": [
                                            {
                                                "code": "SP30",
                                                "points": 3,
                                                "offence_date": "2024-06-02",
                                                "valid_to": "2028-06-02"
                                            }
                                        ],
                                        "total_points": 3,
                                        "total_offences": 1
                                    },
                                    "credit_balance": 490
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "Insufficient credits.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                },
                                "example": {
                                    "error": true,
                                    "message": "Insufficient credits.",
                                    "credit_balance": 0
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "This API key is not authorised for this product.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                },
                                "example": {
                                    "error": true,
                                    "message": "This API key is not authorised for this product."
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Missing/invalid input, or the licence could not be verified.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                },
                                "example": {
                                    "error": true,
                                    "message": "A valid driving licence number is required."
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "ApiKeyAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "X-VEHICLEMATIC-KEY",
                "description": "Your API key. Create one on the API access page in your portal."
            }
        }
    }
}