---
title: "Validate a place"
method: POST
path: "/v1/validate"
tags: ["core"]
---

# Validate a place

`POST /v1/validate`

## Request

- Base URL: `https://api.voygr.tech`
- URL: `https://api.voygr.tech/v1/validate`
- Auth: API key in header `X-API-Key`

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

## Request body

- POIValidateRequest: Request model for single POI validation.
  - `id` string, nullable: Client-provided identifier
  - `poi_name` string, required: POI name
  - `street` string, nullable: Street address
  - `city` string, nullable: City
  - `region` string, nullable: State/province
  - `postcode` string, nullable: Postal/ZIP code
  - `country` string, nullable: 2-letter ISO country code
  - `address` string, nullable: Unstructured address string. May also be sent as `freeform_address` (input-only alias).
  - `latitude` number, nullable: Latitude in decimal degrees (WGS84). Optional but recommended.
  - `longitude` number, nullable: Longitude in decimal degrees (WGS84). Optional but recommended.

## Response `200`

Successful Response

- POIValidateResponse: Validation results describing existence and operating status separately.
  - `success` boolean, required: Whether validation succeeded
  - `id` string, nullable: Client-provided ID (pass-through)
  - `existence_confidence` number, nullable: Confidence (0-1) that a matching place ever existed at this address. A score of 0.5 or more means we judge that the place exists. Below 0.5 we judge that it does not. 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: 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. closure_confidence sits above 0.5 for 'closed' and below 0.5 for 'open', and is not a probability. 'unknown' means the place exists but the evidence does not say whether it is open or closed; null means no closure assessment, not zero confidence.
    - `status` 'open' | 'closed' | 'unknown' | 'not_exists', required: Operational status. 'open' means assessed as operating. 'closed' means evidence supports closure. 'unknown' means the place exists but the evidence does not say whether it is open or closed, so re-check it later. 'not_exists' means the place was not judged to exist and no closure assessment was made. closure_confidence and closure_reason are null for 'unknown' and 'not_exists'.
    - `closure_confidence` number, nullable, required: How strongly the closure model leans closed (0-1). Above 0.5 when operational_status.status is 'closed', below 0.5 when it is 'open'. On each side, a higher number means a stronger lean towards closed. Rank places with it within one status. The same number means a different chance of closure in different lists, so it is not a probability. It is null, not zero, when the status is 'unknown' or 'not_exists': we make no open or closed call. Use operational_status.status for the decision.
    - `closure_reason` 'permanent' | 'temporary' | 'relocated' | 'replaced' | 'dissolved' | 'unspecified', nullable: 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.
  - `error` string, nullable: Error message if success=false
  - `error_code` string, nullable: Error category code (VALIDATION_ERROR, MODEL_ERROR, EXTERNAL_API_ERROR, etc.)
  - `request_id` string, nullable: Request ID for tracing
  - `validation_timestamp` string, nullable: UTC timestamp when validation was produced (ISO 8601).

## Other responses

- `400`: Invalid request. Correct the fields before retrying.
- `401`: Missing or invalid X-API-Key.
- `402`: The available balance cannot cover the request's credit hold. Nothing ran.
- `403`: The key lacks the entitlement this operation requires.
- `429`: Rate limit exceeded; wait and follow Retry-After when returned. Free keys are limited to 10 requests per second and 120 requests per minute, and can place 1 call at a time, up to 25 calls per day. Paid keys are limited to 10 requests per second and 120 requests per minute. A top-up raises a key's daily cap to 5,000 calls and its concurrent-call ceiling to 10. Enterprise limits are set per contract.
- `502`: The service behind the gateway failed. Nothing is charged; retry later.
- `504`: The service behind the gateway did not answer in time. Nothing is charged; retry later.

## Changes

- **2026-10-29** `03b7688c4c40`: 6 info
  - added the non-success response with the status `401`
  - added the non-success response with the status `402`
  - added the non-success response with the status `403`
  - added the non-success response with the status `429`
  - …2 more
- **2026-09-16** `892990bd38e1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/voygr/apis/voygr-calls-api/changes/v1/validate/post.md)

---

[API](https://skmtc.dev/voygr/apis/voygr-calls-api.md) - [All operations](https://skmtc.dev/voygr/apis/voygr-calls-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voygr/apis/voygr-calls-api/revisions/7199881ed19e?raw)