Validate a place

POST /v1/validate

https://api.voygr.tech/v1/validate

Open in playground

Overview

Validate a place's existence and operating status using evidence about the place.

Authentication

• API key in header X-API-Key: Your customer API key (pk_live_...), sent on every request. Self-serve at https://api.voygr.tech/checkout.

Request body

required

application/json

Schema: POIValidateRequest

Responses

200

Successful Response

application/json

Schema: POIValidateResponse

400

Invalid request. Correct the fields before retrying.

application/json

Schema: object | object

Option 1 fields

Field	Type	Required	Description and constraints
success	boolean	required	constant False
error	string	required
error_code	string	required	constant VALIDATION_ERROR
request_id	string | null	required
validation_timestamp	string	required
detail	array of object	required	Item fields Field Type Required Description and constraints field string required message string required type string required

Option 2 fields

Field	Type	Required	Description and constraints
detail	object	required	Gateway rejection, for example an invalid Idempotency-Key header. Fields Field Type Required Description and constraints error string required error_code string optional

One of

• Option 1: requires success, error, error_code, request_id, validation_timestamp, detail
• Option 2: requires detail

invalidinput

{
  "success": false,
  "error": "Invalid input provided",
  "error_code": "VALIDATION_ERROR",
  "request_id": "example-request-id",
  "validation_timestamp": "2026-09-16T12:00:00Z",
  "detail": [
    {
      "field": "poi_name",
      "message": "Field required",
      "type": "missing"
    }
  ]
}

Schemas

POIValidateRequest

Type: object

Request model for single POI validation.

Field	Type	Required	Description and constraints
id	string (max length 100) | null	optional	Client-provided identifier
poi_name	string	required	POI name length 1 to 200
street	string (max length 300) | null	optional	Street address
city	string (max length 200) | null	optional	City
region	string (max length 200) | null	optional	State/province
postcode	string (max length 40) | null	optional	Postal/ZIP code
country	string | null	optional	2-letter ISO country code
address	string (max length 500) | null	optional	Unstructured address string. May also be sent as freeform_address (input-only alias).
latitude	number (-90.0 to 90.0) | null	optional	Latitude in decimal degrees (WGS84). Optional but recommended.
longitude	number (-180.0 to 180.0) | null	optional	Longitude in decimal degrees (WGS84). Optional but recommended.

Example

{
  "id": "bakery-001",
  "poi_name": "Example Bakery",
  "address": "123 Example Street",
  "country": "US",
  "latitude": 37.7749,
  "longitude": -122.4194
}

POIValidateResponse

Type: object

Validation results describing existence and operating status separately.

Field	Type	Required	Description and constraints
success	boolean	required	Whether validation succeeded
id	string | null	optional	Client-provided ID (pass-through)
existence_confidence	number | null	optional	Confidence (0-1) that a matching place ever existed at this address. A closed place can still have high existence confidence. This does not describe whether it is operating today. Interpret closure only when existence is established; use operational_status.status for the decision.
operational_status	OperationalStatusBlock | null	optional	Operating-status result. Use operational_status.status for the decision.
error	string | null	optional	Error message if success=false
error_code	string | null	optional	Error category code (VALIDATION_ERROR, MODEL_ERROR, EXTERNAL_API_ERROR, etc.)
request_id	string | null	optional	Request ID for tracing
validation_timestamp	string | null	optional	UTC timestamp when validation was produced (ISO 8601).

OperationalStatusBlock

Type: object

Operational status for a place. Use operational_status.status for the decision. A closed verdict is evidence-backed, not a decision based on score alone. Confidence is not a cross-status decision threshold. 'unknown' means undetermined; null means no closure assessment, not zero confidence.

Field	Type	Required	Description and constraints
status	string	required	Operational status: 'open' means assessed as operating; 'closed' means evidence supports closure; 'unknown' means undetermined and worth re-checking; 'not_exists' means the place was not judged to exist and no closure assessment was made. closure_confidence and closure_reason are null for 'not_exists'. one of open, closed, unknown, not_exists
closure_confidence	number | null	required	Confidence in a closed verdict (0-1). Use operational_status.status for the decision; do not use confidence as a cross-status threshold or rank non-closed places by it. Null for 'not_exists' means no closure assessment, not zero confidence.
closure_reason	string (one of permanent, temporary, relocated, replaced, dissolved, unspecified) | null	optional	What kind of evidence closed the place: permanent, temporary, relocated, replaced, dissolved, or unspecified. Null whenever status is not 'closed' - an open or unknown verdict has no closure to attribute.

On this page

• Overview
• Authentication
• Request body
• Responses
• Schemas