postman_collection.json

{
	"info": {
		"name": "ID OCR Engine - HF Spaces",
		"description": "OCR microservice deployed on Hugging Face Spaces.\n\nSupports 3 document types:\n- SA Smart Card (sa_id_card)\n- SA Green Book (sa_id_book)\n- Passport (passport)\n\nSet the `base_url` variable to your HF Space URL.",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
	},
	"variable": [
		{
			"key": "base_url",
			"value": "https://itkes-id-ocr-engine.hf.space",
			"type": "string"
		},
		{
			"key": "api_key",
			"value": "",
			"type": "string",
			"description": "Leave empty if OCR_API_KEY is not set on the server"
		}
	],
	"auth": {
		"type": "apikey",
		"apikey": [
			{
				"key": "key",
				"value": "X-API-Key",
				"type": "string"
			},
			{
				"key": "value",
				"value": "{{api_key}}",
				"type": "string"
			},
			{
				"key": "in",
				"value": "header",
				"type": "string"
			}
		]
	},
	"item": [
		{
			"name": "Health & Status",
			"item": [
				{
					"name": "Health Check",
					"request": {
						"method": "GET",
						"header": [],
						"url": {
							"raw": "{{base_url}}/health",
							"host": ["{{base_url}}"],
							"path": ["health"]
						},
						"description": "Check if the service is healthy. No auth required."
					}
				},
				{
					"name": "Warm Up Models",
					"request": {
						"method": "GET",
						"header": [],
						"url": {
							"raw": "{{base_url}}/warm",
							"host": ["{{base_url}}"],
							"path": ["warm"]
						},
						"description": "Warm up VLM, PaddleOCR, and MRZ models. Call before first OCR request to avoid cold start. No auth required."
					}
				},
				{
					"name": "Dashboard (HTML)",
					"request": {
						"method": "GET",
						"header": [],
						"url": {
							"raw": "{{base_url}}/",
							"host": ["{{base_url}}"],
							"path": [""]
						},
						"description": "Load the web dashboard UI."
					}
				}
			]
		},
		{
			"name": "OCR - SA Smart Card",
			"item": [
				{
					"name": "SA Smart Card - Front Only",
					"request": {
						"method": "POST",
						"header": [],
						"body": {
							"mode": "formdata",
							"formdata": [
								{
									"key": "front",
									"type": "file",
									"src": "",
									"description": "Front of SA smart card (required)"
								},
								{
									"key": "doc_type",
									"value": "sa_id_card",
									"type": "text"
								}
							]
						},
						"url": {
							"raw": "{{base_url}}/api/ocr",
							"host": ["{{base_url}}"],
							"path": ["api", "ocr"]
						},
						"description": "Process front of SA smart card. Returns: id_number, surname, names, date_of_birth, sex, nationality, country_of_birth, citizenship_status."
					}
				},
				{
					"name": "SA Smart Card - Front + Back",
					"request": {
						"method": "POST",
						"header": [],
						"body": {
							"mode": "formdata",
							"formdata": [
								{
									"key": "front",
									"type": "file",
									"src": "",
									"description": "Front of SA smart card (required)"
								},
								{
									"key": "back",
									"type": "file",
									"src": "",
									"description": "Back of SA smart card with PDF417 barcode (optional)"
								},
								{
									"key": "doc_type",
									"value": "sa_id_card",
									"type": "text"
								}
							]
						},
						"url": {
							"raw": "{{base_url}}/api/ocr",
							"host": ["{{base_url}}"],
							"path": ["api", "ocr"]
						},
						"description": "Process front + back of SA smart card. Back image provides PDF417 barcode for 100% accurate extraction. Returns barcode_data in response."
					}
				}
			]
		},
		{
			"name": "OCR - SA Green Book",
			"item": [
				{
					"name": "SA Green Book",
					"request": {
						"method": "POST",
						"header": [],
						"body": {
							"mode": "formdata",
							"formdata": [
								{
									"key": "front",
									"type": "file",
									"src": "",
									"description": "Front page of SA green ID book (required)"
								},
								{
									"key": "doc_type",
									"value": "sa_id_book",
									"type": "text"
								}
							]
						},
						"url": {
							"raw": "{{base_url}}/api/ocr",
							"host": ["{{base_url}}"],
							"path": ["api", "ocr"]
						},
						"description": "Process SA green ID book. No back image accepted (green books have no barcode). Returns: id_number, surname, names, date_of_birth, sex, nationality, country_of_birth, citizenship_status."
					}
				}
			]
		},
		{
			"name": "OCR - Passport",
			"item": [
				{
					"name": "Passport",
					"request": {
						"method": "POST",
						"header": [],
						"body": {
							"mode": "formdata",
							"formdata": [
								{
									"key": "front",
									"type": "file",
									"src": "",
									"description": "Passport photo page (required)"
								},
								{
									"key": "doc_type",
									"value": "passport",
									"type": "text"
								}
							]
						},
						"url": {
							"raw": "{{base_url}}/api/ocr",
							"host": ["{{base_url}}"],
							"path": ["api", "ocr"]
						},
						"description": "Process passport (any country). Uses MRZ + VLM extraction. Returns: passport_number, surname, given_names, date_of_birth, sex, nationality, expiry_date, issuing_country. SA passports also return id_number."
					}
				}
			]
		},
		{
			"name": "Error Cases",
			"item": [
				{
					"name": "Missing doc_type",
					"request": {
						"method": "POST",
						"header": [],
						"body": {
							"mode": "formdata",
							"formdata": [
								{
									"key": "front",
									"type": "file",
									"src": ""
								}
							]
						},
						"url": {
							"raw": "{{base_url}}/api/ocr",
							"host": ["{{base_url}}"],
							"path": ["api", "ocr"]
						},
						"description": "Should return 400: doc_type is required."
					}
				},
				{
					"name": "Invalid doc_type",
					"request": {
						"method": "POST",
						"header": [],
						"body": {
							"mode": "formdata",
							"formdata": [
								{
									"key": "front",
									"type": "file",
									"src": ""
								},
								{
									"key": "doc_type",
									"value": "drivers_license",
									"type": "text"
								}
							]
						},
						"url": {
							"raw": "{{base_url}}/api/ocr",
							"host": ["{{base_url}}"],
							"path": ["api", "ocr"]
						},
						"description": "Should return 400: Invalid doc_type."
					}
				},
				{
					"name": "Back image with non-sa_id_card",
					"request": {
						"method": "POST",
						"header": [],
						"body": {
							"mode": "formdata",
							"formdata": [
								{
									"key": "front",
									"type": "file",
									"src": ""
								},
								{
									"key": "back",
									"type": "file",
									"src": ""
								},
								{
									"key": "doc_type",
									"value": "passport",
									"type": "text"
								}
							]
						},
						"url": {
							"raw": "{{base_url}}/api/ocr",
							"host": ["{{base_url}}"],
							"path": ["api", "ocr"]
						},
						"description": "Should return 400: Back image is only accepted for doc_type=sa_id_card."
					}
				},
				{
					"name": "No image uploaded",
					"request": {
						"method": "POST",
						"header": [],
						"body": {
							"mode": "formdata",
							"formdata": [
								{
									"key": "doc_type",
									"value": "sa_id_card",
									"type": "text"
								}
							]
						},
						"url": {
							"raw": "{{base_url}}/api/ocr",
							"host": ["{{base_url}}"],
							"path": ["api", "ocr"]
						},
						"description": "Should return 400: No front image uploaded."
					}
				},
				{
					"name": "Legacy 'file' key (backwards compat)",
					"request": {
						"method": "POST",
						"header": [],
						"body": {
							"mode": "formdata",
							"formdata": [
								{
									"key": "file",
									"type": "file",
									"src": "",
									"description": "Legacy key name — treated as 'front'"
								},
								{
									"key": "doc_type",
									"value": "sa_id_card",
									"type": "text"
								}
							]
						},
						"url": {
							"raw": "{{base_url}}/api/ocr",
							"host": ["{{base_url}}"],
							"path": ["api", "ocr"]
						},
						"description": "Test backwards compatibility: 'file' key is accepted as alias for 'front'."
					}
				}
			]
		}
	]
}