{ "item": [ { "name": "connect", "description": "", "item": [ { "id": "a92b8632-07b3-40ab-8bec-91e2aae5ebc5", "name": "Connect", "request": { "name": "Connect", "description": { "content": "Free key/health probe. Returns `200` if the key is active and the upstream search service is reachable. Designed to be hit on input focus in autocomplete UIs — it warms the worker and TLS connection so the first real query lands on a hot path. Doubles as a heartbeat. We use this in our integrations for optimising user experience. Free to use.", "type": "text/plain" }, "url": { "path": [ "connect" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "275361ce-782a-4a59-a57d-3b4efb19f049", "name": "Key is active and the service is healthy.", "originalRequest": { "url": { "path": [ "connect" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"meta\": {\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "4dbcf9a5-0765-42f4-a0a2-15bf3c9a38a5", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "connect" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"meta\": {\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b0c00f10-a6d4-488a-aa5b-c3a11ed00f49", "name": "Upstream search service unreachable.", "originalRequest": { "url": { "path": [ "connect" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Gateway", "code": 502, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"meta\": {\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "address", "description": "", "item": [ { "name": "search", "description": "", "item": [ { "id": "f1b893d8-7111-4088-976a-2d68ae09ed31", "name": "Search", "request": { "name": "Search", "description": { "content": "Free, single-line autocomplete over UK PAF + BFPO. Feed it whatever the user has typed — building, street, postcode, organisation, or any combination — and get back a slim `{ udprn, suggestion }` list of matches. To pull the full address for the one the user picks, call `/address/udprn/{udprn}`. Free to use.\n\nSearch is backed by a Typesense index replicated next to the Worker, so typeahead queries usually resolve in single-digit milliseconds before network.", "type": "text/plain" }, "url": { "path": [ "address", "search" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "(Required) Search string (free-form: building, street, postcode, organisation).", "type": "text/plain" }, "key": "q", "value": "" }, { "disabled": false, "description": { "content": "Max results to return. Default 10, max 50.", "type": "text/plain" }, "key": "max_results", "value": "10" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "dffd2c5d-b3a1-4bee-9538-80149ad39e43", "name": "Search results (zero or more matches).", "originalRequest": { "url": { "path": [ "address", "search" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "(Required) Search string (free-form: building, street, postcode, organisation).", "type": "text/plain" }, "key": "q", "value": "" }, { "disabled": false, "description": { "content": "Max results to return. Default 10, max 50.", "type": "text/plain" }, "key": "max_results", "value": "10" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"results\": [\n {\n \"udprn\": \"\",\n \"suggestion\": \"\"\n },\n {\n \"udprn\": \"\",\n \"suggestion\": \"\"\n }\n ],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "dd43f772-1658-4aff-8d43-8233f9a70583", "name": "Bad request — validation failed.", "originalRequest": { "url": { "path": [ "address", "search" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "(Required) Search string (free-form: building, street, postcode, organisation).", "type": "text/plain" }, "key": "q", "value": "" }, { "disabled": false, "description": { "content": "Max results to return. Default 10, max 50.", "type": "text/plain" }, "key": "max_results", "value": "10" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "fb0968da-14ea-4a2d-bc0d-65fb6809a09f", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "address", "search" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "(Required) Search string (free-form: building, street, postcode, organisation).", "type": "text/plain" }, "key": "q", "value": "" }, { "disabled": false, "description": { "content": "Max results to return. Default 10, max 50.", "type": "text/plain" }, "key": "max_results", "value": "10" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8c0c1aed-14b2-4611-883a-b6ac28d2217f", "name": "Out of credit. Top up to resume billable requests.", "originalRequest": { "url": { "path": [ "address", "search" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "(Required) Search string (free-form: building, street, postcode, organisation).", "type": "text/plain" }, "key": "q", "value": "" }, { "disabled": false, "description": { "content": "Max results to return. Default 10, max 50.", "type": "text/plain" }, "key": "max_results", "value": "10" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Payment Required", "code": 402, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "00a0fd45-64ad-4b99-a085-77d6089bd456", "name": "Forbidden — service disabled, or origin/IP not allowed for this key.", "originalRequest": { "url": { "path": [ "address", "search" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "(Required) Search string (free-form: building, street, postcode, organisation).", "type": "text/plain" }, "key": "q", "value": "" }, { "disabled": false, "description": { "content": "Max results to return. Default 10, max 50.", "type": "text/plain" }, "key": "max_results", "value": "10" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "64185860-7940-442b-b6cc-46a769c9dbab", "name": "Rate limit exceeded.", "originalRequest": { "url": { "path": [ "address", "search" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "(Required) Search string (free-form: building, street, postcode, organisation).", "type": "text/plain" }, "key": "q", "value": "" }, { "disabled": false, "description": { "content": "Max results to return. Default 10, max 50.", "type": "text/plain" }, "key": "max_results", "value": "10" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "760976f2-6004-4ada-b343-cbd4f53e536f", "name": "Server error.", "originalRequest": { "url": { "path": [ "address", "search" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "(Required) Search string (free-form: building, street, postcode, organisation).", "type": "text/plain" }, "key": "q", "value": "" }, { "disabled": false, "description": { "content": "Max results to return. Default 10, max 50.", "type": "text/plain" }, "key": "max_results", "value": "10" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "postcode", "description": "", "item": [ { "name": "{postcode}", "description": "", "item": [ { "id": "d33d463a-7dae-4c71-bfd2-54709f2cbe0b", "name": "Postcode", "request": { "name": "Postcode", "description": { "content": "Returns every PAF delivery point at the given postcode, ordered by building number. Whitespace and case are normalised, so `w1g8yw`, `W1G 8YW`, and `w1g 8yw` all resolve to the same record. Billable on a hit. A syntactically valid postcode with no delivery points (a withdrawn postcode, or one outside PAF's coverage) returns `200` with `results: []` and is not charged.", "type": "text/plain" }, "url": { "path": [ "address", "postcode", ":postcode" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Max results to return. Default 100, max 100. UK PAF postcodes max out at ~100 delivery points so a single page covers every postcode.", "type": "text/plain" }, "key": "max_results", "value": "100" } ], "variable": [ { "type": "any", "value": "", "key": "postcode", "disabled": false, "description": { "content": "(Required) UK postcode. Whitespace and case are normalised.", "type": "text/plain" } } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "7fb06661-30cc-4f52-93ef-d50e3ce0e91a", "name": "Addresses at the postcode (empty array if none).", "originalRequest": { "url": { "path": [ "address", "postcode", ":postcode" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Max results to return. Default 100, max 100. UK PAF postcodes max out at ~100 delivery points so a single page covers every postcode.", "type": "text/plain" }, "key": "max_results", "value": "100" } ], "variable": [ { "disabled": false, "description": { "content": "(Required) UK postcode. Whitespace and case are normalised.", "type": "text/plain" }, "type": "any", "value": "", "key": "postcode" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"results\": [\n {\n \"udprn\": \"\",\n \"postcode\": \"\",\n \"postcode_outward\": \"\",\n \"postcode_inward\": \"\",\n \"postcode_type\": \"\",\n \"address_line_1\": \"\",\n \"address_line_2\": \"\",\n \"address_line_3\": \"\",\n \"post_town\": \"\",\n \"organisation_name\": \"\",\n \"department_name\": \"\",\n \"building_name\": \"\",\n \"building_number\": \"\",\n \"sub_building_name\": \"\",\n \"po_box\": \"\",\n \"thoroughfare\": \"\",\n \"dependent_thoroughfare\": \"\",\n \"dependent_locality\": \"\",\n \"double_dependent_locality\": \"\",\n \"delivery_point_suffix\": \"\",\n \"country\": \"\",\n \"county\": \"\",\n \"district\": \"\",\n \"ward\": \"\",\n \"latitude\": \"\",\n \"longitude\": \"\",\n \"eastings\": \"\",\n \"northings\": \"\"\n },\n {\n \"udprn\": \"\",\n \"postcode\": \"\",\n \"postcode_outward\": \"\",\n \"postcode_inward\": \"\",\n \"postcode_type\": \"\",\n \"address_line_1\": \"\",\n \"address_line_2\": \"\",\n \"address_line_3\": \"\",\n \"post_town\": \"\",\n \"organisation_name\": \"\",\n \"department_name\": \"\",\n \"building_name\": \"\",\n \"building_number\": \"\",\n \"sub_building_name\": \"\",\n \"po_box\": \"\",\n \"thoroughfare\": \"\",\n \"dependent_thoroughfare\": \"\",\n \"dependent_locality\": \"\",\n \"double_dependent_locality\": \"\",\n \"delivery_point_suffix\": \"\",\n \"country\": \"\",\n \"county\": \"\",\n \"district\": \"\",\n \"ward\": \"\",\n \"latitude\": \"\",\n \"longitude\": \"\",\n \"eastings\": \"\",\n \"northings\": \"\"\n }\n ],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "71c38eea-8a29-440a-a3d9-1ce134929737", "name": "Bad request — validation failed.", "originalRequest": { "url": { "path": [ "address", "postcode", ":postcode" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Max results to return. Default 100, max 100. UK PAF postcodes max out at ~100 delivery points so a single page covers every postcode.", "type": "text/plain" }, "key": "max_results", "value": "100" } ], "variable": [ { "disabled": false, "description": { "content": "(Required) UK postcode. Whitespace and case are normalised.", "type": "text/plain" }, "type": "any", "value": "", "key": "postcode" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "84e39144-8766-4da3-a931-488c239fd0fd", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "address", "postcode", ":postcode" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Max results to return. Default 100, max 100. UK PAF postcodes max out at ~100 delivery points so a single page covers every postcode.", "type": "text/plain" }, "key": "max_results", "value": "100" } ], "variable": [ { "disabled": false, "description": { "content": "(Required) UK postcode. Whitespace and case are normalised.", "type": "text/plain" }, "type": "any", "value": "", "key": "postcode" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "1920de66-c72e-4d00-8b61-b93af70a32c9", "name": "Out of credit. Top up to resume billable requests.", "originalRequest": { "url": { "path": [ "address", "postcode", ":postcode" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Max results to return. Default 100, max 100. UK PAF postcodes max out at ~100 delivery points so a single page covers every postcode.", "type": "text/plain" }, "key": "max_results", "value": "100" } ], "variable": [ { "disabled": false, "description": { "content": "(Required) UK postcode. Whitespace and case are normalised.", "type": "text/plain" }, "type": "any", "value": "", "key": "postcode" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Payment Required", "code": 402, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "fbcb1a7c-f9cd-40cd-a11c-9c826cf50c71", "name": "Forbidden — service disabled, or origin/IP not allowed for this key.", "originalRequest": { "url": { "path": [ "address", "postcode", ":postcode" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Max results to return. Default 100, max 100. UK PAF postcodes max out at ~100 delivery points so a single page covers every postcode.", "type": "text/plain" }, "key": "max_results", "value": "100" } ], "variable": [ { "disabled": false, "description": { "content": "(Required) UK postcode. Whitespace and case are normalised.", "type": "text/plain" }, "type": "any", "value": "", "key": "postcode" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "01a8fb87-5683-4604-b08e-8fec4287d54b", "name": "Rate limit exceeded.", "originalRequest": { "url": { "path": [ "address", "postcode", ":postcode" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Max results to return. Default 100, max 100. UK PAF postcodes max out at ~100 delivery points so a single page covers every postcode.", "type": "text/plain" }, "key": "max_results", "value": "100" } ], "variable": [ { "disabled": false, "description": { "content": "(Required) UK postcode. Whitespace and case are normalised.", "type": "text/plain" }, "type": "any", "value": "", "key": "postcode" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ab1aa3be-a1a8-44d3-a805-9eb7ea00f9e5", "name": "Server error.", "originalRequest": { "url": { "path": [ "address", "postcode", ":postcode" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Max results to return. Default 100, max 100. UK PAF postcodes max out at ~100 delivery points so a single page covers every postcode.", "type": "text/plain" }, "key": "max_results", "value": "100" } ], "variable": [ { "disabled": false, "description": { "content": "(Required) UK postcode. Whitespace and case are normalised.", "type": "text/plain" }, "type": "any", "value": "", "key": "postcode" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] } ] }, { "name": "udprn", "description": "", "item": [ { "name": "{udprn}", "description": "", "item": [ { "id": "6e697be6-00cd-459e-832b-5b0fb28c731f", "name": "UDPRN", "request": { "name": "UDPRN", "description": { "content": "Looks up a single delivery point by its Unique Delivery Point Reference Number — Royal Mail's stable per-address ID. Use this after `/address/search` to fetch the full record for the address the user picked, or to refresh a stored record. Billable on a hit. A UDPRN that doesn't exist returns `404`; misses are not charged.", "type": "text/plain" }, "url": { "path": [ "address", "udprn", ":udprn" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "udprn", "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" } } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "6fc0ec60-5eea-4d43-bb74-9f5eeac6c7da", "name": "The matching address.", "originalRequest": { "url": { "path": [ "address", "udprn", ":udprn" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "udprn" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"results\": [\n {\n \"udprn\": \"\",\n \"postcode\": \"\",\n \"postcode_outward\": \"\",\n \"postcode_inward\": \"\",\n \"postcode_type\": \"\",\n \"address_line_1\": \"\",\n \"address_line_2\": \"\",\n \"address_line_3\": \"\",\n \"post_town\": \"\",\n \"organisation_name\": \"\",\n \"department_name\": \"\",\n \"building_name\": \"\",\n \"building_number\": \"\",\n \"sub_building_name\": \"\",\n \"po_box\": \"\",\n \"thoroughfare\": \"\",\n \"dependent_thoroughfare\": \"\",\n \"dependent_locality\": \"\",\n \"double_dependent_locality\": \"\",\n \"delivery_point_suffix\": \"\",\n \"country\": \"\",\n \"county\": \"\",\n \"district\": \"\",\n \"ward\": \"\",\n \"latitude\": \"\",\n \"longitude\": \"\",\n \"eastings\": \"\",\n \"northings\": \"\"\n },\n {\n \"udprn\": \"\",\n \"postcode\": \"\",\n \"postcode_outward\": \"\",\n \"postcode_inward\": \"\",\n \"postcode_type\": \"\",\n \"address_line_1\": \"\",\n \"address_line_2\": \"\",\n \"address_line_3\": \"\",\n \"post_town\": \"\",\n \"organisation_name\": \"\",\n \"department_name\": \"\",\n \"building_name\": \"\",\n \"building_number\": \"\",\n \"sub_building_name\": \"\",\n \"po_box\": \"\",\n \"thoroughfare\": \"\",\n \"dependent_thoroughfare\": \"\",\n \"dependent_locality\": \"\",\n \"double_dependent_locality\": \"\",\n \"delivery_point_suffix\": \"\",\n \"country\": \"\",\n \"county\": \"\",\n \"district\": \"\",\n \"ward\": \"\",\n \"latitude\": \"\",\n \"longitude\": \"\",\n \"eastings\": \"\",\n \"northings\": \"\"\n }\n ],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a98c8a5e-0870-4077-aacd-bb70e828881b", "name": "Bad request — validation failed.", "originalRequest": { "url": { "path": [ "address", "udprn", ":udprn" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "udprn" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "085f0dea-f8c3-4b7f-8b0a-b6662b7d2429", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "address", "udprn", ":udprn" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "udprn" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ab828e3e-cb75-436e-b398-2b6b68f5115d", "name": "Out of credit. Top up to resume billable requests.", "originalRequest": { "url": { "path": [ "address", "udprn", ":udprn" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "udprn" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Payment Required", "code": 402, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "da2f836c-e526-4427-aa5a-878e4ac4c4fe", "name": "Forbidden — service disabled, or origin/IP not allowed for this key.", "originalRequest": { "url": { "path": [ "address", "udprn", ":udprn" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "udprn" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "78b6492d-a188-4147-9aef-8de1160178e9", "name": "UDPRN not found.", "originalRequest": { "url": { "path": [ "address", "udprn", ":udprn" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "udprn" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d81f0fd7-fcea-4ad3-8c89-c37c3922848f", "name": "Rate limit exceeded.", "originalRequest": { "url": { "path": [ "address", "udprn", ":udprn" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "udprn" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e1dc584c-a0da-484e-bb9b-5064c11f1e6f", "name": "Server error.", "originalRequest": { "url": { "path": [ "address", "udprn", ":udprn" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "udprn" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] } ] } ] }, { "name": "email", "description": "", "item": [ { "name": "{address}", "description": "", "item": [ { "id": "747727d4-13a6-4d96-a625-8766614d231e", "name": "Validate address", "request": { "name": "Validate address", "description": { "content": "Runs a five-stage check on the address:\n\n1. **Syntax** — RFC 5322 parsing, including IDN and quoted local-parts.\n2. **Typo correction** — flags likely fat-finger domains (`gnail.com` → `gmail.com`) via `didYouMean`.\n3. **Classification** — disposable provider, role account (`info@`, `support@`), free provider (Gmail / Outlook / Yahoo).\n4. **MX lookup** — confirms the domain has mail servers configured.\n5. **Mailbox probe** — where the mail server allows it, an SMTP-level check on whether the specific mailbox accepts mail (catch-all detection included).\n\nEach signal is returned independently alongside an aggregated `deliverability` verdict (`deliverable`, `undeliverable`, `risky`, `unknown`, `invalid`) so you can apply your own thresholds. Invalid syntax still returns `200` with `isValidSyntax: false` and `deliverability: \"invalid\"` — there's no `400` for unparseable input.", "type": "text/plain" }, "url": { "path": [ "email", ":address" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "address", "disabled": false, "description": { "content": "(Required) Email address to validate. URL-encode the `@`.", "type": "text/plain" } } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "ed9e6794-7d1a-44e9-990c-0e3baecb0f44", "name": "Validation verdict.", "originalRequest": { "url": { "path": [ "email", ":address" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Email address to validate. URL-encode the `@`.", "type": "text/plain" }, "type": "any", "value": "", "key": "address" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"results\": [\n {\n \"email\": \"\",\n \"isValidSyntax\": \"\",\n \"didYouMean\": \"\",\n \"isDisposable\": \"\",\n \"isFreeProvider\": \"\",\n \"isRoleAccount\": \"\",\n \"mxFound\": \"\",\n \"smtpCheck\": \"\",\n \"isCatchAll\": \"\",\n \"deliverability\": \"unknown\"\n },\n {\n \"email\": \"\",\n \"isValidSyntax\": \"\",\n \"didYouMean\": \"\",\n \"isDisposable\": \"\",\n \"isFreeProvider\": \"\",\n \"isRoleAccount\": \"\",\n \"mxFound\": \"\",\n \"smtpCheck\": \"\",\n \"isCatchAll\": \"\",\n \"deliverability\": \"invalid\"\n }\n ],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "51d69da5-a318-4bbc-8743-abceba415f4d", "name": "Bad request — validation failed.", "originalRequest": { "url": { "path": [ "email", ":address" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Email address to validate. URL-encode the `@`.", "type": "text/plain" }, "type": "any", "value": "", "key": "address" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "404c3a5e-fcfb-410f-b98d-f339e01d759c", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "email", ":address" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Email address to validate. URL-encode the `@`.", "type": "text/plain" }, "type": "any", "value": "", "key": "address" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8d7d9a4d-7dec-4e1c-9c58-34339cf28e6a", "name": "Out of credit. Top up to resume billable requests.", "originalRequest": { "url": { "path": [ "email", ":address" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Email address to validate. URL-encode the `@`.", "type": "text/plain" }, "type": "any", "value": "", "key": "address" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Payment Required", "code": 402, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "66efe1d8-1a5d-4324-9db5-f920c96433d9", "name": "Forbidden — service disabled, or origin/IP not allowed for this key.", "originalRequest": { "url": { "path": [ "email", ":address" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Email address to validate. URL-encode the `@`.", "type": "text/plain" }, "type": "any", "value": "", "key": "address" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "11c7c717-367a-46b0-85cb-f1daf20a3144", "name": "Rate limit exceeded.", "originalRequest": { "url": { "path": [ "email", ":address" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Email address to validate. URL-encode the `@`.", "type": "text/plain" }, "type": "any", "value": "", "key": "address" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e5f80ed4-1d6b-40f8-b03e-119f2ffff3dc", "name": "Server error.", "originalRequest": { "url": { "path": [ "email", ":address" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Email address to validate. URL-encode the `@`.", "type": "text/plain" }, "type": "any", "value": "", "key": "address" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] } ] }, { "name": "phone", "description": "", "item": [ { "name": "{number}", "description": "", "item": [ { "id": "03022e31-cea5-4141-b900-c1d07e900d7c", "name": "Validate number", "request": { "name": "Validate number", "description": { "content": "Parses the supplied number with libphonenumber (E.164, international, or national — all accepted). On a valid parse, runs a live HLR (Home Location Register) lookup against the carrier network and returns:\n\n- **Current carrier** — the network the number is on right now, even after porting.\n- **Original carrier** — the network it was issued on.\n- **Ported flag** — whether the number has moved network.\n- **Reachable flag** — whether the number is currently powered on and attached to a network.\n- **MCC / MNC** — the standard mobile country and network codes.\n\nPass numbers in E.164 (`+447700900123`) for unambiguous results — URL-encode the leading `+` as `%2B`. Other formats work but rely on libphonenumber's heuristics for country detection. Invalid numbers return `200` with `isValid: false` and the parsed fields it could derive still populated.", "type": "text/plain" }, "url": { "path": [ "phone", ":number" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "number", "disabled": false, "description": { "content": "(Required) Phone number in E.164 (`+447700900123`) or any format libphonenumber can parse. URL-encode the leading `+` as `%2B`.", "type": "text/plain" } } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "4f319db5-f04f-412c-a28a-910043abb8bb", "name": "Validation + lookup verdict.", "originalRequest": { "url": { "path": [ "phone", ":number" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Phone number in E.164 (`+447700900123`) or any format libphonenumber can parse. URL-encode the leading `+` as `%2B`.", "type": "text/plain" }, "type": "any", "value": "", "key": "number" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"results\": [\n {\n \"number\": \"\",\n \"isValid\": \"\",\n \"isPossible\": \"\",\n \"type\": \"\",\n \"countryCode\": \"\",\n \"countryName\": \"\",\n \"nationalFormat\": \"\",\n \"internationalFormat\": \"\",\n \"e164Format\": \"\",\n \"originalCarrier\": \"\",\n \"currentCarrier\": \"\",\n \"isPorted\": \"\",\n \"isReachable\": \"\",\n \"mcc\": \"\",\n \"mnc\": \"\",\n \"level\": \"\",\n \"lookupError\": \"\"\n },\n {\n \"number\": \"\",\n \"isValid\": \"\",\n \"isPossible\": \"\",\n \"type\": \"\",\n \"countryCode\": \"\",\n \"countryName\": \"\",\n \"nationalFormat\": \"\",\n \"internationalFormat\": \"\",\n \"e164Format\": \"\",\n \"originalCarrier\": \"\",\n \"currentCarrier\": \"\",\n \"isPorted\": \"\",\n \"isReachable\": \"\",\n \"mcc\": \"\",\n \"mnc\": \"\",\n \"level\": \"\",\n \"lookupError\": \"\"\n }\n ],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f260f034-214b-4543-ac65-8360bb18a695", "name": "Bad request — validation failed.", "originalRequest": { "url": { "path": [ "phone", ":number" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Phone number in E.164 (`+447700900123`) or any format libphonenumber can parse. URL-encode the leading `+` as `%2B`.", "type": "text/plain" }, "type": "any", "value": "", "key": "number" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "16dd843f-f564-4b92-a027-0e941b51e5cd", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "phone", ":number" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Phone number in E.164 (`+447700900123`) or any format libphonenumber can parse. URL-encode the leading `+` as `%2B`.", "type": "text/plain" }, "type": "any", "value": "", "key": "number" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d805b076-0659-44fe-ac04-a52aa026fb7b", "name": "Out of credit. Top up to resume billable requests.", "originalRequest": { "url": { "path": [ "phone", ":number" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Phone number in E.164 (`+447700900123`) or any format libphonenumber can parse. URL-encode the leading `+` as `%2B`.", "type": "text/plain" }, "type": "any", "value": "", "key": "number" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Payment Required", "code": 402, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d389e23d-e9b1-45c6-b0ac-5005fe57073a", "name": "Forbidden — service disabled, or origin/IP not allowed for this key.", "originalRequest": { "url": { "path": [ "phone", ":number" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Phone number in E.164 (`+447700900123`) or any format libphonenumber can parse. URL-encode the leading `+` as `%2B`.", "type": "text/plain" }, "type": "any", "value": "", "key": "number" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d14475d5-bc49-4d95-98ac-bb426c9519c2", "name": "Rate limit exceeded.", "originalRequest": { "url": { "path": [ "phone", ":number" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Phone number in E.164 (`+447700900123`) or any format libphonenumber can parse. URL-encode the leading `+` as `%2B`.", "type": "text/plain" }, "type": "any", "value": "", "key": "number" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b9092a07-fa58-41c9-bbd7-b97feca68b8f", "name": "Server error.", "originalRequest": { "url": { "path": [ "phone", ":number" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Phone number in E.164 (`+447700900123`) or any format libphonenumber can parse. URL-encode the leading `+` as `%2B`.", "type": "text/plain" }, "type": "any", "value": "", "key": "number" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Your Postio API key. Get one in the dashboard.", "type": "text/plain" }, "key": "x-api-key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"error\": \"\",\n \"results\": [],\n \"meta\": {\n \"countResults\": \"\",\n \"requestId\": \"\",\n \"performance\": {\n \"workerMs\": \"\",\n \"lookupMs\": \"\"\n }\n },\n \"details\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] } ] } ], "event": [], "variable": [ { "key": "baseUrl", "value": "https://api.postio.co.uk/v1" } ], "info": { "_postman_id": "9fdd0a2e-b9fd-4e6f-9542-e5ad5c737db8", "name": "Postio API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": { "content": "Postio is a UK validation API for **addresses**, **emails**, and **phone numbers** running on Cloudflare's edge so requests are answered close to wherever your users are.\n\nEvery endpoint is a `GET` returning JSON, served over HTTPS at `https://api.postio.co.uk/v1`.\n\nIf you can speak HTTP and parse JSON, you can integrate in under five minutes — sign up, copy your `pk_*` key from the dashboard, and you're away.\n\n## Authentication\n\nSend your key in the `x-api-key` header on every request:\n\n```bash\ncurl https://api.postio.co.uk/v1/address/search?q=57+wimpole+street \\\n -H \"x-api-key: YOUR_API_KEY\"\n```\n\nKeys are scoped per service (address / email / phone) and can be locked to specific origins or IP ranges in the dashboard. Treat them as secrets — don't ship them in client-side code unless the key is locked to your domains.\n\nMissing or invalid key → `401`. Key out of credit → `402`.\n\n## Rate limiting\n\nEach key is limited to **30 requests per second**. Bursts past that return `429` — back off and retry. Sustained abuse can result in the key being suspended. If you legitimately expect higher throughput, [get in touch](https://postio.co.uk/contact) and we'll raise the limit.\n\n\n## Versioning\n\nThe API is versioned by URL prefix — currently `/v1/`. Backwards-compatible changes (new endpoints, new optional parameters, new response fields) ship under the same version. Anything breaking gets a new prefix.\n\n## Response shape\n\nEvery response follows the same envelope:\n\n```json\n{\n \"success\": true,\n \"results\": [ /* one or more result objects */ ],\n \"meta\": {\n \"countResults\": 1,\n \"requestId\": \"dd273343-4597-4fa4-bcb6-c74a608c10dc\",\n \"performance\": { \"workerMs\": 15, \"lookupMs\": 12 }\n }\n}\n```\n\nOn error, `success` is `false`, `results` is empty, and a top-level `error` field carries a stable machine-readable code (`details` adds context for humans).\n\n`requestId` is worth logging — it's how we trace any request you raise with us.\n\n### Performance\n\nTwo numbers, both in milliseconds, both measured by the Worker itself:\n\n- **`workerMs`** — wall-clock at the edge, from the moment the\n request arrives at our Cloudflare Worker to the moment we hand the\n response back. This is the latency *we* control end-to-end.\n- **`lookupMs`** — the slice of `workerMs` spent in the upstream\n lookup (PAF index for address, MX resolution for email, HLR query\n for phone). Subtract `lookupMs` from `workerMs` and you've got the\n Worker's own compute — auth, rate-limiting, parsing, shaping the\n response.\n\nThe API runs on Cloudflare Workers from every edge location; the\naddress index is replicated next to the Worker. Most lookups settle\nin the low tens of milliseconds end-to-end, before your own network\nhop home.\n\n## Free vs billable\n\n`/connect` and `/address/search` are free, but monitored for abuse patterns. Everything else is billable **on a hit with results only** — a query that returns no match (e.g. a valid postcode with no delivery points) is `200` with an empty `results` array and is not charged.\n\n\n## Errors\n\nHTTP status conveys the outcome class:\n\n| Status | Meaning |\n| --- | --- |\n| `200` | Success — including \"no match\", which is still 200 |\n| `400` | Validation failed |\n| `401` | Missing or invalid API key |\n| `402` | Out of credit — top up to resume billable requests |\n| `403` | Service disabled, or origin/IP not allowed for this key |\n| `429` | Rate limit exceeded |\n| `5xx` | Server-side problem — safe to retry |\n\nEndpoint-specific errors are documented per endpoint below.\n\n\n## Contact\n\nAnything missing or broken? reach out to [technical support](https://postio.co.uk/contact).", "type": "text/plain" } } }