{ "openapi": "3.1.0", "info": { "title": "MassVerify Solutions API", "version": "1.0.0", "summary": "Find partner fingerprinting locations near a U.S. ZIP code.", "description": "Read-only JSON API from MassVerify Solutions, a Massachusetts background check company. It lists partner locations that collect fingerprints for expedited FBI background checks, nearest first. No authentication. There is no booking or payment API: to start a request, people contact MassVerify by WhatsApp (https://wa.me/18573080309), phone (+1 857-308-0309) or email (info@massverifysolutions.com). Partner locations serve expedited checks only, need a U.S.-issued photo ID, and the person should contact MassVerify before going. MassVerify is not a law firm and gives no legal advice.\n\nVersioning: the major version is in the path (/api/v1/) and every response carries an API-Version header. Within v1, changes are additive only (new optional fields or endpoints); clients must ignore fields they don't know. Breaking changes ship as a new path (/api/v2/). Deprecation: a deprecated version answers with a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) giving its shutdown date, plus a Link header (rel=\"deprecation\") to the documentation, and keeps working for at least 6 months after deprecation is announced. The unversioned paths /api/ and /api/locations/ are permanent aliases of v1.\n\nRate limits: 60 requests per minute per IP address, best-effort (counted per server instance). Every response carries the IETF RateLimit headers; over the limit the API answers 429 with Retry-After. Responses may be cached for an hour.", "contact": { "name": "MassVerify Solutions", "url": "https://massverifysolutions.com/developers/", "email": "info@massverifysolutions.com" } }, "externalDocs": { "description": "Developer and AI agent documentation", "url": "https://massverifysolutions.com/developers/" }, "servers": [ { "url": "https://massverifysolutions.com", "description": "Production" } ], "security": [], "tags": [ { "name": "Fingerprinting", "description": "Where fingerprints can be collected for an FBI background check." }, { "name": "Meta", "description": "About the API itself." } ], "paths": { "/api/v1/locations/": { "get": { "operationId": "findFingerprintingLocations", "tags": [ "Fingerprinting" ], "summary": "Find partner fingerprinting locations near a ZIP code", "description": "Returns up to 8 partner locations within 60 miles of the given U.S. ZIP code, nearest first, for expedited FBI background checks. Addresses only; locations are not named. Partner locations in Woburn and Everett, Massachusetts are never listed. If the ZIP code is a P.O. Box-only ZIP with no map position, the nearest-numbered ZIP is used instead and returned as nearZip. An unknown ZIP returns 200 with an empty list and reason \"zip_not_found\". Data is a stored list refreshed periodically; its date is in updated.", "parameters": [ { "name": "zip", "in": "query", "required": true, "description": "The person's 5-digit U.S. ZIP code.", "schema": { "type": "string", "pattern": "^[0-9]{5}$", "minLength": 5, "maxLength": 5, "examples": [ "02139" ] } } ], "responses": { "200": { "description": "Nearby partner locations (possibly none).", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "description": "Locations near the requested ZIP code.", "required": [ "zip", "locations" ], "properties": { "zip": { "type": "string", "pattern": "^[0-9]{5}$", "description": "The ZIP code that was requested." }, "nearZip": { "type": "string", "pattern": "^[0-9]{5}$", "description": "Present when the requested ZIP is a P.O. Box-only ZIP: the neighbouring ZIP actually used for distances." }, "locations": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/Location" }, "description": "Nearest first; empty when none are within 60 miles or the ZIP is unknown." }, "reason": { "type": "string", "enum": [ "zip_not_found" ], "description": "Present only when the ZIP code could not be found." }, "updated": { "type": "string", "format": "date", "description": "When the stored location list was last collected." } } }, "examples": { "found": { "value": { "zip": "02139", "locations": [ { "address": "770 Massachusetts Ave", "city": "Cambridge", "state": "MA", "zip": "02139", "miles": 0.36, "bearing": 326 } ], "updated": "2026-10-23" } }, "poBox": { "value": { "zip": "02479", "nearZip": "02478", "locations": [ { "address": "10 Court St", "city": "Arlington", "state": "MA", "zip": "02476", "miles": 1.95, "bearing": 39 } ], "updated": "2026-10-23" } }, "unknownZip": { "value": { "zip": "99999", "locations": [], "reason": "zip_not_found" } } } } } }, "400": { "description": "invalid_zip: the zip parameter is missing or is not five digits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_zip", "message": "The zip parameter must be a 5-digit U.S. ZIP code.", "hint": "Call GET /api/v1/locations/?zip=02139 with exactly five digits.", "docs": "https://massverifysolutions.com/developers/" } } } } }, "404": { "description": "not_found: no API endpoint at this address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: only GET and HEAD are accepted; the Allow header lists them.", "headers": { "Allow": { "description": "GET, HEAD", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: more than 60 requests in a minute from this address. Retry after the number of seconds in Retry-After.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "source_unavailable: the stored location list could not be read. Retry later, or contact MassVerify.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/": { "get": { "operationId": "getApiIndex", "tags": [ "Meta" ], "summary": "List the API's endpoints, version and limits", "description": "Returns the API name and version, links to the documentation and this specification, the versioning and rate-limit policy, the endpoints, and MassVerify's contact details. Takes no parameters.", "parameters": [], "responses": { "200": { "description": "API index.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "description": "The API index.", "required": [ "name", "version", "docs", "openapi", "endpoints" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string", "description": "Major API version.", "examples": [ "1" ] }, "docs": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "versioning": { "type": "string", "description": "The versioning and deprecation policy in one sentence." }, "rateLimit": { "type": "object", "properties": { "requests": { "type": "integer" }, "perSeconds": { "type": "integer" }, "scope": { "type": "string" } } }, "endpoints": { "type": "array", "items": { "type": "object", "required": [ "method", "path", "operationId" ], "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "operationId": { "type": "string" }, "example": { "type": "string", "format": "uri" } } } }, "contact": { "type": "object", "properties": { "whatsapp": { "type": "string", "format": "uri" }, "phone": { "type": "string" }, "email": { "type": "string", "format": "email" } } } } } } } }, "404": { "description": "not_found: no API endpoint at this address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: only GET and HEAD are accepted; the Allow header lists them.", "headers": { "Allow": { "description": "GET, HEAD", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: more than 60 requests in a minute from this address. Retry after the number of seconds in Retry-After.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Location": { "type": "object", "description": "A partner location that collects fingerprints for expedited FBI background checks.", "required": [ "address", "city", "state", "zip", "miles", "bearing" ], "properties": { "address": { "type": "string", "description": "Street address.", "examples": [ "770 Massachusetts Ave" ] }, "city": { "type": "string", "examples": [ "Cambridge" ] }, "state": { "type": "string", "description": "Two-letter U.S. state or territory code.", "pattern": "^[A-Z]{2}$", "examples": [ "MA" ] }, "zip": { "type": "string", "description": "The location's 5-digit ZIP code.", "pattern": "^[0-9]{5}$" }, "miles": { "type": "number", "minimum": 0, "maximum": 60, "description": "Straight-line distance from the requested ZIP code's center, in miles." }, "bearing": { "type": "integer", "minimum": 0, "maximum": 359, "description": "Compass direction from the requested ZIP code, in degrees (0 = north, 90 = east)." } } }, "Error": { "type": "object", "description": "Every error response from this API has this shape.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "hint", "docs" ], "properties": { "code": { "type": "string", "enum": [ "invalid_zip", "not_found", "method_not_allowed", "rate_limited", "source_unavailable" ], "description": "Stable, machine-readable error code." }, "message": { "type": "string", "description": "What went wrong, in plain English." }, "hint": { "type": "string", "description": "How to fix or work around it." }, "docs": { "type": "string", "format": "uri", "description": "Documentation link." } } } } } }, "headers": { "API-Version": { "description": "Major version of the API that answered.", "schema": { "type": "string", "examples": [ "1" ] } }, "RateLimit-Policy": { "description": "IETF RateLimit policy: quota (q) per window in seconds (w), per IP address.", "schema": { "type": "string", "examples": [ "\"per-ip\";q=60;w=60" ] } }, "RateLimit": { "description": "IETF RateLimit: remaining requests (r) and seconds until the window resets (t).", "schema": { "type": "string", "examples": [ "\"per-ip\";r=59;t=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed per window (earlier draft field).", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window (earlier draft field).", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window resets (earlier draft field).", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "Deprecation": { "description": "RFC 9745. Present only on a deprecated API version: when it was deprecated.", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594. Present only on a deprecated API version: when it stops working (at least 6 months after deprecation).", "schema": { "type": "string" } } } } }