{"openapi":"3.1.0","info":{"title":"Postal API","version":"0.1.0","description":"Indian pincodes, world postal/ZIP codes, UK postcodes, IFSC, IBAN/BIC validation, geocoding and reverse geocoding, country dialing and emergency numbers.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://postal.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/postal/docs"},"termsOfService":"https://connectorbay.com/postal/terms"},"servers":[{"url":"https://postal.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/postal/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/pincode":{"post":{"operationId":"pincode","summary":"Indian PIN code → post offices (name, type, delivery status, district, division, region, state); or a post-office","description":"Indian PIN code → post offices (name, type, delivery status, district, division, region, state); or a post-office\n    name → matching offices and their pincodes. Use for \"which area is 411001\", \"pincode of Andheri East\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"6-digit Indian PIN code.","examples":["411001","110001"],"title":"Code"},"post_office":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Or a post-office / locality name to find its pincode.","examples":["Koregaon Park","Connaught Place"],"title":"Post Office"}},"title":"pincodeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/postal_code":{"post":{"operationId":"postal_code","summary":"Postal / ZIP code → place, state and coordinates in 60+ countries (US, CA, DE, FR, ES, IT, IN, BR, MX, JP, AU…),","description":"Postal / ZIP code → place, state and coordinates in 60+ countries (US, CA, DE, FR, ES, IT, IN, BR, MX, JP, AU…),\n    or place + state → its codes. Also validates the code's format for that country. Use for \"ZIP 95814\", \"PLZ 10115\",\n    \"zip codes of Sacramento CA\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country":{"description":"Country (ISO-2 or name).","examples":["US","Germany","IN"],"title":"Country","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Postal / ZIP code.","examples":["95814","10115"],"title":"Code"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Or: state/region code with a place name to find codes.","examples":["CA"],"title":"State"},"place":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Place name (with state) to find its codes.","examples":["Sacramento"],"title":"Place"}},"required":["country"],"title":"postal_codeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/uk_postcode":{"post":{"operationId":"uk_postcode","summary":"UK postcode lookup (country, region, district, ward, parish, constituency, coordinates), autocomplete a partial","description":"UK postcode lookup (country, region, district, ward, parish, constituency, coordinates), autocomplete a partial\n    postcode, outcode summary, or nearest postcodes to coordinates. Use for \"where is SW1A 1AA\", \"postcodes starting\n    EH1 2\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"postcode":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Full postcode.","examples":["SW1A 1AA","M1 1AE"],"title":"Postcode"},"partial":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Partial postcode to autocomplete.","examples":["SW1A 1","EH1"],"title":"Partial"},"outcode":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Outward code for an area summary.","examples":["SW1A","B1"],"title":"Outcode"},"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"With longitude: nearest postcodes.","title":"Latitude"},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Longitude"}},"title":"uk_postcodeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/ifsc":{"post":{"operationId":"ifsc","summary":"Indian bank branch from an IFSC: bank, branch, address, city/state, MICR, SWIFT, contact, and whether UPI, NEFT,","description":"Indian bank branch from an IFSC: bank, branch, address, city/state, MICR, SWIFT, contact, and whether UPI, NEFT,\n    RTGS and IMPS are enabled. Use for \"which branch is SBIN0000300\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"code":{"description":"11-character IFSC.","examples":["HDFC0000001","SBIN0000300"],"title":"Code","type":"string"}},"required":["code"],"title":"ifscArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/iban":{"post":{"operationId":"iban","summary":"Validate an IBAN (country length, mod-97 checksum, formatted groups, bank/branch/account split for GB, DE, FR,","description":"Validate an IBAN (country length, mod-97 checksum, formatted groups, bank/branch/account split for GB, DE, FR,\n    AE, SA) or format-check a BIC/SWIFT code. Use for \"is this IBAN right\", \"what bank is BIC DEUTDEFF\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"iban":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"IBAN to validate (spaces allowed).","examples":["GB82 WEST 1234 5698 7654 32","DE89 3704 0044 0532 0130 00"],"title":"Iban"},"bic":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Or a BIC/SWIFT code to format-check.","examples":["HDFCINBB","DEUTDEFF500"],"title":"Bic"}},"title":"ibanArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/geocode":{"post":{"operationId":"geocode","summary":"Address or place → coordinates and structured address parts including the postcode (OpenStreetMap Nominatim).","description":"Address or place → coordinates and structured address parts including the postcode (OpenStreetMap Nominatim).\n    Use for \"postcode of 10 Downing Street\", \"coordinates of Koregaon Park\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Address or place.","examples":["10 Downing Street, London","Koregaon Park, Pune","Eiffel Tower"],"title":"Query","type":"string"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Restrict to a country (ISO-2 or name).","title":"Country"},"limit":{"default":3,"maximum":5,"minimum":1,"title":"Limit","type":"integer"}},"required":["query"],"title":"geocodeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/reverse_geocode":{"post":{"operationId":"reverse_geocode","summary":"Coordinates → nearest address with road, locality, city, district, state, postcode and country (OpenStreetMap","description":"Coordinates → nearest address with road, locality, city, district, state, postcode and country (OpenStreetMap\n    Nominatim). Use for \"what address is 18.52, 73.86\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"latitude":{"maximum":90,"minimum":-90,"title":"Latitude","type":"number"},"longitude":{"maximum":180,"minimum":-180,"title":"Longitude","type":"number"}},"required":["latitude","longitude"],"title":"reverse_geocodeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/country_codes":{"post":{"operationId":"country_codes","summary":"Dialing code, emergency numbers, postal-code name/format/example, currency and time zone for a country — or","description":"Dialing code, emergency numbers, postal-code name/format/example, currency and time zone for a country — or\n    check a postal code's format. Use for \"emergency number in Japan\", \"how to call India\", \"is 1234 a valid Dutch\n    postcode\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Country (ISO-2 or name); omit to list all.","examples":["India","JP","UAE"],"title":"Country"},"validate_postal":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A postal code to check against the country's format.","title":"Validate Postal"}},"title":"country_codesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}