Validate places in bulk

POST /v1/jobs/validate

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

Overview

Submit 1 to 10,000 places for asynchronous validation. Each downloaded JSON Lines row follows the POST /v1/validate response contract. Save batch_id and poll GET /v1/jobs/{batch_id} after acceptance. For an uncertain submission, retry promptly with the same Idempotency-Key and identical body. Replay only applies while the idempotency record is retained and the job is not cancelled. Reusing a key after cancellation or retention expiry can create new work and charges. While replay applies, a different body returns 409 IDEMPOTENCY_CONFLICT. Use a new key for intentional new work.

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.

Parameters

Name	Location	Required	Type	Description and constraints
`Idempotency-Key`	header	optional	`string \| null`

Request body

required

application/json

Schema: ValidateJobSubmit

Responses

`200`

Successful Response

application/json

Schema: ValidationJobSubmitResponse

`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
`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": "pois.0.poi_name",
      "message": "Field required",
      "type": "missing"
    }
  ]
}

Schemas

ValidateJobSubmit

Type: object

Submit 1 to 10,000 places for validation.

Field	Type	Required	Description and constraints
`pois`	`array of POIValidateRequest`	required	Inline POIs to validate 1 to 10000 items

Example

{
  "pois": [
    {
      "id": "bakery-001",
      "poi_name": "Example Bakery",
      "address": "123 Example Street",
      "country": "US",
      "latitude": 37.7749,
      "longitude": -122.4194
    },
    {
      "id": "cafe-002",
      "poi_name": "Example Cafe",
      "address": "456 Sample Avenue",
      "country": "US",
      "latitude": 37.7755,
      "longitude": -122.4183
    }
  ]
}

ValidationJobSubmitResponse

Type: object

Accepted validation or enrichment job submission.

Field	Type	Required	Description and constraints
`batch_id`	`string`	required
`type`	`string (one of validate, enrich) \| null`	optional
`status`	`string`	required	one of queued, running, completed, failed, cancelled
`created_at`	`string`	required
`total_items`	`integer`	required
`eta_seconds`	`integer`	required
`eta_completion_at`	`string`	required

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
}